docs(工程文档): 格式化文档表格

Co-authored-by: LingandRX <LingandRX@users.noreply.github.com>
docs(工程文档): 同步当前架构说明
2026-06-26 08:43:20 +00:00 · 2026-06-26 08:42:28 +00:00
225 changed files with 5676 additions and 6596 deletions
@@ -1,17 +0,0 @@
 # CI/CD 配置
 ## CI 步骤
 严格顺序，任一步骤失败则停止并标记 CI 失败：
 1. `setup`（安装依赖、`wxt prepare`）
 2. 并行运行 `lint`、`typecheck`、`test`（三者全部通过才继续）
 3. `build`（仅当步骤 2 全部成功时执行）
 ## Pre-commit Hook
 `.husky/pre-commit` 调用 `lint-staged`，任一步骤返回非零则终止提交：
 1. 代码文件 (`*.{ts,tsx,js,jsx,mjs}`)：运行 `eslint --fix --max-warnings=0 --no-warn-ignored`；若失败则终止并报告错误
 2. 同一代码文件：运行 `prettier --write`
 3. 其他文件 (`*.{json,css,scss,md}`)：运行 `prettier --write`
@@ -265,11 +265,12 @@ const visibleSet = useMemo(() => new Set<string>(visiblePages), [visiblePages]);
 2. 第三方库（图标、UI 库等）
 3. 业务 Provider / Context
 4. 配置 / 存储
-5. 本地页面组件
+5. i18n
-6. UI 组件
+6. 本地页面组件
-7. 工具函数 / Hook
+7. UI 组件
-8. 类型
+8. 工具函数 / Hook
-9. 常量
+9. 类型
 10. 常量
 ```typescript
 // 1. React 核心
@@ -283,16 +284,18 @@ import { useThemeMode } from '@/providers/ThemeModeProvider';
 // 4. 配置 / 存储
 import { FeatureConfig, FEATURES } from '@/config/features';
 import { storageUtil } from '@/utils/chromeStorage';
-// 5. 本地组件
+// 5. i18n
 import { useI18n } from '@/utils/chromeI18n';
 // 6. 本地组件
 import TextMode from './TextMode';
 import { ZONES } from './constants';
-// 6. UI 组件
+// 7. UI 组件
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
 import { Button } from '@/components/ui/button';
-// 7. 工具函数 / Hook
+// 8. 工具函数 / Hook
 import { cn } from '@/lib/utils';
 import { useStorageState } from '@/utils/useStorageState';
-// 8. 类型
+// 9. 类型
 import type { PageType, StorageSchema } from '@/types/storage';
 ```
@@ -556,7 +559,7 @@ describe('SwitchButtonGroup 组件', () => {
 - 使用 `vi.mock()` 进行模块级 Mock
 - 使用 `vi.fn()` 进行函数级 Mock
 - 使用 `vi.useFakeTimers()` 控制时间
- **避免重复 mock `vitest.setup.ts` 中已有的内容**（chrome API、matchMedia 等）
+- **避免重复 mock `vitest.setup.ts` 中已有的内容**（chrome API、i18n、matchMedia 等）
 ```typescript
 // ✅ 模块级 Mock
@@ -654,7 +657,7 @@ export function useTimestampConverter(): UseTimestampConverterReturn { ... }
 ```
 src/utils/useStorageState.ts          — Chrome Storage 状态持久化
-src/utils/syncSnapshot.ts             — localStorage 快照读取
+src/utils/chromeI18n.ts               — chrome.i18n wrapper 与 useI18n
 src/utils/useContextMenuData.ts       — 右键菜单数据
 src/utils/useDebounce.ts              — 防抖
 src/pages/Timestamp/useTimestampConverter.ts    — 页面级 Hook
@@ -663,50 +666,52 @@ src/pages/StorageCleaner/useStorageCleaner.ts  — 页面级 Hook
 ---
-## 9. UI 文案规范
+## 9. 国际化规范
-项目已移除 `chrome.i18n`，所有 UI 文案直接在代码中使用中文。
+### 9.1 翻译键格式
-### 9.1 功能元数据
+- 使用 Chrome 扩展标准的 `chrome.i18n`，通过 `src/utils/chromeI18n.ts` 暴露 `useI18n`
 - 翻译 key 存放在 `public/_locales/zh_CN/messages.json`
 - 直接 key：`t('dashboard_title')` → 查找 `dashboard_title`
 - 命名空间兼容写法：`t('common:buttons.search')` → 查找 `common_buttons_search`
 - 命名空间参数：`useI18n(['common', 'features'])` 会尝试 `common_key`、`features_key`
-功能名称与描述在 `config/features.tsx` 的 `FEATURES` 数组中定义：
+### 9.2 翻译文件结构
-```typescript
+```
-{
+public/_locales/zh_CN/messages.json        — Chrome 扩展默认语言包
-  key: 'timestamp',
+wxt.config.ts                              — manifest.default_locale = 'zh_CN'
  label: '时间戳转换',
  description: '日期与时间戳互转',
  defaultVisible: true,
  component: TimestampPage,
 }
 ```
-Dashboard 卡片、TopBar 搜索等功能从此处读取 `label` / `description`。
+### 9.3 使用方式
 ### 9.2 页面与组件文案
 - 页面标题、按钮、提示信息等直接在 JSX 或 `constants.ts` 中写中文
 - 错误消息可在 Hook 中定义，或使用常量映射
 - Toast 通知使用 `sonner` 的 `toast()`，文案写在调用处或常量中
 ```typescript
-// ✅ 页面组件 — 直接写中文
+// ✅ 页面组件 / 子组件 — 使用 useI18n
 import { useI18n } from '@/utils/chromeI18n';
 export default function Index() {
-  return <h1 className="font-bold text-sm">时间戳转换</h1>;
+  const { t } = useI18n('timestamp');
  return <h1>{t('timestamp_title')}</h1>;
 }
-// ✅ 常量文件 — 可复用文案
+// ✅ 带占位符
-export const ERROR_MESSAGES = {
+export function NotFoundMessage() {
-  invalidInput: '输入格式无效',
+  const { t } = useI18n('router');
-  conversionFailed: '转换失败',
+  return <p>{t('router_notFoundDescription', { entryPointType: 'popup' })}</p>;
-} as const;
+}
 ```
-### 9.3 添加新功能文案
+### 9.4 添加新翻译
-1. 在 `config/features.tsx` 填写 `label` 和 `description`
+1. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome 扩展格式的消息：
-2. 在页面组件、`constants.ts` 或 Hook 中编写 UI 文案
+   ```json
-3. 扩展名称与描述在 `wxt.config.ts` 的 `manifest` 中维护
+   {
     "feature_title": { "message": "功能标题" },
     "feature_description": { "message": "功能描述" }
   }
   ```
 2. key 使用下划线分隔，避免点号；`useI18n` 会把 `namespace:key.path` 兼容转换为下划线
 3. `chrome.i18n` 不支持运行时动态切换语言，浏览器语言变化后需要刷新扩展页面
 ---
@@ -759,18 +764,6 @@ const [themeMode, setThemeMode, isInitialized] = useStorageState(
 );
 ```
 ### 10.4 首屏快照与初始化防覆盖
 Chrome Storage 读取是异步的。项目通过 `localStorage` 快照（键名 `snapshot/{storageKey}`）提供同步初始值，消除首屏闪烁。
 | 模块                | 快照工具           | 防覆盖机制                                                                                |
 | ------------------- | ------------------ | ----------------------------------------------------------------------------------------- |
 | `RouterProvider`    | `syncSnapshot.ts`  | `canPersistRef`（加载成功后才写入）、`hasUserNavigatedRef`（用户导航后不被 storage 覆盖） |
 | `useStorageState`   | `syncSnapshot.ts`  | `loadSucceededRef` 或 `userModifiedRef` 为 true 时才写入                                  |
 | `ThemeModeProvider` | `themeSnapshot.ts` | `hasUserSetMode`（用户切换主题后不被 storage 覆盖）                                       |
 新增持久化状态时，应遵循相同模式：同步快照作初始 state → 异步加载 storage → 加载成功或用户修改后才允许写入。
 ---
 ## 11. 页面开发规范
@@ -853,21 +846,24 @@ export default function DashboardPage() { ... }
 #### 组件职责
-`index.tsx` 只负责两件事：
+`index.tsx` 只负责三件事：
-1. **调用业务 Hook** 获取状态和操作方法
+1. **获取翻译函数**（`useI18n`）
-2. **渲染 UI 布局**（纯展示，无业务逻辑）
+2. **调用业务 Hook** 获取状态和操作方法
 3. **渲染 UI 布局**（纯展示，无业务逻辑）
 ```typescript
 // ✅ 标准页面入口模板
 import { useI18n } from '@/utils/chromeI18n';
 import { useFeatureName } from './useFeatureName';
 export default function Index() {
  const { t } = useI18n('featureName');
  const { state, actions } = useFeatureName();
  return (
    <div className="p-4 w-full flex flex-col space-y-4 select-none">
-      {/* 纯 UI 渲染，文案直接写中文 */}
+      {/* 纯 UI 渲染 */}
    </div>
  );
 }
@@ -911,22 +907,25 @@ export function useTimestampConverter(): UseTimestampConverterReturn {
 ```typescript
 export function useFeatureName(): UseFeatureNameReturn {
-  // 1. 基础 state（useState）
+  // 1. i18n
  const { t } = useI18n('featureName');
  // 2. 基础 state（useState）
  const [mode, setMode] = useState<Mode>('default');
  const [input, setInput] = useState('');
-  // 2. 持久化 state（useStorageState）
+  // 3. 持久化 state（useStorageState）
  const [pageMode, setPageMode] = useStorageState('feature/pageMode', 'default', isValidMode);
-  // 3. 衍生数据（useMemo）— 响应式计算管线
+  // 4. 衍生数据（useMemo）— 响应式计算管线
  const result = useMemo(() => {
    // 自动计算，无需手动点击"转换"按钮
  }, [input, mode]);
-  // 4. 事件处理（useCallback）
+  // 5. 事件处理（useCallback）
  const handleAction = useCallback(() => { ... }, [deps]);
-  // 5. 副作用（useEffect）— 防抖、初始化、清理
+  // 6. 副作用（useEffect）— 防抖、初始化、清理
  useEffect(() => { ... }, [deps]);
  // 7. 右键菜单数据（页面需要时）
@@ -996,7 +995,7 @@ interface ResultViewProps extends React.HTMLAttributes<HTMLDivElement> {
 // ✅ 使用 React.memo + displayName
 const ResultView = React.memo(
  ({ result, mode, showEmptyPlaceholder = false, className, ...props }: ResultViewProps) => {
-    // 文案直接写中文或使用 constants
+    const { t } = useI18n('featureName');
    // ...
  },
 );
@@ -1006,7 +1005,7 @@ export default ResultView;
 #### 子组件内可以使用 Hook
-子组件可以独立调用 `useRouter`、`useThemeMode`、`toast` 等全局 Hook/API，**不需要**通过 props 从父组件传递。
+子组件可以独立调用 `useI18n`、`useSnackbar` 等全局 Hook，**不需要**通过 props 从父组件传递翻译函数或 toast 方法。
 ---
@@ -1043,6 +1042,7 @@ const isValidMode = (val: unknown): val is PageMode =>
  typeof val === 'string' && (VALID_MODES as readonly string[]).includes(val);
 export default function Index() {
  const { t } = useI18n('featureName');
  const [pageMode, setPageMode] = useStorageState('feature/pageMode', 'modeA', isValidMode);
  return (
@@ -1050,8 +1050,8 @@ export default function Index() {
      <SwitchButtonGroup
        value={pageMode}
        options={[
-          { value: 'modeA', label: '模式 A' },
+          { value: 'modeA', label: t('feature:modeA') },
-          { value: 'modeB', label: '模式 B' },
+          { value: 'modeB', label: t('feature:modeB') },
        ]}
        onChange={(v: PageMode) => setPageMode(v)}
        size="small"
@@ -1082,12 +1082,12 @@ export default function Index() {
 新增功能页面时，逐项确认：
 1. ✅ 在 `types/storage.d.ts` 添加 `PageType` 联合类型
-2. ✅ 在 `config/features.tsx` 注册 `FEATURES` 配置（key、label、description、icon、三种渲染模式组件）
+2. ✅ 在 `config/features.tsx` 注册 `FEATURES` 配置（key、labelKey、icon、三种渲染模式组件）
 3. ✅ 创建页面目录，使用 `Index` 作为组件名
 4. ✅ 业务逻辑提取到 `useXxx.ts` Hook（index.tsx 不超过 150 行）
 5. ✅ 需要持久化的 UI 状态使用 `useStorageState`
 6. ✅ 常量 ≥3 个时提取到 `constants.ts`
-7. ✅ 在页面组件或 `constants.ts` 中编写 UI 文案
+7. ✅ 在 `public/_locales/zh_CN/messages.json` 添加翻译
 8. ✅ 创建 `__tests__/index.test.tsx` 测试文件
 9. ✅ 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
 10. ✅ 运行 `npm run lint && npm run typecheck && npm run test` 全部通过
@@ -1108,7 +1108,7 @@ export default function Index() {
 | `src/utils/`         | 工具函数与服务抽象                                           |
 | `src/types/`         | TypeScript 类型声明                                          |
 | `src/lib/`           | 通用工具函数与生成器库（cn、utils、generators）              |
-| `public/`            | 静态资源（图标等）                                           |
+| `public/`            | 静态资源与 Chrome `_locales` 语言包                          |
 ---
@@ -0,0 +1,140 @@
 # Copilot 指令
 基于 WXT 框架的浏览器扩展项目（React 19 + TypeScript），为开发者和测试人员提供效率工具：时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等。
 ## 核心命令
 ```bash
 npm run dev              # Chrome 开发模式（支持 HMR）
 npm run dev:firefox      # Firefox 开发模式
 npm run build            # Chrome 生产构建
 npm run build:firefox    # Firefox 生产构建
 npm run zip              # 打包 Chrome 扩展（.output/*.zip）
 npm run zip:firefox      # 打包 Firefox 扩展
 npm run lint             # ESLint 检查（--max-warnings=0）
 npm run typecheck        # TypeScript 类型检查（tsc --noEmit）
 npm run test             # 运行全部单元测试（vitest run）
 npm run test:watch       # Vitest 监视模式
 npm run test:coverage    # 带覆盖率的测试
 ```
 运行单个测试文件：`npx vitest run path/to/file.test.ts`
 修改 `package.json` 后需运行 `npm install`（会自动触发 `postinstall` → `wxt prepare` 重新生成 `.wxt/` 类型声明）。
 ## CI 流水线（GitHub Actions）
 严格顺序门控，任一步骤失败则终止：
 1. **setup** — 安装依赖，缓存 `node_modules`
 2. **lint**、**typecheck**、**test** — 三者并行运行，全部通过才继续
 3. **build** — Chrome + Firefox 矩阵构建（仅当步骤 2 全部通过时执行）
 Pre-commit 钩子（`.husky/pre-commit` → `lint-staged`）：
 1. 代码文件（`*.{ts,tsx,js,jsx,mjs}`）：运行 `eslint --fix --max-warnings=0`
 2. 同一代码文件：运行 `prettier --write`
 3. 其他文件（`*.{json,css,scss,md}`）：运行 `prettier --write`
 ## 项目架构
 ### 路由（不使用 React Router）
 路由完全通过 `config/features.tsx` 中的 `FEATURES` 数组管理。每个功能定义一个 `key`（类型为 `types/storage.d.ts` 中的 `PageType`）和三个懒加载组件，分别对应 `popup`、`sidepanel`、`tab` 三种渲染模式。`providers/RouterProvider.tsx` 中的 `RouterProvider` 根据存储状态渲染当前页面。
 存在三套独立的路由作用域：`app/popupRoute`、`app/sidepanelRoute`、`app/tabRoute`，各自维护独立的可见页面列表和页面排序。
 ### 存储
 所有 Chrome Storage 键必须在 `types/storage.d.ts` 的 `StorageSchema` 中声明，键名使用 kebab-case 格式（如 `app/currentRoute`）。使用 `utils/chromeStorage.ts` 中的类型安全封装（`storageUtil.get/set/remove`）。
 Router 同时使用 `chrome.storage.local` 持久化和 `localStorage` 快照来消除首屏闪烁。
 ### 扩展通信
 使用 `@webext-core/messaging`。通信协议在 `utils/messages.ts` 中通过 `ProtocolMap` 定义。使用该模块导出的 `sendMessage` / `onMessage`，不要直接使用原生 `chrome.runtime.sendMessage`。
 ### 页面组件模式
 功能页面遵循 **UI + Hook 分离** 模式，详见 [CODING_STANDARDS.md § 11](./CODING_STANDARDS.md#11-页面开发规范)：
 ```
 pages/FeatureName/
 ├── index.tsx              # UI 组件（纯展示，使用 shadcn/ui 组件）
 ├── useFeatureName.ts      # 业务逻辑 Hook（状态管理 + 转换逻辑）
 └── constants.ts           # 常量定义（可选）
 ```
 - 页面组件调用 `useI18n('featureName')` 获取翻译函数
 - Hook 负责所有状态管理，通过返回值暴露给页面
 - 子组件可进一步拆分（如 `LiveClock.tsx`、`ResultView.tsx`）
 ### 新功能开发清单
 1. 在 `types/storage.d.ts` 的 `PageType` 联合类型中添加新成员
 2. 在 `config/features.tsx` 的 `FEATURES` 数组中添加配置（key、翻译键、图标、三种渲染模式组件）
 3. 在 `pages/` 目录创建页面组件（懒加载）：
   - `index.tsx` — 使用 `useI18n` 的 UI 组件
   - `useFeatureName.ts` — 业务逻辑 Hook
   - `constants.ts` — 常量（可选）
 4. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome i18n 翻译
 5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
 6. 添加对应的单元测试
 ## 关键规范
 > 完整的代码编写规范详见 [CODING_STANDARDS.md](./CODING_STANDARDS.md)。
 ### 浏览器 API
 始终使用 `wxt/browser` 导出的 `browser` 对象，而非原生 `chrome` API，以确保跨浏览器兼容性。
 ### 路径别名
 `@/` 映射到项目根目录（已在 tsconfig 和 vitest.config 中配置）。跨目录导入使用 `@/` 绝对别名，同目录导入使用 `./` 相对路径。
 ### UI 组件
 - 使用 `components/ui/` 下的 shadcn/ui 组件（button、dialog、select、input 等）
 - 图标：`lucide-react`
 - 样式：Tailwind CSS + `@/lib/utils` 中的 `cn()` 工具函数（clsx + tailwind-merge）
 - 主题：使用 shadcn/ui 语义化 token（`bg-background`、`text-foreground`、`border-border` 等），禁止硬编码颜色
 ### 代码分割
 `wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组 vendor 依赖（vendor-react、vendor-qr、vendor-dnd），无需手动配置。
 ### 代码风格
 - 禁止使用 `any`（测试文件除外）
 - 未使用的变量/参数：使用 `_` 前缀（如 `_unused`）
 - Prettier：100 字符宽、单引号、尾逗号 all、LF 换行
 - ESLint 使用 `typescript-eslint` 的 `projectService: true`
 - 导出模式：页面组件 default export，工具函数/Hook 命名导出，UI 组件 forwardRef + 命名导出
 ### 测试
 - 环境：jsdom
 - 全局变量：`vitest/globals`（describe、it、expect 等无需导入）
 - Setup 文件：`vitest.setup.ts` 自动 mock 以下内容：
  - `chrome.*` / `browser.*` API（storage、tabs、runtime、cookies 等）
  - `@/utils/chromeI18n`（从 `public/_locales/zh_CN/messages.json` 加载真实翻译）
  - `window.matchMedia`
 - 测试文件命名：`__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
 - 使用 `vi.mock()` 进行模块级 mock；避免重复 mock `vitest.setup.ts` 中已有的内容
 - 测试工具：`@testing-library/react` + `@testing-library/user-event`
 ### 国际化（i18n）
 - 使用 Chrome 扩展标准 `chrome.i18n`
 - 默认语言目录：`public/_locales/zh_CN/messages.json`
 - 使用方式：`import { useI18n } from '@/utils/chromeI18n'`
 - 翻译键格式：直接 key（如 `timestamp_title`）；兼容 `namespace:key.path` 并转换为下划线
 - 回退策略：缺失翻译返回 key 本身，并在开发模式下记录 warning
 - 限制：`chrome.i18n` 跟随浏览器语言，不能在运行时动态切换语言
 ### WXT 生成文件
 - `.wxt/` 目录由 `postinstall`（`wxt prepare`）自动生成，包含 TypeScript 类型声明和扩展 tsconfig
 - 生产构建输出到 `.output/` 目录
 - `tsconfig.json` 继承自 `./.wxt/tsconfig.json`
@@ -16,64 +16,48 @@ npm run typecheck        # tsc --noEmit
 npm run test             # vitest run (单次执行)
 npm run test:watch       # vitest 监视模式
 npm run test:coverage    # 带覆盖率的测试
 npx vitest run path/to/file.test.ts   # 运行单个测试文件
 npx wxt prepare          # 重新生成 .wxt/ 类型声明（npm install 时 postinstall 会自动执行）
 ```
-修改 `package.json` 或首次克隆仓库后需执行 `npm install`，会自动触发 `postinstall` → `wxt prepare`。
+运行单个测试: `npx vitest run path/to/file.test.ts`
 ## 验证流程
-详见 [CI 配置](./.github/CI.md)。本地与 CI 的检查层次如下。
+CI 步骤（严格顺序，任一步骤失败则停止并标记 CI 失败）：
-### Pre-commit（`.husky/pre-commit`）
+1. `setup`（安装依赖、`wxt prepare`）
 2. 并行运行 `lint`、`typecheck`、`test`（三者全部通过才继续）
 3. `build`（仅当步骤 2 全部成功时执行）
-1. 后台运行 `tsc --noEmit`（不阻塞提交，结果输出到 stderr）
+Pre-commit hook（`.husky/pre-commit` 调用 `lint-staged`，任一步骤返回非零则终止提交）：
 2. 前台运行 `lint-staged`：
   - 代码文件 (`*.{ts,tsx,js,jsx,mjs}`)：`eslint --fix --max-warnings=0`，再 `prettier --write`
   - 其他文件 (`*.{json,css,scss,md}`)：`prettier --write`
-### Pre-push（`.husky/pre-push`）
+1. 代码文件 (`*.{ts,tsx,js,jsx,mjs}`)：运行 `eslint --fix --max-warnings=0 --no-warn-ignored`；若失败则终止并报告错误
 2. 同一代码文件：运行 `prettier --write`
 3. 其他文件 (`*.{json,css,scss,md}`)：运行 `prettier --write`
-1. 全项目 `tsc --noEmit`（阻塞推送）
+## WXT 生成文件
 2. 对本次推送相对 upstream（或 `origin/main`）变更的 `*.{ts,tsx,js,jsx,mjs}` 文件运行 `eslint --max-warnings=0`
-### CI（GitHub Actions）
+- `.wxt/` 目录由 `postinstall` 自动执行 `wxt prepare` 生成，包含 TypeScript 类型声明和扩展的 tsconfig。
-
+- 生产构建输出到 `.output/` 目录。
-1. `setup` — 安装依赖
+- `tsconfig.json` 继承自 `./.wxt/tsconfig.json`。
 2. 并行 `lint`、`typecheck`（含 `wxt prepare`）、`test`
 3. `build` — Chrome + Firefox 矩阵构建（仅当步骤 2 全部通过）
 ## 项目结构
 ```
-src/                     # 源代码根目录
+src/                   # 源代码根目录
-  config/features.tsx      # 功能定义（路由 + 元数据的单一事实来源）
+  config/features.tsx    # 功能定义（路由 + 元数据的单一事实来源）
-  entrypoints/             # 扩展入口点 (popup/, sidepanel/, background.ts, content.ts)
+  entrypoints/           # 扩展入口点 (popup/, sidepanel/, background.ts, content.ts)
-  layout/                  # 应用壳层布局（TopBar 导航、搜索、主题切换）
+  pages/                 # 功能页面组件 (懒加载)
-  pages/                   # 功能页面组件 (懒加载)
+  components/            # 可复用 UI 组件
-  components/              # 可复用 UI 组件
+  components/ui/         # shadcn/ui 基础组件 (button, dialog, select 等)
-  components/ui/           # shadcn/ui 基础组件 (button, dialog, select 等)
+  providers/             # React Context (Router, Theme 等)
-  providers/               # React Context (Router, Theme 等)
+  hooks/                 # 自定义 React Hooks
-  hooks/                   # 自定义 React Hooks
+  utils/                 # 工具函数与服务抽象
-  utils/                   # 工具函数与服务抽象
+  types/                 # TypeScript 类型声明
-  types/                   # TypeScript 类型声明
+  lib/                   # 通用工具函数（cn、utils）
-  lib/                     # 通用工具函数（cn、utils）及数据生成器定义
+  workers/               # Web Worker（数据生成等耗时任务）
-  workers/                 # Web Worker（数据生成等耗时任务）
+public/                # 静态资源（图标、_locales 等）
 spec/                    # 功能规格、修复方案与验收标准（见 spec/README.md）
 public/                  # 静态资源（图标等）
 .wxt/                    # wxt prepare 自动生成，含类型声明与扩展 tsconfig（勿手动编辑）
 .output/                 # 生产构建输出目录
 ```
 ### layout/
 应用壳层，与 popup / sidepanel / tab 入口绑定。当前含 `TopBar/`（搜索、主题切换、返回导航、「在标签页打开」），遵循与 `pages/` 相同的 UI + Hook 模式。详见 [layout/README.md](./src/layout/README.md)。
 ### spec/
 功能规格与验收标准文档，重大改动前优先查阅。索引见 [spec/README.md](./spec/README.md)。
 ### 页面组件模式
 典型功能页面遵循 **UI + Hook 分离** 模式。详见 [CODING_STANDARDS.md § 11](./.github/CODING_STANDARDS.md#11-页面开发规范)。
@@ -89,7 +73,7 @@ src/pages/FeatureName/
 - 页面入口组件统一命名为 `Index`，通过 `export default function Index()` 导出
 - Hook 负责所有状态管理和业务逻辑，通过返回值暴露给页面
- 子组件可以独立调用全局 Hook
+- 子组件可以独立调用 `useI18n` 等全局 Hook
 - 当 `index.tsx` 超过 150 行时，必须拆分为 UI + Hook 模式
 - 复杂页面可增加 `contexts/`、`hooks/`、`components/` 子目录
@@ -128,49 +112,60 @@ src/types/
 ## 关键架构决策
 **路由**: 不使用 React Router。通过 `src/config/features.tsx` 的 `FEATURES` 数组管理，`RouterProvider` 根据 `PageType`
-渲染对应组件。支持三种渲染模式：popup（弹窗）、sidepanel（侧边栏）和 tab（浏览器新标签页，TopBar「在标签页打开」调用 `openExtensionPage('popup.html', { mode: 'tab' })`，由 `getEntryPointType()` 根据 URL 参数 `mode=tab` 识别）。
+渲染对应组件。支持三种渲染模式：popup（弹窗）、sidepanel（侧边栏）和 browser-tab（浏览器新标签页，通过 `open_in_tab` 打开）。
 每种模式有独立的路由和可见页面配置（`app/popupRoute`、`app/sidepanelRoute`、`app/tabRoute` 等）。
 **存储**: 所有 Chrome Storage 键必须在 `src/types/storage.d.ts` 的 `StorageSchema` 中定义，键名使用 kebab-case 格式（如 `app/currentRoute`）。
-使用 `src/utils/chromeStorage.ts` 及其 Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 快照（`snapshot/{key}`）消除首屏闪烁。
+使用 `src/utils/chromeStorage.ts` 及其 Hook。Router 同时使用 `chrome.storage.local` 和 `localStorage` 做快照以消除首屏闪烁。
-异步加载完成前禁止写入 storage（`RouterProvider` 的 `canPersistRef`、`useStorageState` 的 `loadSucceededRef`），避免默认值覆盖已有数据。
+修改 StorageSchema 时，必须在 `src/utils/chromeStorage.ts` 添加版本迁移函数，并在测试中覆盖迁移场景。
 **通信**: 使用 `@webext-core/messaging`，协议定义在 `src/utils/messages.ts`。
-**路径别名**: `@/` 映射到 `src/` 目录（已在 `.wxt/tsconfig.json` 和 `vitest.config.ts` 中配置）。项目根目录使用 `@@/`。
+**路径别名**: `@/` 映射到项目根目录 (已在 tsconfig 和 vitest.config 中配置)。
 **浏览器兼容**: 优先使用 `wxt/browser` 导出的 `browser` 对象，而非原生 `chrome` API。
 **代码分割**: `wxt.config.ts` 通过 `manualChunksForHtmlOnly()` 自动分组依赖（vendor-react、vendor-qr、vendor-dnd 等），无需手动配置。
 ## 测试环境
 - 环境: jsdom
 - 全局变量: `vitest/globals` (describe, it, expect 等无需导入)
 - Setup 文件: `vitest.setup.ts` 自动 mock:
  - `chrome.*` / `browser.*` API (storage, tabs, runtime, cookies 等)
  - `@/utils/chromeI18n` (从 `public/_locales/zh_CN/messages.json` 加载真实翻译)
  - `window.matchMedia`
 - 测试文件命名: `__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
 - Mock 模式: 使用 `vi.mock()` 进行模块级 mock，避免在测试文件中重复 mock 代码
 - 测试工具: `@testing-library/react` + `@testing-library/user-event` 进行组件测试
-## UI 文案
+## i18n (chrome.i18n)
-项目已移除 `chrome.i18n`，UI 文案直接在代码中使用中文。
+项目使用 Chrome 扩展标准的 `chrome.i18n` API 进行本地化，通过 `src/utils/chromeI18n.ts` 提供类型安全的 React Hook 包装。
- **功能元数据**: `src/config/features.tsx` 的 `FEATURES` 数组定义 `label`、`description`（用于 Dashboard 卡片与搜索）
+- **翻译文件**: `public/_locales/zh_CN/messages.json`（Chrome 扩展标准格式）
- **页面文案**: 在组件 JSX、`constants.ts` 或 Hook 中直接写中文
+- **默认语言**: `zh_CN`（在 `wxt.config.ts` 的 `manifest.default_locale` 中配置）
- **Manifest 文案**: 扩展名称与描述在 `wxt.config.ts` 的 `manifest` 中维护
+- **使用方式**: `import { useI18n } from '@/utils/chromeI18n'`
- **Toast / 错误提示**: 在 Hook 或 `constants.ts` 中定义，使用 `sonner` 的 `toast()` 展示
+- **翻译键格式**:
  - 直接 key: `t('dashboard_title')` → 查找 `dashboard_title`
  - 命名空间格式（兼容旧用法）: `t('common:buttons.search')` → 查找 `common_buttons_search`
  - 带命名空间参数: `useI18n(['common', 'features'])`，会自动尝试 `common_key`、`features_key`
 - **占位符支持**: `t('router_notFoundDescription', { entryPointType: 'popup' })`
 - **Hook 返回值**: `{ t, i18n: { language, changeLanguage }, isLoaded }`
 - **回退策略**: 当翻译 key 未命中时，返回 key 本身（开发模式下在控制台记录 warning）
 - **限制**: `chrome.i18n` 无法动态切换语言，语言跟随浏览器设置，切换后需刷新页面
 ## 新功能开发清单
 1. 在 `src/types/storage.d.ts` 添加 `PageType` 联合类型
-2. 在 `src/config/features.tsx` 的 `FEATURES` 数组添加配置（指定 key、label、description、图标、三种渲染模式的组件）
+2. 在 `src/config/features.tsx` 的 `FEATURES` 数组添加配置（指定 key、翻译键、图标、三种渲染模式的组件）
 3. 在 `src/pages/` 创建页面组件 (懒加载)：
-   - `index.tsx` — UI 组件（纯展示）
+   - `index.tsx` — UI 组件，使用 `useI18n` 获取翻译
   - `useFeatureName.ts` — 业务逻辑 Hook
-   - `constants.ts` — 常量定义（可选，≥3 个常量时创建）
+   - `constants.ts` — 常量（可选）
-4. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
+4. 在 `public/_locales/zh_CN/messages.json` 添加翻译
-5. 添加对应的单元测试
+5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
 6. 添加对应的单元测试
 ## 代码规范
@@ -179,9 +174,9 @@ src/types/
 - 样式: 使用 Tailwind CSS + shadcn/ui (通过 `className` 和 `cn()` 工具)
 - UI 组件: 优先使用 `src/components/ui/` 下的 shadcn/ui 组件 (button, dialog, select 等)
 - 图标: 使用 `lucide-react` 图标库
- 格式: Prettier [配置](./.prettierrc)
+- 格式: Prettier (`.prettierrc`: 100 字符宽, 单引号, 尾逗号 all, LF 换行)
- ESLint 使用 `typescript-eslint` 的 `projectService: true`
+- ESLint 使用 `typescript-eslint` 的 `projectService: true`（无需手动维护 project 路径）
- Git Commit: 使用中文描述，遵循 [Conventional Commits 规范](https://www.conventionalcommits.org/zh-hans/v1.0.0/)
+- **Git Commit**: 必须使用中文描述，遵循 Conventional Commits 规范（如 `fix(组件名): 描述`、`feat(功能名): 描述`）
 ## 关键外部库（非显而易见的）
@@ -189,4 +184,5 @@ src/types/
 - `@dnd-kit` — 拖拽排序（用于页面顺序管理和字段列表排序）
 - `qrious` + `qr-scanner` — 二维码生成与解析
 - `dayjs` — 日期处理（时间戳转换）
- `sonner` — Toast 通知
+- `sonner` — Toast 通知（替代传统 snackbar）
 - Web Worker — 批量数据生成（`src/workers/generator.worker.ts`），避免阻塞 UI 线程
@@ -1 +1 @@
-@AGENTS.md
+@AGENT.md
@@ -81,7 +81,7 @@
 - **UI 组件**: shadcn/ui (基于 Radix UI 的无头组件库)
 - **样式**: Tailwind CSS + class-variance-authority + cn() 工具函数
 - **日期处理**: dayjs (集成 UTC 和 Timezone 插件)
- **UI 文案**: 组件内直接使用中文字符串；功能名称与描述定义在 `src/config/features.tsx`
+- **国际化**: Chrome `chrome.i18n` + `public/_locales/zh_CN/messages.json`
 - **通信**: @webext-core/messaging
 - **存储**: Chrome Storage API (类型安全封装)
 - **解析引擎**: qr-scanner (二维码解析), qrious (二维码生成)
@@ -108,7 +108,7 @@
 │   ├── utils/             # 工具函数与服务抽象
 │   ├── types/             # TypeScript 类型声明
 │   └── lib/               # 通用工具函数与生成器库 (cn, utils, generators 等)
-├── public/                # 静态资源 (图标等)
+├── public/                # 静态资源 (图标、_locales 本地化资源等)
 ├── wxt.config.ts          # WXT 框架核心配置
 └── package.json           # 项目元数据与依赖管理
 ```
@@ -5,7 +5,7 @@
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
-    "css": "src/styles/shell.css",
+    "css": "src/index.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
@@ -724,14 +724,17 @@ src/
 ```tsx
 // src/pages/NewTool/index.tsx
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
 import { useI18n } from '@/utils/chromeI18n';
 import { cn } from '@/lib/utils';
 export default function Index() {
  const { t } = useI18n('newTool');
  return (
-    <div className="p-4 w-full flex flex-col space-y-4 select-none">
+    <div className="p-4 w-full flex flex-col space-y-4 min-h-[500px] select-none">
      {/* 页面内容 */}
      <div className="p-5 rounded-xl border border-border bg-card text-card-foreground shadow-sm">
-        <h4 className="font-bold text-sm tracking-tight">新工具</h4>
+        <h4 className="font-bold text-sm tracking-tight">{t('newTool:title')}</h4>
      </div>
    </div>
  );
@@ -1,7 +0,0 @@
 # Spec 目录
 功能规格、修复方案与验收标准文档。
 | 文档                                                                             | 状态              | 说明                                                 |
 | -------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------- |
 | [storage-cleaner/indexeddb-fix-plan.md](./storage-cleaner/indexeddb-fix-plan.md) | ✅ Phase 3 已完成 | Storage Cleaner IndexedDB 清理逻辑修复方案与验收标准 |
@@ -1,435 +0,0 @@
 # Storage Cleaner — IndexedDB 修复方案与验收标准
 > 创建时间: 2026-06-25
 > 状态: ✅ Phase 3 已完成（2026-06-25）
 > 关联模块: `src/utils/storageCleaner.ts`
 > 前置审查: Code Review（`storageCleaner.ts` 修改版）
 ## 背景与目标
 本次修复针对 `storageCleaner.ts` 中 IndexedDB 清理逻辑及错误处理链路的审查结论，按优先级分三阶段实施。
 | 问题域              | 现状                                           | 目标                              |
 | ------------------- | ---------------------------------------------- | --------------------------------- |
 | IndexedDB fallback  | `store.clear()` 完成后立即 `db.close()`        | 等 transaction commit 后再关闭    |
 | deleteDatabase 超时 | 超时后仍可能触发 `onsuccess`，与 fallback 并发 | 单次删除生命周期内只 resolve 一次 |
 | 部分成功            | 多 DB 部分失败时 `count` 丢失                  | 失败结果保留已清理数量            |
 | 代码结构            | `runScript` / `runCleanScript` 重复            | 统一 executeScript 入口           |
 | 测试                | 缺多 DB 混合场景                               | 补单元测试覆盖                    |
 ---
 ## Phase 1 — 合并前必做（P1）
 ### 1.1 等待 IndexedDB transaction 完成后再关闭连接
 #### 问题
 `clearObjectStores` 在 `Promise.all(clearStore...)` 结束后立刻 `db.close()`。单个 `clearReq.onsuccess` 只表示 request 完成，transaction 可能尚未 commit，存在清空被回滚的风险。
 #### 根因
 IndexedDB 规范中，transaction 的持久化以 `transaction.oncomplete` 为准，而非单个 request 的 `onsuccess`。
 #### 修复方案
 在注入脚本内的 `clearObjectStores` 中，增加 `waitForTransaction` 辅助函数：
 ```typescript
 const waitForTransaction = (tx: IDBTransaction): Promise<void> =>
  new Promise((resolve, reject) => {
    tx.oncomplete = () => resolve();
    tx.onerror = () => reject(tx.error ?? new Error('Transaction failed'));
    tx.onabort = () => reject(tx.error ?? new Error('Transaction aborted'));
  });
 ```
 修改 `openReq.onsuccess` 分支：
 ```typescript
 const transaction = db.transaction(storeNames, 'readwrite');
 const errors = (
  await Promise.all(
    storeNames.map((storeName) => clearStore(transaction.objectStore(storeName), storeName)),
  )
 ).filter((error): error is string => Boolean(error));
 try {
  await waitForTransaction(transaction);
 } catch {
  db.close();
  resolve({
    success: false,
    errors: [`清空 IndexedDB 失败（${dbName}），请刷新后重试`],
  });
  return;
 }
 db.close();
 resolve({ success: errors.length === 0, errors });
 ```
 #### 涉及文件
 - `src/utils/storageCleaner.ts` — `injectClearIndexedDB` 内 `clearObjectStores`
 #### 新增测试
 ```typescript
 it('should wait for transaction complete before closing db', async () => {
  // mock: clear onsuccess 先于 transaction.oncomplete 触发
  // 断言 db.close 在 transaction.oncomplete 之后调用
 });
 ```
 ---
 ### 1.2 消除 deleteDatabase 超时竞态
 #### 问题
 超时 `resolve('timeout')` 后，`deleteReq.onsuccess` 仍可能触发；此时 fallback 的 `indexedDB.open` 与进行中的 `deleteDatabase` 可能并发，行为未定义。
 #### 修复方案
 为每个 DB 删除引入 **单次 settle** 状态：
 ```typescript
 const waitForDeleteDatabase = (dbName: string, timeoutMs: number) =>
  new Promise<'deleted' | 'blocked' | 'timeout' | 'error'>((resolve) => {
    let settled = false;
    const settle = (status: 'deleted' | 'blocked' | 'timeout' | 'error') => {
      if (settled) return;
      settled = true;
      clearTimeout(timeout);
      resolve(status);
    };
    const deleteReq = indexedDB.deleteDatabase(dbName);
    const timeout = setTimeout(() => {
      console.warn('IndexedDB delete timeout:', dbName);
      settle('timeout');
    }, timeoutMs);
    deleteReq.onblocked = () => {
      console.warn('IndexedDB delete blocked:', dbName);
      settle('blocked');
    };
    deleteReq.onsuccess = () => settle('deleted');
    deleteReq.onerror = () => settle('error');
  });
 ```
 #### timeout / blocked 后的 fallback 策略
 | 状态      | 行为                                                               |
 | --------- | ------------------------------------------------------------------ |
 | `blocked` | 立即 fallback `clearObjectStores`（页面仍占用连接，open 通常可行） |
 | `timeout` | 先 `await delay(100~200ms)` 再 fallback，降低与 delete 并发概率    |
 | `error`   | 不 fallback，直接报错                                              |
 #### 涉及文件
 - `src/utils/storageCleaner.ts` — 替换现有 `new Promise` 删除逻辑
 #### 新增测试
 ```typescript
 it('should ignore late onsuccess after delete timeout', async () => {
  // deleteBehavior: timeout，5000ms 后 resolve timeout
  // 6000ms 后再触发 onsuccess
  // 断言：只走 fallback 一次，count 不因 late onsuccess 重复 +1
 });
 ```
 ---
 ## Phase 2 — 建议同 PR 或紧接 follow-up（P2）
 ### 2.1 IndexedDB 部分成功时保留 count
 #### 问题
 多 DB 场景返回 `{ count: 2, errors: ['...'] }` 时，`runCleanScript` 只返回 `{ success: false, error }`，用户看不到已清理 2 个库。
 #### 修复方案（推荐）
 扩展失败分支类型，可选 `count`：
 ```typescript
 // src/types/storage.d.ts
 export type StorageCleanResult =
  | { success: true; count: number }
  | { success: false; error: string; count?: number }; // 部分成功时的已清理数
 ```
 修改 `runCleanScript`：
 ```typescript
 if (raw.errors?.length) {
  const errorMsg = raw.errors.join('\n');
  const partialHint = raw.count > 0 ? `（已成功清理 ${raw.count} 个数据库，但部分失败）\n` : '';
  return {
    success: false,
    error: partialHint + errorMsg,
    ...(raw.count > 0 ? { count: raw.count } : {}),
  };
 }
 ```
 #### UI 层（可选增强）
 `CleaningResult.tsx` 失败时若 `result.indexedDB?.count` 存在，可展示部分成功提示（非必须，error 字符串已含 hint 即可）。
 #### 涉及文件
 - `src/types/storage.d.ts`
 - `src/utils/storageCleaner.ts` — `runCleanScript`
 - `src/utils/__tests__/storageCleaner.test.ts`
 - （可选）`src/pages/StorageCleaner/components/CleaningResult.tsx`
 #### 新增测试
 ```typescript
 it('should preserve partial count when some IndexedDB databases fail', async () => {
  // 3 个 DB：2 成功删除，1 blocked 且 fallback 失败
  // expect: success false, count 2, error 含「已成功清理 2 个」
 });
 ```
 ---
 ### 2.2 统一 executeScript 调用入口
 #### 问题
 `runScript` 与 `runCleanScript` 各自调用 `browser.scripting.executeScript`，行为不一致（吞错 vs 抛错）。
 #### 修复方案
 抽取底层函数：
 ```typescript
 type ExecuteScriptMode = 'fallback' | 'throw';
 async function executeInTab<T>(
  tabId: number,
  func: () => T | Promise<T>,
  options: { errorLabel: string; mode: 'fallback'; fallback: T },
 ): Promise<T>;
 async function executeInTab<T>(
  tabId: number,
  func: () => T | Promise<T>,
  options: { errorLabel: string; mode: 'throw' },
 ): Promise<T>;
 async function executeInTab<T>(...) {
  try {
    const [result] = await browser.scripting.executeScript({ target: { tabId }, func });
    return (result?.result as T) ?? (options.mode === 'fallback' ? options.fallback : undefined as T);
  } catch (error) {
    console.error(`Failed to ${options.errorLabel}:`, error);
    if (options.mode === 'throw') throw error;
    return options.fallback;
  }
 }
 ```
 - `runScript` → `executeInTab(..., { mode: 'fallback', fallback })`
 - `runCleanScript` → `executeInTab(..., { mode: 'throw' })` + 结果解析
 #### 涉及文件
 - `src/utils/storageCleaner.ts`
 #### 验收
 现有 11 个测试全部通过，无行为回归。
 ---
 ### 2.3 错误信息分隔符统一
 #### 问题
 `runCleanScript` 用 `'; '` 拼接，`clearStorage` 的 `result.error` 用 `'\n'`，UI 用 `break-all` 展示，多错误时可读性不一致。
 #### 修复方案
 IndexedDB 内部多错误统一改为 `'\n'`：
 ```typescript
 error: raw.errors.join('\n');
 ```
 #### 涉及文件
 - `src/utils/storageCleaner.ts`
 - 相关测试断言（若有 `'; '` 期望）
 ---
 ### 2.4 补充多 DB 混合场景测试
 | 用例               | 输入                           | 期望                                         |
 | ------------------ | ------------------------------ | -------------------------------------------- |
 | 全部成功           | 3 DB，均 delete success        | `success: true, count: 3`                    |
 | 部分 fallback 成功 | 2 success + 1 blocked→clear OK | `success: true, count: 3`                    |
 | 部分失败           | 2 success + 1 error            | `success: false, count: 2, error 含失败库名` |
 | 空库列表           | `databases()` 返回 `[]`        | `success: true, count: 0`                    |
 #### 涉及文件
 - `src/utils/__tests__/storageCleaner.test.ts`
 - 扩展 `createIndexedDBMock` 支持 per-db 不同 `deleteBehavior`
 ---
 ## Phase 3 — 可选优化（P3）
 ### 3.1 超时常量提升到模块级
 ```typescript
 // src/utils/storageCleaner.ts 或 src/pages/StorageCleaner/constants.ts
 const INDEXED_DB_DELETE_TIMEOUT_MS = 5000;
 const INDEXED_DB_CLEAR_STORE_TIMEOUT_MS = 5000;
 ```
 注入脚本通过闭包引用（executeScript 会序列化 func，常量需在 func 外部定义并 capture，或仍写在 func 内但从模块常量赋值）。
 ### 3.2 IndexedDB 逻辑拆分（长期）
 将 `clearObjectStores`、`waitForDeleteDatabase` 等抽到 `src/utils/indexedDbCleaner.ts` 的纯函数，注入层只做：
 ```typescript
 async () => clearAllIndexedDBs(INDEXED_DB_DELETE_TIMEOUT_MS);
 ```
 便于单测，不依赖 `mockExecuteScriptEval` 间接执行注入函数。工作量大，建议单独 PR。
 ---
 ## 实施顺序
 ```mermaid
 flowchart TD
  A[1.1 transaction.oncomplete] --> B[1.2 delete settle 防竞态]
  B --> C[2.4 补多 DB 测试]
  C --> D[2.1 部分成功 count]
  D --> E[2.2 统一 executeInTab]
  E --> F[2.3 错误分隔符]
  F --> G[3.x 可选重构]
 ```
 | 阶段    | 预估工作量 | 风险             |
 | ------- | ---------- | ---------------- |
 | Phase 1 | 0.5~1 天   | 低，逻辑局部     |
 | Phase 2 | 0.5~1 天   | 中，涉及类型扩展 |
 | Phase 3 | 1~2 天     | 低，可延后       |
 ---
 ## 验收标准
 ### A. 自动化（CI 必须通过）
 ```bash
 npm run test -- src/utils/__tests__/storageCleaner.test.ts
 npm run typecheck
 npm run lint
 ```
 | 编号 | 标准                                                                           |
 | ---- | ------------------------------------------------------------------------------ |
 | A-1  | 全部单元测试通过，新增测试 ≥ 3（transaction 顺序、late onsuccess、多 DB 混合） |
 | A-2  | `tsc --noEmit` 无错误；若扩展 `StorageCleanResult`，所有引用处类型正确         |
 | A-3  | ESLint `--max-warnings=0` 通过                                                 |
 ---
 ### B. 功能行为
 | 编号 | 场景                                                 | 期望结果                                                                      |
 | ---- | ---------------------------------------------------- | ----------------------------------------------------------------------------- |
 | B-1  | 单 DB，`deleteDatabase` 成功                         | `indexedDB: { success: true, count: 1 }`，`overallSuccess: true`              |
 | B-2  | 单 DB，`deleteDatabase` blocked，fallback clear 成功 | `success: true, count: 1`；transaction 在 `oncomplete` 后 `db.close`          |
 | B-3  | 单 DB，delete 超时 5s，fallback clear 成功           | 5s 内进入 fallback；不因 late `onsuccess` 重复计数                            |
 | B-4  | fallback 中某 store clear hang 5s                    | `success: false`，error 含 `dbName/storeName`                                 |
 | B-5  | 3 DB：2 成功 + 1 失败                                | `success: false`，`count: 2`（Phase 2.1 后），error 含失败库名与部分成功提示  |
 | B-6  | `executeScript` 注入失败                             | `success: false`，**不得** `{ success: true, count: 0 }`                      |
 | B-7  | localStorage 成功 + cookies 失败                     | `overallSuccess: false`，`result.error` 为 `Cookies: ...`（换行分隔多项失败） |
 ---
 ### C. 回归与 UI
 | 编号 | 标准                                                                                                      |
 | ---- | --------------------------------------------------------------------------------------------------------- |
 | C-1  | `formatCleaningResult` 成功路径不变                                                                       |
 | C-2  | `CleaningResult` 失败时展示 `result.error`；含 `\n` 时多行可读（现有 `leading-relaxed break-all` 可接受） |
 | C-3  | `reloadAfterClean=true` 且 `overallSuccess=false` 时不刷新页面（`useStorageCleaner` 现有逻辑）            |
 | C-4  | Cookie 清理：domain 前导 `.` 剥离逻辑不变                                                                 |
 ---
 ### D. 手动验收（扩展环境）
 在 Chrome 加载 unpacked extension，选普通 HTTPS 页面：
 | 编号 | 步骤                                              | 期望                                                                    |
 | ---- | ------------------------------------------------- | ----------------------------------------------------------------------- |
 | D-1  | 页面写入 localStorage + IndexedDB，仅清 IndexedDB | 成功提示或明确错误；DevTools → Application → IndexedDB 数据为空或库已删 |
 | D-2  | 打开 DevTools 保持 IndexedDB 面板，执行清理       | 若 blocked，显示中文提示；fallback 成功后数据不可见                     |
 | D-3  | 勾选「清理后刷新」且全部成功                      | Toast「清理成功，即将刷新页面」，页面刷新                               |
 | D-4  | 部分失败                                          | 不刷新；结果区红色展示错误详情                                          |
 ---
 ### E. 代码质量
 | 编号 | 标准                                                               |
 | ---- | ------------------------------------------------------------------ |
 | E-1  | 注入脚本内无重复 `settled` / timeout 逻辑（删除与 clear 各自封装） |
 | E-2  | 错误文案仍为中文，含库名/store 名                                  |
 | E-3  | 无 `any`（测试文件除外）                                           |
 | E-4  | Phase 1 合并后，P1 项在 PR 描述中标注「已修复」并附测试名          |
 ---
 ## PR 检查清单
 ```markdown
 ## 修复内容
 - [ ] P1: transaction.oncomplete 后再 db.close
 - [ ] P1: deleteDatabase settle 防竞态
 - [ ] P2: 部分成功保留 count（可选）
 - [ ] P2: 多 DB 混合测试
 - [ ] P2: 错误信息 `\n` 分隔（可选）
 ## 验收
 - [ ] npm run test / typecheck / lint 通过
 - [ ] 新增测试覆盖 B-2、B-3、B-5
 - [ ] 手动 D-1 ~ D-4 至少测 D-1、D-3
 ```
 ---
 ## 风险与边界说明
 1. **fallback 清空 ≠ 删除库**：blocked 时只清 object store，库结构仍在；成功 `count` 表示「有效清理动作完成」，需在 UI/文档中说明（可选文案：「数据已清空，数据库结构可能仍存在」）。
 2. **timeout 延迟 fallback**：100~200ms 为经验值，无法完全消除竞态，只能降低概率；完全消除需浏览器不支持 abort delete 的前提下接受 best-effort。
 3. **类型扩展**：`StorageCleanResult` 加可选 `count` 为向后兼容；消费方用 `'count' in result && result.count` 判断即可。
 ---
 ## 相关文件索引
 | 文件                                                     | 说明                                         |
 | -------------------------------------------------------- | -------------------------------------------- |
 | `src/utils/storageCleaner.ts`                            | 核心清理逻辑                                 |
 | `src/utils/__tests__/storageCleaner.test.ts`             | 单元测试                                     |
 | `src/types/storage.d.ts`                                 | `StorageCleanResult` / `CleaningResult` 类型 |
 | `src/pages/StorageCleaner/constants.ts`                  | 选项标签与键名                               |
 | `src/pages/StorageCleaner/useStorageCleaner.ts`          | 清理流程编排                                 |
 | `src/pages/StorageCleaner/components/CleaningResult.tsx` | 结果展示 UI                                  |
@@ -29,20 +29,3 @@
 - 导出工具：`src/utils/dataExporter.ts`
 实现约束与任务完成状态记录在 [TASKS.md](./TASKS.md)。
 ## 开发者注意事项（与源码同步）
 以下行为以 `src/` 源码为准；设计文档中的旧版 class API、`metadata`/`options` 嵌套结构已废弃。
 ### Worker 任务 ID（`generationId`）
 `useGenerator` 每次调用 `generate()` 递增 `generationIdRef`，经 `start` 消息传入 Worker。Worker 所有响应（`progress` / `complete` / `error`）均携带同一 `generationId`。
 - **取消**：`cancel()` 先递增 ID 再发送 `cancel`，使进行中的 Worker 响应被主线程忽略；Worker 每生成 100 行让出事件循环以处理 cancel。
 - **快速重试**：新任务 ID 大于旧响应时，旧消息被丢弃，避免 UI 状态错乱。
 类型见 `WorkerRequestMessage` / `WorkerResponseMessage`（`src/types/testDataGenerator.ts`）。
 ### 规则存储写入失败
 `ruleStorage.save()` / `update()` 在 `localStorage.setItem` 失败时返回 `null`（不部分提交）。页面层（如 `FieldList.tsx`）仅在返回值非空时 Toast 成功。详见 [rule-management.md § 存储机制](./rule-management.md#存储机制) 与 `src/utils/README.md`。
@@ -24,20 +24,25 @@
 ## 数据结构
 > **与源码对齐**：类型定义见 `src/types/testDataGenerator.ts`。规则**不**持久化生成数量与导出格式（由页面 `GenerateOptions` 状态管理）。
 ### 规则模板
 ```typescript
 interface DataRule {
-  id: string;
+  id: string; // 唯一标识
-  name: string;
+  name: string; // 规则名称
-  description?: string;
+  description?: string; // 规则描述
-  fields: FieldConfig[];
+  fields: FieldConfig[]; // 字段配置
-  createdAt: number;
+  options: {
-  updatedAt: number;
+    total: number; // 生成数量
-  lastUsedAt?: number;
+    format: 'json' | 'csv';
-  useCount: number;
+    defaultEmptyRate: number; // 默认空值率（0-100）
  };
  metadata: {
    createdAt: number; // 创建时间
    updatedAt: number; // 更新时间
    lastUsedAt?: number; // 最后使用时间
    useCount: number; // 使用次数
  };
 }
 ```
@@ -45,14 +50,13 @@ interface DataRule {
 ```typescript
 interface FieldConfig {
-  id: string;
+  id: string; // 字段唯一标识
-  name: string;
+  name: string; // 字段名
-  description?: string;
+  generator: string; // 生成器名称
-  generatorId: string; // 生成器 ID，对应 lib/generators 中的 id
+  params: Record<string, any>; // 生成器参数
-  params: Record<string, unknown>;
+  unique: boolean; // 唯一性约束
-  required: boolean;
+  required: boolean; // 是否必填
-  nullRate: number; // 空值率 0-100，仅 required=false 时生效
+  emptyRate?: number; // 选填字段的空值概率（0-100）
  unique: boolean;
 }
 ```
@@ -106,9 +110,11 @@ interface FieldConfig {
 1. 验证规则名称不为空
 2. 检查规则数量是否达到上限（20 条）
-3. 若达上限，`save()` 返回 `null`，UI 应阻止或提示
+3. 如果达到上限，显示提示"已达到最大规则数量"
-4. 生成唯一 ID，写入 `createdAt`/`updatedAt`，`useCount` 初始为 0
+4. 生成唯一 ID
-5. 调用 `ruleStorage.save()`；仅当返回值非 `null` 时视为成功（`localStorage` 写入失败同样返回 `null`）
+5. 设置创建时间和更新时间
 6. 初始化使用次数为 0
 7. 保存到 localStorage
 ---
@@ -161,13 +167,17 @@ interface FieldConfig {
 - 支持按规则描述搜索
 - 搜索为模糊匹配，不区分大小写
-**实现方式**（`src/utils/ruleStorage.ts`）:
+**实现方式**:
 ```typescript
-import * as ruleStorage from '@/utils/ruleStorage';
+search(keyword: string): DataRule[] {
  const rules = this.getAll();
  const lowerKeyword = keyword.toLowerCase();
-function searchRules(query: string): DataRule[] {
+  return rules.filter(r =>
-  return ruleStorage.search(query);
+    r.name.toLowerCase().includes(lowerKeyword) ||
    r.description?.toLowerCase().includes(lowerKeyword)
  );
 }
 ```
@@ -214,7 +224,9 @@ function searchRules(query: string): DataRule[] {
 1. 加载原规则配置到编辑器
 2. 用户修改配置
-3. 点击保存时调用 `ruleStorage.update()`；返回非 `null` 才更新 `updatedAt` 并提示成功
+3. 点击保存时更新规则
 4. 更新 metadata.updatedAt
 5. 保存到 localStorage
 ---
@@ -257,12 +269,18 @@ function searchRules(query: string): DataRule[] {
 **实现方式**:
 ```typescript
-function loadRule(ruleId: string): void {
+loadRule(ruleId: string): void {
-  const rule = ruleStorage.getById(ruleId);
+  const rule = this.storage.getById(ruleId);
  if (!rule) return;
-  setFields(rule.fields);
+  // 应用规则配置
-  ruleStorage.recordUse(ruleId);
+  this.setFields(rule.fields);
  this.setOptions(rule.options);
  // 记录使用
  this.storage.recordUse(ruleId);
  // 更新预览
  this.updatePreview();
 }
 ```
@@ -274,7 +292,7 @@ function loadRule(ruleId: string): void {
 1. 点击"复制"按钮
 2. 创建规则的副本
-3. 名称添加「（副本）」后缀（默认 `duplicate(id, '（副本）')`）
+3. 名称添加"(副本)"后缀
 4. 生成新的 ID
 5. 保存为新规则
@@ -309,20 +327,23 @@ function loadRule(ruleId: string): void {
 └─────────────────────────────────────────────────────────────────────┘
 ```
-**导出格式**（`exportRules()` 返回 `DataRule[]` 的 JSON 字符串，无外层包装）:
+**导出格式**:
 ```json
-[
+{
-  {
+  "version": "1.0",
-    "id": "rule_123456",
+  "exportedAt": "2024-01-20T10:15:45.000Z",
-    "name": "电商用户数据 - 测试用",
+  "rules": [
-    "description": "用于测试用户注册功能",
+    {
-    "fields": [],
+      "id": "rule_123456",
-    "createdAt": 1704067200000,
+      "name": "电商用户数据 - 测试用",
-    "updatedAt": 1704067200000,
+      "description": "用于测试用户注册功能",
-    "useCount": 0
+      "fields": [...],
-  }
+      "options": {...},
-]
+      "metadata": {...}
    }
  ]
 }
 ```
 ---
@@ -380,25 +401,63 @@ function loadRule(ruleId: string): void {
 ### 本地存储
-使用 `localStorage`，键名 `testDataGenerator_rules`。API 为**命名导出函数**（见 `src/utils/ruleStorage.ts`）：
+使用 localStorage 存储规则数据:
 | 函数 | 说明 |
 | ---- | ---- |
 | `getAll()` / `getById()` / `getByName()` | 读取 |
 | `save()` / `update()` / `deleteRule()` / `duplicate()` | 写入；失败时返回 `null` 或 `false` |
 | `recordUse()` | 递增 `useCount`、更新 `lastUsedAt` |
 | `search()` / `getRecent()` | 搜索与最近使用 |
 | `exportRules()` / `importRules()` | 导入导出 JSON 数组 |
 | `clear()` | 清空全部规则 |
 写入失败（如 `QuotaExceededError`）时，内部 `setAll()` 返回 `false`，`save`/`update` 返回 `null`，`deleteRule` 返回 `false`，并在控制台输出 `[ruleStorage] 保存规则失败`。调用方须检查返回值，避免误报成功。
 ```typescript
-import * as ruleStorage from '@/utils/ruleStorage';
+class RuleStorage {
  private readonly STORAGE_KEY = 'testDataGenerator_rules';
-const saved = ruleStorage.save({ name: '示例', fields });
+  // 获取所有规则
-if (!saved) {
+  getAll(): DataRule[] {
-  // 达上限或 localStorage 不可用
+    const data = localStorage.getItem(this.STORAGE_KEY);
    return data ? JSON.parse(data) : [];
  }
  // 保存规则
  save(rule: DataRule): { success: boolean; message?: string } {
    const rules = this.getAll();
    // 规则数量限制：最多 20 条
    const MAX_RULES = 20;
    if (rules.length >= MAX_RULES) {
      return {
        success: false,
        message: `已达到最大规则数量（${MAX_RULES}条），请删除一些规则后再保存`,
      };
    }
    rules.push(rule);
    localStorage.setItem(this.STORAGE_KEY, JSON.stringify(rules));
    return { success: true };
  }
  // 更新规则
  update(id: string, updates: Partial<DataRule>): void {
    const rules = this.getAll();
    const index = rules.findIndex((r) => r.id === id);
    if (index !== -1) {
      rules[index] = { ...rules[index], ...updates };
      localStorage.setItem(this.STORAGE_KEY, JSON.stringify(rules));
    }
  }
  // 删除规则
  delete(id: string): void {
    const rules = this.getAll();
    const filtered = rules.filter((r) => r.id !== id);
    localStorage.setItem(this.STORAGE_KEY, JSON.stringify(filtered));
  }
  // 记录使用
  recordUse(id: string): void {
    const rules = this.getAll();
    const rule = rules.find((r) => r.id === id);
    if (rule) {
      rule.metadata.lastUsedAt = Date.now();
      rule.metadata.useCount++;
      localStorage.setItem(this.STORAGE_KEY, JSON.stringify(rules));
    }
  }
 }
 ```
@@ -1,7 +1,5 @@
 # 技术实现
 > **文档同步说明**：本文档含早期设计稿代码示例，部分类型/API 已与实现偏离。开发时请以 `src/types/testDataGenerator.ts`、`src/workers/generator.worker.ts`、`src/pages/TestDataGenerator/hooks/useGenerator.ts`、`src/utils/ruleStorage.ts` 为准。近期变更摘要见 [README § 开发者注意事项](./README.md#开发者注意事项与源码同步)。
 ## 技术栈
 | 技术         | 用途     | 版本 |
@@ -1500,69 +1498,6 @@ export class DataExporter {
 ## Web Worker 使用
 ### 消息协议
 ```typescript
 // src/types/testDataGenerator.ts
 type WorkerRequestMessage =
  | { type: 'start'; payload: WorkerStartPayload }
  | { type: 'cancel' };
 type WorkerResponseMessage =
  | { type: 'progress'; generationId: number; payload: GenerateProgress }
  | { type: 'complete'; generationId: number; payload: GenerateResult }
  | { type: 'error'; generationId: number; payload: { error: string } };
 interface WorkerStartPayload {
  generationId: number; // 任务 ID，用于忽略过期响应
  fields: FieldConfig[];
  count: number;
  csvMode: boolean;
 }
 ```
 ### useGenerator Hook
 `src/pages/TestDataGenerator/hooks/useGenerator.ts` 负责 Worker 生命周期与 `generationId` 管理：
 - Worker **复用**：同一 Hook 实例内只创建一次，出错后 `terminate` 并在下次重建
 - **开始生成**：`generate(fields, count, csvMode?)` 递增 `generationId` 并 post `start`
 - **取消**：`cancel()` 递增 ID（使旧响应失效）并 post `cancel`；取消完成的 `complete` 不写入 `error` 状态
 - **响应过滤**：`onmessage` 中若 `data.generationId !== generationIdRef.current` 则忽略
 ```typescript
 const generate = (fields: FieldConfig[], count: number, csvMode = false) => {
  if (isGenerating) return;
  const generationId = ++generationIdRef.current;
  worker.postMessage({ type: 'start', payload: { generationId, fields, count, csvMode } });
 };
 const cancel = () => {
  if (workerRef.current && isGenerating) {
    ++generationIdRef.current;
    worker.postMessage({ type: 'cancel' });
    setIsGenerating(false);
  }
 };
 ```
 ### Worker 实现要点
 `src/workers/generator.worker.ts`：
 - 按 `field.generatorId` 查找生成器；选填字段按 `nullRate` 随机置 `null`
 - 唯一性：≤1000 条随机+重试；>1000 条优先 `generateAtIndex`
 - 每 `YIELD_EVERY`（100）行 `await setTimeout(0)`，以便处理 `cancel`
 - 进度：每 1000 条或最后一行 post `progress`
 ---
 ## Web Worker 使用（历史设计稿，仅供参考）
 <details>
 <summary>展开查看旧版设计示例（与当前实现不一致）</summary>
 ### 创建 Worker
 ```typescript
@@ -1658,7 +1593,7 @@ export function useGenerator() {
 }
 ```
-### 错误处理（设计稿，`useErrorHandler.ts` 未实现）
+### 错误处理
 ```typescript
 // src/pages/TestDataGenerator/hooks/useErrorHandler.ts
@@ -1701,12 +1636,8 @@ export function useErrorHandler(options: ErrorHandlerOptions = {}) {
 ---
 </details>
 ## 错误提示机制
 > 当前实现：`TestDataGenerator/index.tsx` 直接使用 `useGenerator` 的 `error`/`result` 与 `ResultPanel` 展示警告；下方示例引用未实现的 `useErrorHandler`，仅供对照。
 ### 错误类型分类
 | 错误类型        | 严重程度 | 触发场景                 | 提示方式      |
@@ -12,9 +12,24 @@
 | `icon/48.png`  | 48×48 图标（扩展管理页）         |
 | `icon/96.png`  | 96×96 图标                       |
 | `icon/128.png` | 128×128 图标（Chrome Web Store） |
 | `_locales/`    | Chrome 扩展本地化资源            |
 ## 本地化资源
 项目使用 Chrome 扩展标准 `chrome.i18n`，默认语言在 `wxt.config.ts` 中配置为 `zh_CN`。
 | 文件/目录                      | 用途                                               |
 | ------------------------------ | -------------------------------------------------- |
 | `_locales/zh_CN/messages.json` | 默认中文语言包，包含功能名、描述、按钮、提示等翻译 |
 添加或修改文案时：
 - 使用 Chrome 扩展消息格式：`"key": { "message": "文本" }`
 - key 使用下划线分隔，例如 `testDataGenerator_title`
 - 代码中通过 `useI18n` 或 `getMessage` 读取，不要新增 `i18n/locales` 目录
 ## 注意事项
 - 修改图标后需同步更新 `wxt.config.ts` 中的 manifest 配置
 - 图标格式推荐使用 PNG，确保透明背景
- UI 文案不在此目录维护，见 `src/config/features.tsx` 与各页面组件
+- 修改 `_locales` 后需确认 `manifest.default_locale` 与语言目录名一致
@@ -0,0 +1 @@
 <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="35.93" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 228"><path fill="#00D8FF" d="M210.483 73.824a171.49 171.49 0 0 0-8.24-2.597c.465-1.9.893-3.777 1.273-5.621c6.238-30.281 2.16-54.676-11.769-62.708c-13.355-7.7-35.196.329-57.254 19.526a171.23 171.23 0 0 0-6.375 5.848a155.866 155.866 0 0 0-4.241-3.917C100.759 3.829 77.587-4.822 63.673 3.233C50.33 10.957 46.379 33.89 51.995 62.588a170.974 170.974 0 0 0 1.892 8.48c-3.28.932-6.445 1.924-9.474 2.98C17.309 83.498 0 98.307 0 113.668c0 15.865 18.582 31.778 46.812 41.427a145.52 145.52 0 0 0 6.921 2.165a167.467 167.467 0 0 0-2.01 9.138c-5.354 28.2-1.173 50.591 12.134 58.266c13.744 7.926 36.812-.22 59.273-19.855a145.567 145.567 0 0 0 5.342-4.923a168.064 168.064 0 0 0 6.92 6.314c21.758 18.722 43.246 26.282 56.54 18.586c13.731-7.949 18.194-32.003 12.4-61.268a145.016 145.016 0 0 0-1.535-6.842c1.62-.48 3.21-.974 4.76-1.488c29.348-9.723 48.443-25.443 48.443-41.52c0-15.417-17.868-30.326-45.517-39.844Zm-6.365 70.984c-1.4.463-2.836.91-4.3 1.345c-3.24-10.257-7.612-21.163-12.963-32.432c5.106-11 9.31-21.767 12.459-31.957c2.619.758 5.16 1.557 7.61 2.4c23.69 8.156 38.14 20.213 38.14 29.504c0 9.896-15.606 22.743-40.946 31.14Zm-10.514 20.834c2.562 12.94 2.927 24.64 1.23 33.787c-1.524 8.219-4.59 13.698-8.382 15.893c-8.067 4.67-25.32-1.4-43.927-17.412a156.726 156.726 0 0 1-6.437-5.87c7.214-7.889 14.423-17.06 21.459-27.246c12.376-1.098 24.068-2.894 34.671-5.345a134.17 134.17 0 0 1 1.386 6.193ZM87.276 214.515c-7.882 2.783-14.16 2.863-17.955.675c-8.075-4.657-11.432-22.636-6.853-46.752a156.923 156.923 0 0 1 1.869-8.499c10.486 2.32 22.093 3.988 34.498 4.994c7.084 9.967 14.501 19.128 21.976 27.15a134.668 134.668 0 0 1-4.877 4.492c-9.933 8.682-19.886 14.842-28.658 17.94ZM50.35 144.747c-12.483-4.267-22.792-9.812-29.858-15.863c-6.35-5.437-9.555-10.836-9.555-15.216c0-9.322 13.897-21.212 37.076-29.293c2.813-.98 5.757-1.905 8.812-2.773c3.204 10.42 7.406 21.315 12.477 32.332c-5.137 11.18-9.399 22.249-12.634 32.792a134.718 134.718 0 0 1-6.318-1.979Zm12.378-84.26c-4.811-24.587-1.616-43.134 6.425-47.789c8.564-4.958 27.502 2.111 47.463 19.835a144.318 144.318 0 0 1 3.841 3.545c-7.438 7.987-14.787 17.08-21.808 26.988c-12.04 1.116-23.565 2.908-34.161 5.309a160.342 160.342 0 0 1-1.76-7.887Zm110.427 27.268a347.8 347.8 0 0 0-7.785-12.803c8.168 1.033 15.994 2.404 23.343 4.08c-2.206 7.072-4.956 14.465-8.193 22.045a381.151 381.151 0 0 0-7.365-13.322Zm-45.032-43.861c5.044 5.465 10.096 11.566 15.065 18.186a322.04 322.04 0 0 0-30.257-.006c4.974-6.559 10.069-12.652 15.192-18.18ZM82.802 87.83a323.167 323.167 0 0 0-7.227 13.238c-3.184-7.553-5.909-14.98-8.134-22.152c7.304-1.634 15.093-2.97 23.209-3.984a321.524 321.524 0 0 0-7.848 12.897Zm8.081 65.352c-8.385-.936-16.291-2.203-23.593-3.793c2.26-7.3 5.045-14.885 8.298-22.6a321.187 321.187 0 0 0 7.257 13.246c2.594 4.48 5.28 8.868 8.038 13.147Zm37.542 31.03c-5.184-5.592-10.354-11.779-15.403-18.433c4.902.192 9.899.29 14.978.29c5.218 0 10.376-.117 15.453-.343c-4.985 6.774-10.018 12.97-15.028 18.486Zm52.198-57.817c3.422 7.8 6.306 15.345 8.596 22.52c-7.422 1.694-15.436 3.058-23.88 4.071a382.417 382.417 0 0 0 7.859-13.026a347.403 347.403 0 0 0 7.425-13.565Zm-16.898 8.101a358.557 358.557 0 0 1-12.281 19.815a329.4 329.4 0 0 1-23.444.823c-7.967 0-15.716-.248-23.178-.732a310.202 310.202 0 0 1-12.513-19.846h.001a307.41 307.41 0 0 1-10.923-20.627a310.278 310.278 0 0 1 10.89-20.637l-.001.001a307.318 307.318 0 0 1 12.413-19.761c7.613-.576 15.42-.876 23.31-.876H128c7.926 0 15.743.303 23.354.883a329.357 329.357 0 0 1 12.335 19.695a358.489 358.489 0 0 1 11.036 20.54a329.472 329.472 0 0 1-11 20.722Zm22.56-122.124c8.572 4.944 11.906 24.881 6.52 51.026c-.344 1.668-.73 3.367-1.15 5.09c-10.622-2.452-22.155-4.275-34.23-5.408c-7.034-10.017-14.323-19.124-21.64-27.008a160.789 160.789 0 0 1 5.888-5.4c18.9-16.447 36.564-22.941 44.612-18.3ZM128 90.808c12.625 0 22.86 10.235 22.86 22.86s-10.235 22.86-22.86 22.86s-22.86-10.235-22.86-22.86s10.235-22.86 22.86-22.86Z"></path></svg>
@@ -1,9 +1,10 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { Check, Copy } from 'lucide-react';
 import { copyTextToClipboard } from '@/utils/clipboard';
 import { Button, type ButtonProps } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
 import { buttonVariants, type ButtonProps } from '@/components/ui/button';
 import { toast } from 'sonner';
 import { useI18n } from '@/utils/chromeI18n';
 interface CopyButtonProps extends Omit<ButtonProps, 'children' | 'onClick'> {
  text: string;
@@ -18,6 +19,7 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
  className,
  ...props
 }) => {
  const { t } = useI18n('common');
  const [copied, setCopied] = useState(false);
  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -31,34 +33,41 @@ export const CopyButton: React.FC<CopyButtonProps> = ({
    e.stopPropagation();
    if (!text) {
-      toast.error('无内容可复制');
+      toast.error(t('messages.copyEmpty'));
      return;
    }
    const success = await copyTextToClipboard(text);
    if (success) {
-      toast.success('已复制到剪贴板');
+      toast.success(t('messages.copySuccess'));
      setCopied(true);
      if (timerRef.current) clearTimeout(timerRef.current);
      timerRef.current = setTimeout(() => setCopied(false), 1500);
    } else {
-      toast.error('复制失败');
+      toast.error(t('messages.copyError'));
    }
  };
  return (
-    <Button
+    <button
      type="button"
      onClick={handleCopy}
-      title={tooltip ?? '复制'}
+      title={tooltip ?? t('buttons.copy')}
-      aria-label={tooltip ?? '复制'}
+      aria-label={tooltip ?? t('buttons.copy')}
-      variant={variant}
+      className={cn(
-      size={size}
+        buttonVariants({ variant, size }),
-      className={cn(className, copied && 'text-emerald-500')}
+        copied &&
          'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 hover:bg-emerald-500/10',
        className,
      )}
      {...props}
    >
-      {copied ? <Check className="h-4 w-4" /> : <Copy className="h-4 w-4" />}
+      {copied ? (
-    </Button>
+        <Check className="h-[1.2em] w-[1.2em]" />
      ) : (
        <Copy className="h-[1.2em] w-[1.2em]" />
      )}
    </button>
  );
 };
@@ -0,0 +1,86 @@
 /**
 * DecodeResultPaper
 *
 * FileMode 与 ImageMode 通用的 decode 结果展示组件。
 * 提取了二者 decode 输出区完全一致的结构：
 *   标题 → 可选预览（children）→ 文件信息 → 文件名输入 → 下载按钮
 *
 * FileMode 直接使用，ImageMode 通过 children 传入图片预览。
 */
 import { Download } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { formatFileSize } from '@/utils/base64Converter';
 import { useI18n } from '@/utils/chromeI18n';
 interface DecodeResultPaperProps {
  /** 标题文案，由调用方传入 i18n key 对应的值（如 decodedFileOutput / decodedImageOutput） */
  title: string;
  /** 解码后推断的 MIME 类型 */
  mimeType: string;
  /** 解码后 Blob 的大小（字节） */
  blobSize: number;
  /** 当前文件名 */
  fileName: string;
  /** 文件名变更回调 */
  onFileNameChange: (name: string) => void;
  /** 下载按钮点击回调 */
  onDownload: () => void;
  /** 可选的预览内容，ImageMode 用于渲染图片预览 */
  children?: React.ReactNode;
 }
 export default function DecodeResultPaper({
  title,
  mimeType,
  blobSize,
  fileName,
  onFileNameChange,
  onDownload,
  children,
 }: DecodeResultPaperProps) {
  const { t } = useI18n('base64Converter');
  return (
    <div className="p-4 rounded-xl bg-primary/10 border border-primary/30">
      {/* 标题 */}
      <span className="block mb-2 text-xs font-bold text-muted-foreground">{title}</span>
      {/* 可选预览内容（ImageMode 的图片） */}
      {children}
      {/* 文件信息 */}
      <div className="flex gap-4 mb-3">
        <span className="text-xs text-muted-foreground">
          {t('inferredMimeType')}: {mimeType}
        </span>
        <span className="text-xs text-muted-foreground">
          {t('decodedSize')}: {formatFileSize(blobSize)}
        </span>
      </div>
      {/* 文件名输入 */}
      <div className="mb-3">
        <label className="block text-xs font-medium text-muted-foreground mb-1">
          {t('decodedFileName')}
        </label>
        <input
          type="text"
          value={fileName}
          onChange={(e) => onFileNameChange(e.target.value)}
          className="w-full px-3 py-2 text-sm border border-border rounded-lg focus:outline-none focus:ring-2 focus:ring-primary"
        />
      </div>
      {/* 下载按钮 */}
      <Button
        variant="default"
        onClick={onDownload}
        disabled={!fileName.trim()}
        className="w-full rounded-lg font-bold"
      >
        <Download className="mr-2 h-4 w-4" />
        {t('download')}
      </Button>
    </div>
  );
 }
@@ -1,30 +0,0 @@
 import React from 'react';
 import { cn } from '@/lib/utils';
 export interface EmptyPlaceholderProps extends React.HTMLAttributes<HTMLDivElement> {
  children: React.ReactNode;
  messageClassName?: string;
 }
 const CONTAINER_CLASSES =
  'rounded-xl bg-muted/30 border border-dashed border-border/80 text-center flex flex-col items-center justify-center select-none p-8 min-h-[120px]';
 const MESSAGE_CLASSES =
  'text-xs font-semibold text-muted-foreground/80 tracking-wide max-w-[240px] leading-relaxed';
 export default function EmptyPlaceholder({
  children,
  className,
  messageClassName,
  ...props
 }: EmptyPlaceholderProps) {
  return (
    <div className={cn(CONTAINER_CLASSES, className)} {...props}>
      {typeof children === 'string' || typeof children === 'number' ? (
        <p className={cn(MESSAGE_CLASSES, messageClassName)}>{children}</p>
      ) : (
        children
      )}
    </div>
  );
 }
@@ -1,5 +1,7 @@
 import { Component, ErrorInfo, ReactNode } from 'react';
-import { ErrorFallback } from '@/components/ErrorFallback';
+import { AlertCircle, RefreshCw } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { getMessage } from '@/utils/chromeI18n';
 interface Props {
  children: ReactNode;
@@ -37,14 +39,34 @@ class ErrorBoundary extends Component<Props, State> {
  render() {
    if (this.state.hasError) {
      return (
-        <ErrorFallback
+        <div className="flex flex-col items-center justify-center mt-16 mx-auto max-w-md">
-          variant="app"
+          <div className="p-6 text-center rounded-xl border border-destructive/20 bg-destructive/5 shadow-sm">
-          title="糟糕，出了点问题"
+            <div className="flex h-16 w-16 items-center justify-center rounded-full bg-destructive/10 text-destructive mx-auto mb-4">
-          description="应用遇到了一些意外错误。您可以尝试刷新页面或重置应用。"
+              <AlertCircle className="h-8 w-8" />
-          error={this.state.error}
+            </div>
-          actionLabel="刷新应用"
+            <h2 className="text-xl font-extrabold text-destructive mb-2">
-          onAction={this.handleReset}
+              {getMessage('errorBoundary_title')}
-        />
+            </h2>
            <p className="text-sm text-muted-foreground mb-6">
              {getMessage('errorBoundary_description')}
            </p>
            {this.state.error && (
              <div className="mb-6 p-4 rounded-lg bg-zinc-950 dark:bg-zinc-900 text-left max-h-[200px] overflow-auto border border-border/40">
                <pre className="font-mono text-xs whitespace-pre-wrap break-all text-zinc-200 selection:bg-zinc-700">
                  {this.state.error.toString()}
                </pre>
              </div>
            )}
            <Button
              variant="destructive"
              onClick={this.handleReset}
              className="rounded-lg font-bold shadow-sm"
            >
              <RefreshCw className="mr-2 h-4 w-4" />
              {getMessage('errorBoundary_refresh')}
            </Button>
          </div>
        </div>
      );
    }
@@ -1,96 +0,0 @@
 import { AlertCircle, RefreshCw } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
 export interface ErrorFallbackProps {
  title: string;
  description: string;
  error: Error | null;
  actionLabel: string;
  onAction: () => void;
  variant?: 'app' | 'page';
  showStack?: boolean;
  className?: string;
 }
 export function ErrorFallback({
  title,
  description,
  error,
  actionLabel,
  onAction,
  variant = 'page',
  showStack = false,
  className,
 }: ErrorFallbackProps) {
  const isApp = variant === 'app';
  const errorText = error ? (showStack ? error.stack || error.toString() : error.toString()) : null;
  return (
    <div
      className={cn(
        'flex flex-col items-center justify-center',
        isApp ? 'mt-16 mx-auto max-w-md' : 'flex-1 p-6 min-h-[300px] fade-in-zoom-95',
        className,
      )}
    >
      <div
        className={cn(
          'p-6 text-center rounded-xl border border-destructive/20 bg-destructive/5 shadow-sm',
          !isApp && 'max-w-md w-full',
        )}
      >
        <div
          className={cn(
            'flex items-center justify-center rounded-full bg-destructive/10 text-destructive mx-auto mb-4',
            isApp ? 'h-16 w-16' : 'h-12 w-12',
          )}
        >
          <AlertCircle className={isApp ? 'h-8 w-8' : 'h-6 w-6'} />
        </div>
        {isApp ? (
          <h2 className="text-xl font-extrabold text-destructive mb-2">{title}</h2>
        ) : (
          <h3 className="text-base font-semibold text-foreground mb-1.5">{title}</h3>
        )}
        <p
          className={
            isApp ? 'text-sm text-muted-foreground mb-6' : 'text-xs text-muted-foreground mb-5'
          }
        >
          {description}
        </p>
        {errorText && (
          <div
            className={cn(
              'rounded-lg bg-zinc-950 dark:bg-zinc-900 text-left border border-border/40',
              isApp ? 'mb-6 p-4 max-h-[200px] overflow-auto' : 'mb-5 p-3 max-h-40 overflow-y-auto',
            )}
          >
            <pre
              className={cn(
                'font-mono whitespace-pre-wrap break-all text-zinc-200 selection:bg-zinc-700',
                isApp ? 'text-xs' : 'text-[11px] leading-relaxed',
              )}
            >
              {errorText}
            </pre>
          </div>
        )}
        <Button
          variant="destructive"
          size={isApp ? 'default' : 'sm'}
          onClick={onAction}
          className={isApp ? 'rounded-lg font-bold shadow-sm' : 'font-medium shadow-sm'}
        >
          <RefreshCw className={isApp ? 'mr-2 h-4 w-4' : 'mr-1.5 h-3.5 w-3.5'} />
          {actionLabel}
        </Button>
      </div>
    </div>
  );
 }
@@ -1,14 +1,22 @@
 import { useCallback, useEffect, useRef } from 'react';
 import { Image, X } from 'lucide-react';
 import { toast } from 'sonner';
-import { Button } from '@/components/ui/button';
+import { useI18n } from '@/utils/chromeI18n';
 import { Label } from '@/components/ui/label';
 interface ImageUploaderProps {
  /** 选中的文件 */
  selectedFile: File | null;
  /** 文件变更回调 */
  onFileChange: (file: File) => void;
  /** 清除文件回调 */
  onClearFile: () => void;
  /** 文件预览 URL */
  previewUrl: string;
  /** 预览 URL 变更回调 */
  onPreviewUrlChange: (url: string) => void;
  /** 是否正在拖拽 */
  dragging: boolean;
  /** 拖拽状态变更回调 */
  onDraggingChange: (dragging: boolean) => void;
 }
@@ -17,21 +25,32 @@ const ImageUploader = ({
  onFileChange,
  onClearFile,
  previewUrl,
  onPreviewUrlChange,
  dragging,
  onDraggingChange,
 }: ImageUploaderProps) => {
-  const handleClearFile = () => {
+  const { t } = useI18n('qrCode');
  const fileInputRef = useRef<HTMLInputElement>(null);
  const handleFileChange = useCallback(
    (file: File) => {
      onFileChange(file);
      onPreviewUrlChange(URL.createObjectURL(file));
    },
    [onFileChange, onPreviewUrlChange],
  );
  const handleClearFile = useCallback(() => {
    if (previewUrl) {
      URL.revokeObjectURL(previewUrl);
    }
    onClearFile();
-    toast.success('图片已清除');
+    toast.success(t('qrCode:imageCleared'));
-  };
+  }, [previewUrl, onClearFile, t]);
  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const file = e.target.files?.[0];
+    if (e.target.files && e.target.files.length > 0) {
-    if (file) {
+      handleFileChange(e.target.files[0]);
      onFileChange(file);
    }
  };
@@ -49,10 +68,42 @@ const ImageUploader = ({
    onDraggingChange(false);
    const droppedFile = e.dataTransfer.files?.[0];
    if (droppedFile) {
-      onFileChange(droppedFile);
+      handleFileChange(droppedFile);
    }
  };
  // 监听粘贴事件
  useEffect(() => {
    const handlePaste = async (e: ClipboardEvent) => {
      const items = e.clipboardData?.items;
      if (!items) return;
      for (let i = 0; i < items.length; i++) {
        if (items[i].type.startsWith('image/')) {
          e.preventDefault();
          const file = items[i].getAsFile();
          if (file) {
            try {
              handleFileChange(file);
              toast.success(t('qrCode:imagePasted'));
            } catch (error) {
              console.error('处理粘贴图片失败:', error);
              toast.error(t('qrCode:imagePasteError'));
            }
          }
          break;
        }
      }
    };
    document.addEventListener('paste', handlePaste);
    return () => {
      document.removeEventListener('paste', handlePaste);
    };
  }, [handleFileChange, t]);
  return (
    <div
      className={`flex flex-col items-center justify-center h-[250px] border-2 border-dashed rounded-xl p-4 cursor-pointer transition-all duration-200 ${
@@ -60,20 +111,21 @@ const ImageUploader = ({
          ? 'border-green-600 bg-green-50'
          : selectedFile
            ? 'border-green-600 bg-green-50/50'
-            : 'border-input bg-muted hover:border-green-600 hover:bg-green-500/10'
+            : 'border-input bg-muted hover:border-green-600 hover:bg-green-500/10/50'
      }`}
      onDragOver={handleDragOver}
      onDragLeave={handleDragLeave}
      onDrop={handleDrop}
    >
      <input
        ref={fileInputRef}
        type="file"
        accept="image/*"
        onChange={handleInputChange}
        className="hidden"
        id="qr-code-upload"
      />
-      <Label htmlFor="qr-code-upload" className="cursor-pointer text-center w-full">
+      <label htmlFor="qr-code-upload" className="cursor-pointer text-center w-full">
        {selectedFile ? (
          <div className="text-center w-full relative">
            <div className="relative inline-block">
@@ -82,22 +134,20 @@ const ImageUploader = ({
                alt="QR Code Preview"
                className="max-w-full max-h-40 rounded-lg object-contain"
              />
-              <Button
+              <button
                type="button"
                variant="destructive"
                size="icon"
                data-testid="ClearIcon"
                onClick={(e) => {
                  e.stopPropagation();
                  handleClearFile();
                }}
-                className="absolute -top-2 -right-2 h-6 w-6 rounded-full"
+                className="absolute -top-2 -right-2 w-6 h-6 bg-red-500 text-white rounded-full flex items-center justify-center hover:bg-red-600 transition-colors"
              >
                <X className="w-3 h-3" />
-              </Button>
+              </button>
            </div>
            <span className="block text-sm text-muted-foreground mt-2">{selectedFile.name}</span>
-            <span className="block text-xs text-muted-foreground">点击更换图片</span>
+            <span className="block text-xs text-muted-foreground">{t('qrCode:clickToChange')}</span>
          </div>
        ) : (
          <>
@@ -106,14 +156,14 @@ const ImageUploader = ({
              className="w-12 h-12 text-muted-foreground mx-auto mb-2"
            />
            <span className="block text-sm text-muted-foreground mb-1">
-              点击、拖拽或粘贴上传二维码图片
+              {t('qrCode:clickToUpload')}
            </span>
            <span className="block text-xs text-muted-foreground">
-              支持 PNG、JPG、WEBP、Base64 格式
+              {t('qrCode:supportFormats')}
            </span>
          </>
        )}
-      </Label>
+      </label>
    </div>
  );
 };
@@ -1,5 +1,7 @@
 import { Component, ErrorInfo, ReactNode } from 'react';
-import { ErrorFallback } from '@/components/ErrorFallback';
+import { AlertCircle, RefreshCw } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { getMessage } from '@/utils/chromeI18n';
 interface Props {
  children: ReactNode;
@@ -38,15 +40,38 @@ class PageErrorBoundary extends Component<Props, State> {
  render() {
    if (this.state.hasError) {
      return (
-        <ErrorFallback
+        <div className="flex flex-col items-center justify-center flex-1 p-6 min-h-[300px] animate-in fade-in zoom-in-95 duration-200">
-          variant="page"
+          <div className="p-6 text-center rounded-xl border border-destructive/20 bg-destructive/5 max-w-md w-full shadow-sm">
-          title="该功能运行异常"
+            <div className="flex h-12 w-12 items-center justify-center rounded-full bg-destructive/10 text-destructive mx-auto mb-4">
-          description="该页面在加载或渲染时遇到了内部脚本错误。您可以尝试重试，或者通过导航菜单切换到其他工具。"
+              <AlertCircle className="h-6 w-6" />
-          error={this.state.error}
+            </div>
-          actionLabel="重新尝试"
+
-          onAction={this.handleRetry}
+            <h3 className="text-base font-semibold text-foreground mb-1.5">
-          showStack
+              {getMessage('pageErrorBoundary_title')}
-        />
+            </h3>
            <p className="text-xs text-muted-foreground mb-5">
              {getMessage('pageErrorBoundary_description')}
            </p>
            {this.state.error && (
              <div className="mb-5 p-3 rounded-lg bg-zinc-950 dark:bg-zinc-900 text-left max-h-40 overflow-y-auto border border-border/40">
                <pre className="font-mono text-[11px] leading-relaxed whitespace-pre-wrap break-all text-zinc-200 selection:bg-zinc-700">
                  {this.state.error.stack || this.state.error.toString()}
                </pre>
              </div>
            )}
            <Button
              variant="destructive"
              size="sm"
              onClick={this.handleRetry}
              className="font-medium shadow-sm"
            >
              <RefreshCw className="mr-1.5 h-3.5 w-3.5" />
              {getMessage('errorBoundary_retry')}
            </Button>
          </div>
        </div>
      );
    }
@@ -46,7 +46,7 @@ function ToolPageSkeleton() {
        <div className="w-24 h-9 bg-muted rounded-lg animate-pulse" />
        <div className="w-20 h-9 bg-muted rounded-lg animate-pulse" />
        <div className="flex-1" />
-        <div className="w-24 h-9 bg-muted rounded-lg animate-pulse" />
+        <div className="w-22 h-9 bg-muted rounded-lg animate-pulse" />
      </div>
      {/* 结果区域 */}
@@ -1,13 +1,18 @@
 import React from 'react';
 import { Copy, Download } from 'lucide-react';
-import EmptyPlaceholder from '@/components/EmptyPlaceholder';
+import { useI18n } from '@/utils/chromeI18n';
 import { cn } from '@/lib/utils';
 import { Button } from '@/components/ui/button';
 // 继承原生 HTML Div 属性，方便外部无缝扩充类名或监听事件
 interface QrCodePreviewProps extends React.HTMLAttributes<HTMLDivElement> {
  /** 二维码 Data URL */
  qrCodeDataUrl: string;
  /** 下载回调 */
  onDownload: () => void;
  /** 复制回调 */
  onCopy: () => void;
  /** 自定义占位文本，用于空状态提示 */
  placeholderText?: string;
 }
@@ -19,15 +24,22 @@ const QrCodePreview = ({
  className,
  ...props
 }: QrCodePreviewProps) => {
  const { t } = useI18n('qrCode');
  // 空状态下的虚线骨架屏
  if (!qrCodeDataUrl) {
    return (
-      <EmptyPlaceholder
+      <div
-        className={cn('min-h-[200px] p-4', className)}
+        className={cn(
-        messageClassName="text-sm text-muted-foreground max-w-none"
+          'flex flex-col justify-center items-center min-h-[200px] border border-dashed border-input rounded-xl p-4 bg-muted/40',
          className,
        )}
        {...props}
      >
-        {placeholderText || '二维码将显示在这里'}
+        <p className="text-sm text-muted-foreground text-center">
-      </EmptyPlaceholder>
+          {placeholderText || t('qrCode:qrCodeWillShow')}
        </p>
      </div>
    );
  }
@@ -40,23 +52,28 @@ const QrCodePreview = ({
      {...props}
    >
      <div className="flex flex-col items-center w-full max-w-xs">
        {/*
          二维码容器适配：
          在暗黑模式下，纯黑白的二维码如果直接暴露在暗色背景下，会导致手机摄像头极难识别。
          通过裹一层 bg-white 和 p-2，确保黑白对比度绝对安全，同时加入 shadow 增强卡片感。
        */}
        <div className="p-2 bg-white rounded-lg shadow-sm border border-border/40">
          <img
            src={qrCodeDataUrl}
            alt="QR Code Preview"
-            className="w-48 h-48 max-w-full object-contain block fade-in-300"
+            className="w-48 h-48 max-w-full object-contain block animate-in fade-in duration-300"
          />
        </div>
        <div className="flex w-full gap-2 mt-3">
          <Button variant="outline" size="sm" onClick={onDownload} className="flex-1 h-8">
            <Download className="w-3.5 h-3.5 text-muted-foreground" />
-            <span className="truncate text-xs">下载二维码</span>
+            <span className="truncate text-xs">{t('qrCode:downloadButton')}</span>
          </Button>
          <Button variant="default" size="sm" onClick={onCopy} className="flex-1 h-8">
            <Copy className="w-3.5 h-3.5" />
-            <span className="truncate text-xs">复制二维码</span>
+            <span className="truncate text-xs">{t('qrCode:copyQrButton')}</span>
          </Button>
        </div>
      </div>
@@ -6,11 +6,11 @@
 | 组件                    | 用途                                                                           |
 | ----------------------- | ------------------------------------------------------------------------------ |
 | `TopBar.tsx`            | 顶部导航栏，集成搜索（含历史记录）、主题切换、语言切换、返回导航               |
 | `RouterContainer.tsx`   | 路由容器，根据当前路由动态渲染对应页面组件，集成错误边界和骨架屏               |
 | `SwitchButtonGroup.tsx` | 通用切换按钮组，支持 `small/medium/large` 三种尺寸，用于页面子模式切换         |
 | `EmptyPlaceholder.tsx`  | 虚线边框空状态占位，统一工具页「暂无结果」提示样式                             |
 | `TextInputArea.tsx`     | 增强文本输入区域，支持校验规则、工具栏操作、字符计数、清空                     |
-| `CopyButton.tsx`        | 一键复制按钮：复制成功后 1.5s 内切换为 Check 图标并应用 `text-emerald-500`；空内容/失败时 `toast` 提示 |
+| `CopyButton.tsx`        | 一键复制按钮，支持复制成功状态动画，封装 `copyTextToClipboard` 和 `toast` 反馈 |
 | `ImageUploader.tsx`     | 图片上传组件，支持拖拽上传、文件选择和预览                                     |
 | `QrCodePreview.tsx`     | 二维码预览组件，展示生成的二维码图片，提供复制和下载操作                       |
 | `DecodeResultPaper.tsx` | Base64 解码结果展示面板，显示 MIME 类型、文件大小、文件名输入和下载按钮        |
@@ -1,73 +1,56 @@
-import { getFeatureByKey } from '@/config/features';
+import { FEATURES, getEntryPointType } from '@/config/features';
 import { loadPage } from '@/config/pageLoaders/index';
 import { useRouter } from '@/providers/RouterProvider';
-import type { PageType } from '@/types/storage';
+import { Suspense } from 'react';
-import { type ComponentType, useEffect, useState } from 'react';
+import { useI18n } from '@/utils/chromeI18n';
 import PageErrorBoundary from '@/components/PageErrorBoundary';
 import PageSkeleton from '@/components/PageSkeleton';
 import { cn } from '@/lib/utils';
 import { AlertTriangle } from 'lucide-react';
-function LoadedPage({ pageKey }: { pageKey: PageType }) {
+const entryPointType = getEntryPointType();
  const [Page, setPage] = useState<ComponentType | null>(null);
  useEffect(() => {
    let cancelled = false;
    loadPage(pageKey)
      .then((mod) => {
        if (!cancelled) {
          setPage(() => mod.default);
        }
      })
      .catch((err) => {
        console.error('[Router Page Load Error]', err);
      });
    return () => {
      cancelled = true;
    };
  }, [pageKey]);
  if (!Page) {
    return <PageSkeleton variant={pageKey === 'dashboard' ? 'dashboard' : 'tool'} />;
  }
  return <Page />;
 }
 export default function RouterContainer() {
-  const { currentPage } = useRouter();
+  const { currentPage, isLoaded } = useRouter();
  const { t } = useI18n('common');
  const animationClass =
    currentPage === 'dashboard' ? 'page-transition-dashboard' : 'page-transition-enter';
-  const currentFeature = getFeatureByKey(currentPage);
+  if (!isLoaded) {
    return <PageSkeleton variant={currentPage === 'dashboard' ? 'dashboard' : 'tool'} />;
  }
  const currentFeature = FEATURES.find((f) => f.key === currentPage);
  const MatchedComponent = currentFeature?.components?.[entryPointType];
  return (
    <div
      key={currentPage}
      className={cn(
        'flex-1 flex flex-col overflow-x-hidden overflow-y-auto',
-        'motion-reduce:transition-none',
+        'scrollbar-gutter-stable motion-reduce:transition-none',
        animationClass,
      )}
    >
-      <PageErrorBoundary resetKey={currentPage}>
+      <Suspense
-        {currentFeature ? (
+        fallback={<PageSkeleton variant={currentPage === 'dashboard' ? 'dashboard' : 'tool'} />}
-          <LoadedPage key={currentPage} pageKey={currentPage} />
+      >
-        ) : (
+        <PageErrorBoundary resetKey={currentPage}>
-          <div className="flex-1 flex flex-col items-center justify-center p-8 text-center fade-in-300">
+          {MatchedComponent ? (
-            <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-destructive/10 text-destructive mb-4">
+            <MatchedComponent />
-              <AlertTriangle className="h-6 w-6" />
+          ) : (
            <div className="flex-1 flex flex-col items-center justify-center p-8 text-center animate-in fade-in duration-300">
              <div className="flex h-12 w-12 items-center justify-center rounded-xl bg-destructive/10 text-destructive mb-4">
                <AlertTriangle className="h-6 w-6" />
              </div>
              <h3 className="text-sm font-semibold text-foreground">{t('router.notFound')}</h3>
              <p className="text-xs text-muted-foreground mt-1 max-w-[240px]">
                {t('router.notFoundDescription', { entryPointType })}
              </p>
            </div>
-            <h3 className="text-sm font-semibold text-foreground">页面未找到</h3>
+          )}
-            <p className="text-xs text-muted-foreground mt-1 max-w-[240px]">
+        </PageErrorBoundary>
-              该功能不存在或已被移除。
+      </Suspense>
            </p>
          </div>
        )}
      </PageErrorBoundary>
    </div>
  );
 }
@@ -1,5 +1,4 @@
 import React from 'react';
 import { Button } from '@/components/ui/button';
 import { cn } from '@/lib/utils';
 export interface SwitchOption<T extends string | number = string> {
@@ -18,15 +17,6 @@ export interface SwitchButtonGroupProps<T extends string | number = string> exte
  buttonClassName?: string;
 }
 const SIZE_CLASSES = {
  small: 'text-xs h-8 px-2 py-1 rounded-md',
  medium: 'text-sm h-9 px-3 py-1.5 rounded-md',
  large: 'text-base h-11 px-4 py-2 rounded-lg',
 } as const;
 const SELECTED_CLASSES = 'bg-background text-foreground shadow-sm font-semibold fade-in-zoom-95';
 const UNSELECTED_CLASSES = 'hover:bg-background/50 hover:text-foreground/80';
 export default function SwitchButtonGroup<T extends string | number = string>({
  value,
  options,
@@ -36,6 +26,12 @@ export default function SwitchButtonGroup<T extends string | number = string>({
  buttonClassName,
  ...props
 }: SwitchButtonGroupProps<T>) {
  const sizeClasses = {
    small: 'text-xs h-8 px-2 py-1 rounded-md',
    medium: 'text-sm h-9 px-3 py-1.5 rounded-md',
    large: 'text-base h-11 px-4 py-2 rounded-lg',
  };
  return (
    <div
      className={cn(
@@ -44,22 +40,29 @@ export default function SwitchButtonGroup<T extends string | number = string>({
      )}
      {...props}
    >
-      {options.map((option) => (
+      {options.map((option) => {
-        <Button
+        const isSelected = value === option.value;
-          key={option.value}
+
-          type="button"
+        return (
-          variant="ghost"
+          <button
-          onClick={() => onChange(option.value)}
+            key={option.value}
-          className={cn(
+            type="button"
-            'flex-1 transition-all',
+            onClick={() => onChange(option.value)}
-            SIZE_CLASSES[size],
+            className={cn(
-            value === option.value ? SELECTED_CLASSES : UNSELECTED_CLASSES,
+              'flex-1 inline-flex items-center justify-center font-medium whitespace-nowrap transition-all',
-            buttonClassName,
+              'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-offset-2',
-          )}
+              'disabled:pointer-events-none disabled:opacity-50',
-        >
+              sizeClasses[size],
-          {option.label}
+              isSelected
-        </Button>
+                ? 'bg-background text-foreground shadow-sm font-semibold animate-in fade-in-50 zoom-in-95 duration-150'
-      ))}
+                : 'hover:bg-background/50 hover:text-foreground/80',
              buttonClassName,
            )}
          >
            {option.label}
          </button>
        );
      })}
    </div>
  );
 }
@@ -1,9 +1,9 @@
 import React, { forwardRef, useCallback, useImperativeHandle, useRef, useState } from 'react';
 import { X } from 'lucide-react';
 import { useI18n } from '@/utils/chromeI18n';
 import { cn } from '@/lib/utils';
-import { toast } from 'sonner';
+import { toast } from 'sonner'; // 推荐使用 shadcn 的默认 Toast
 import { CopyButton } from '@/components/CopyButton';
 import { Button } from './ui/button';
 export type ValidateRule = {
  validator: (value: string) => boolean;
@@ -44,6 +44,7 @@ export interface TextInputAreaProps extends Omit<
  onClear?: () => void;
 }
 // 提炼基础的 ActionButton，全面向 shadcn 核心 Button 样式对齐
 function ActionButton({
  action,
  value,
@@ -113,7 +114,8 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
  const [internalValue, setInternalValue] = useState(defaultValue);
  const [error, setError] = useState<string>('');
-  const placeholder = placeholderProp ?? '请输入文本';
+  const { t } = useI18n('common');
  const placeholder = placeholderProp ?? t('textInputArea.placeholder');
  const isControlled = controlledValue !== undefined;
  const value = isControlled ? controlledValue : internalValue;
@@ -125,6 +127,7 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
    const textArea = internalRef.current;
    if (!textArea) return;
    // 重置高度计算
    textArea.style.height = 'auto';
    const computedMin = minRows * 24;
@@ -156,7 +159,7 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
    const newVal = e.target.value;
    if (maxLength && newVal.length > maxLength) {
-      const msg = `内容不能超过 ${maxLength} 个字符`;
+      const msg = t('charCount', { count: maxLength });
      setError(msg);
      toast.warning(msg);
      return;
@@ -178,9 +181,9 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
    onChange?.('');
    setError('');
    internalRef.current?.focus();
-    toast.success('已清空');
+    toast.success(t('textInputArea.cleared'));
    onClear?.();
-  }, [isControlled, onChange, onClear]);
+  }, [isControlled, onChange, onClear, t]);
  const handleAction = useCallback(
    (action: ToolbarAction) => {
@@ -253,6 +256,7 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
        {hasBottomBar && (
          <div className="flex h-10 items-center justify-between px-4 bg-muted/30 border-t border-border/50">
            {/* 左侧自定义动作 */}
            <div className="flex items-center gap-1.5 min-w-0">
              {bottomActions.map((action) => (
                <ActionButton
@@ -265,35 +269,34 @@ const TextInputArea = forwardRef<HTMLTextAreaElement, TextInputAreaProps>((props
              ))}
            </div>
            {/* 右侧系统按钮组 */}
            <div className="flex items-center gap-1.5 ml-auto shrink-0">
              {allowCopy && value && (
                <CopyButton
                  text={value}
-                  tooltip="复制内容"
+                  tooltip={t('textInputArea.copyContent')}
-                  variant="ghost"
+                  size="sm"
-                  size="iconSm"
+                  className="h-7 w-7 p-1"
                  className="text-muted-foreground hover:text-foreground"
                />
              )}
              {showClear && value && !disabled && !readOnly && (
-                <Button
+                <button
                  type="button"
                  onClick={handleClear}
-                  aria-label="清空"
+                  aria-label={t('textInputArea.clear')}
-                  variant="ghost"
+                  className="p-1 h-7 w-7 flex items-center justify-center rounded-md text-muted-foreground hover:text-destructive hover:bg-destructive/10 transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
                  size="iconSm"
                  className="text-muted-foreground hover:text-destructive hover:bg-destructive/10"
                >
                  <X className="h-4 w-4" />
-                </Button>
+                </button>
              )}
            </div>
          </div>
        )}
      </div>
      {/* 错误提示 */}
      {displayError && (
-        <p className="text-xs font-medium text-destructive px-0.5 fade-in-slide-top-1">
+        <p className="text-xs font-medium text-destructive px-0.5 animate-in fade-in slide-in-from-top-1 duration-150">
          {displayError}
        </p>
      )}
@@ -0,0 +1,313 @@
 import React, { useEffect, useMemo, useRef, useState } from 'react';
 import { ArrowLeft, ExternalLink, Monitor, Moon, Search, Sun, X } from 'lucide-react';
 import { useRouter } from '@/providers/RouterProvider';
 import { useThemeMode } from '@/providers/ThemeModeProvider';
 import { FeatureConfig, FEATURES } from '@/config/features';
 import { storageUtil } from '@/utils/chromeStorage';
 import { openExtensionPage } from '@/utils/chromeTabs';
 import { useI18n } from '@/utils/chromeI18n';
 import { cn } from '@/lib/utils';
 const SEARCH_HISTORY_LIMIT = 10;
 const SEARCH_HISTORY_DISPLAY = 5;
 export default function TopBar() {
  const { currentPage, goBack, navigateTo } = useRouter();
  const { mode, setMode } = useThemeMode();
  const { t } = useI18n(['common', 'features']);
  const [searchQuery, setSearchQuery] = useState('');
  const [showResults, setShowResults] = useState(false);
  const [searchHistory, setSearchHistory] = useState<string[]>([]);
  const [selectedIndex, setSelectedIndex] = useState(-1);
  const containerRef = useRef<HTMLDivElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);
  const handleOpenInTab = async () => {
    await openExtensionPage('popup.html', { mode: 'tab' });
    window.close();
  };
  useEffect(() => {
    const handleClickOutside = (event: MouseEvent) => {
      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
        setShowResults(false);
      }
    };
    document.addEventListener('mousedown', handleClickOutside);
    return () => document.removeEventListener('mousedown', handleClickOutside);
  }, []);
  // Cmd/Ctrl+K 快捷键聚焦搜索框
  useEffect(() => {
    const handleGlobalKeyDown = (e: KeyboardEvent) => {
      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
        e.preventDefault();
        inputRef.current?.focus();
        setShowResults(true);
      }
    };
    document.addEventListener('keydown', handleGlobalKeyDown);
    return () => document.removeEventListener('keydown', handleGlobalKeyDown);
  }, []);
  useEffect(() => {
    storageUtil
      .get('app/searchHistory', [])
      .then((history) => {
        if (history) setSearchHistory(history);
      })
      .catch((err) => console.error('加载搜索历史失败:', err));
  }, []);
  const searchResults = useMemo(() => {
    const query = searchQuery.trim().toLowerCase();
    if (!query) return [];
    return FEATURES.filter((f) => {
      if (f.key === 'dashboard') return false;
      return (
        t(f.labelKey).toLowerCase().includes(query) ||
        t(f.descriptionKey).toLowerCase().includes(query)
      );
    });
  }, [searchQuery, t]);
  const displayedHistory = useMemo(() => {
    if (searchQuery.trim()) return [];
    return searchHistory
      .slice(0, SEARCH_HISTORY_DISPLAY)
      .map((key) => ({ key, feature: FEATURES.find((f) => f.key === key) }))
      .filter((item) => item.feature && item.feature.key !== 'dashboard');
  }, [searchHistory, searchQuery]);
  const saveToHistory = async (featureKey: string) => {
    if (!featureKey.trim()) return;
    const nextHistory = [featureKey, ...searchHistory.filter((h) => h !== featureKey)].slice(
      0,
      SEARCH_HISTORY_LIMIT,
    );
    setSearchHistory(nextHistory);
    await storageUtil.set('app/searchHistory', nextHistory).catch((err) => console.error(err));
  };
  const handleSelectFeature = (feature: FeatureConfig) => {
    navigateTo(feature.key);
    saveToHistory(feature.key);
    setSearchQuery('');
    setShowResults(false);
  };
  const cycleThemeMode = () => {
    const nextMap = { light: 'dark', dark: 'system', system: 'light' } as const;
    setMode(nextMap[mode]);
  };
  const ThemeIcon = mode === 'light' ? Sun : mode === 'dark' ? Moon : Monitor;
  const handleKeyDown = (e: React.KeyboardEvent) => {
    const totalItems = searchQuery.trim() ? searchResults.length : displayedHistory.length;
    if (e.key === 'ArrowDown') {
      e.preventDefault();
      setSelectedIndex((prev) => (prev < totalItems - 1 ? prev + 1 : prev));
    } else if (e.key === 'ArrowUp') {
      e.preventDefault();
      setSelectedIndex((prev) => (prev > 0 ? prev - 1 : prev));
    } else if (e.key === 'Enter') {
      e.preventDefault();
      if (selectedIndex >= 0 && selectedIndex < totalItems) {
        if (searchQuery.trim()) {
          handleSelectFeature(searchResults[selectedIndex]);
        } else {
          const selected = displayedHistory[selectedIndex];
          if (selected?.feature) {
            handleSelectFeature(selected.feature);
          }
        }
      } else if (searchQuery.trim() && searchResults.length > 0) {
        handleSelectFeature(searchResults[0]);
      }
    } else if (e.key === 'Escape') {
      setShowResults(false);
      inputRef.current?.blur();
    }
  };
  const isDashboard = currentPage === 'dashboard';
  return (
    <header className="flex h-14 items-center justify-between border-b border-border bg-background px-4 relative z-50">
      {/* 左侧：返回按钮区 */}
      <div className="flex w-10 items-center justify-start">
        {!isDashboard && (
          <button
            type="button"
            onClick={goBack}
            aria-label={t('common_buttons_back')}
            className="flex h-8 w-8 items-center justify-center rounded-md border border-input bg-background text-muted-foreground shadow-sm transition-colors hover:bg-accent hover:text-accent-foreground"
          >
            <ArrowLeft className="h-4 w-4" />
          </button>
        )}
      </div>
      {/* 中间：搜索容器 */}
      <div ref={containerRef} className="flex-1 mx-4 max-w-md relative">
        <div className="relative group">
          <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground/60 group-focus-within:text-muted-foreground transition-colors pointer-events-none" />
          <input
            ref={inputRef}
            type="text"
            placeholder={t('common_buttons_search')}
            value={searchQuery}
            onChange={(e) => {
              setSearchQuery(e.target.value);
              setShowResults(true);
              setSelectedIndex(-1);
            }}
            onFocus={() => setShowResults(true)}
            onKeyDown={handleKeyDown}
            aria-label={t('common_buttons_search')}
            className="w-full h-9 pl-9 pr-16 text-sm rounded-lg border border-border/60 bg-muted/40 transition-all placeholder:text-muted-foreground/50 focus:bg-background focus:outline-none focus:ring-1 focus:ring-ring focus:border-input"
          />
          {!searchQuery && (
            <kbd className="absolute right-3 top-1/2 -translate-y-1/2 hidden sm:inline-flex h-5 items-center gap-0.5 rounded border border-border/60 bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground/60 pointer-events-none">
              ⌘K
            </kbd>
          )}
          {searchQuery && (
            <button
              type="button"
              onClick={() => {
                setSearchQuery('');
                setSelectedIndex(-1);
              }}
              aria-label={t('common:buttons.clearSearch')}
              className="absolute right-2 top-1/2 -translate-y-1/2 p-1 rounded-md text-muted-foreground hover:text-foreground transition-colors"
            >
              <X className="h-3 w-3" />
            </button>
          )}
        </div>
        {/* 动态联想结果卡片 */}
        {showResults && (searchQuery.trim() || displayedHistory.length > 0) && (
          <div className="absolute top-full left-0 right-0 mt-1.5 bg-popover text-popover-foreground rounded-lg shadow-lg border border-border max-h-80 overflow-y-auto z-50 animate-in fade-in slide-in-from-top-2 duration-150">
            <ul role="listbox" className="p-1.5">
              {searchQuery.trim() ? (
                searchResults.length > 0 ? (
                  searchResults.map((feature, index) => (
                    <li
                      key={feature.key}
                      role="option"
                      aria-selected={selectedIndex === index}
                      onClick={() => handleSelectFeature(feature)}
                      className={cn(
                        'flex items-center gap-3 px-3 py-2.5 rounded-md cursor-pointer text-sm transition-colors',
                        selectedIndex === index
                          ? 'bg-accent text-accent-foreground'
                          : 'hover:bg-muted/60',
                      )}
                    >
                      <div
                        className={cn(
                          'flex h-8 w-8 shrink-0 items-center justify-center rounded-lg',
                          'bg-muted/80 text-muted-foreground',
                        )}
                      >
                        {feature.icon && <feature.icon className="h-4 w-4" />}
                      </div>
                      <div className="flex-1 min-w-0">
                        <p className="font-medium text-foreground truncate">
                          {t(feature.labelKey)}
                        </p>
                        <p className="text-xs text-muted-foreground truncate mt-0.5">
                          {t(feature.descriptionKey)}
                        </p>
                      </div>
                    </li>
                  ))
                ) : (
                  <li className="px-4 py-6 text-center text-sm text-muted-foreground">
                    {t('common:buttons.noResults')}
                  </li>
                )
              ) : (
                <>
                  <div className="px-3 py-1.5 text-[11px] font-semibold tracking-wider text-muted-foreground/60 uppercase">
                    {t('common:buttons.recentSearch')}
                  </div>
                  {displayedHistory.map((item, index) => (
                    <li
                      key={item.key}
                      role="option"
                      aria-selected={selectedIndex === index}
                      onClick={() => item.feature && handleSelectFeature(item.feature)}
                      className={cn(
                        'flex items-center gap-3 px-3 py-2 rounded-md cursor-pointer text-sm transition-colors',
                        selectedIndex === index
                          ? 'bg-accent text-accent-foreground'
                          : 'hover:bg-muted/60',
                      )}
                    >
                      <div
                        className={cn(
                          'flex h-8 w-8 shrink-0 items-center justify-center rounded-lg',
                          'bg-muted/80 text-muted-foreground',
                        )}
                      >
                        {item.feature?.icon && <item.feature.icon className="h-4 w-4" />}
                      </div>
                      <div className="flex-1 min-w-0">
                        <p className="font-medium text-foreground truncate">
                          {item.feature && t(item.feature.labelKey)}
                        </p>
                        <p className="text-xs text-muted-foreground truncate mt-0.5">
                          {item.feature && t(item.feature.descriptionKey)}
                        </p>
                      </div>
                    </li>
                  ))}
                </>
              )}
            </ul>
          </div>
        )}
      </div>
      {/* 右侧：操作区 */}
      <div className="flex items-center gap-1 shrink-0">
        <IconButton onClick={cycleThemeMode} title={t(`common:buttons.themeMode.${mode}`)}>
          <ThemeIcon className="h-4 w-4" />
        </IconButton>
        <IconButton onClick={handleOpenInTab} title={t('common:buttons.openInTab')}>
          <ExternalLink className="h-4 w-4" />
        </IconButton>
      </div>
    </header>
  );
 }
 // 5. 提炼出高度复用的原子按钮，大幅精简 Tailwind 冗余，符合 shadcn 的灵巧风格
 function IconButton({
  children,
  onClick,
  title,
 }: {
  children: React.ReactNode;
  onClick: () => void;
  title: string;
 }) {
  return (
    <button
      type="button"
      onClick={onClick}
      title={title}
      aria-label={title}
      className="flex h-8 w-8 items-center justify-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
    >
      {children}
    </button>
  );
 }
@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { act, render, screen } from '@testing-library/react';
+import { act, render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 // unmock the globally-mocked component so we test the real implementation
@@ -45,6 +45,29 @@ describe('CopyButton', () => {
    expect(mockedToast.success).toHaveBeenCalled();
  });
  it('复制成功后图标切换为 Check，1.5 秒后恢复', async () => {
    mockedCopy.mockResolvedValue(true);
    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
    render(<CopyButton text="test" />);
    // 点击后复制成功，按钮获得 emerald 样式（说明切到了 Check 状态）
    await user.click(screen.getByRole('button'));
    await waitFor(() => {
      expect(screen.getByRole('button').className).toContain('text-emerald');
    });
    // 1.5 秒后样式恢复
    act(() => {
      vi.advanceTimersByTime(1500);
    });
    await waitFor(() => {
      expect(screen.getByRole('button').className).not.toContain('text-emerald');
    });
  });
  it('复制空文本时弹出 error toast', async () => {
    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
@@ -68,10 +91,15 @@ describe('CopyButton', () => {
    expect(mockedToast.error).toHaveBeenCalled();
  });
-  it('初始渲染时带有默认 aria-label', () => {
+  // ==================== 新增测试 ====================
  it('初始渲染时显示 Copy 图标且无 emerald 样式', () => {
    render(<CopyButton text="initial" />);
-    expect(screen.getByRole('button')).toHaveAttribute('aria-label', '复制');
+    const button = screen.getByRole('button');
    expect(button.className).not.toContain('text-emerald');
    // 通过 aria-label 确认按钮存在，图标由 lucide 渲染为 svg
    expect(button).toHaveAttribute('aria-label');
  });
  it('自定义 tooltip 会覆盖默认 title 和 aria-label', () => {
@@ -114,12 +142,15 @@ describe('CopyButton', () => {
    await user.click(screen.getByRole('button'));
    // 在 1.5 秒超时到期前卸载组件
    act(() => {
      vi.advanceTimersByTime(500);
    });
    // 卸载不应抛出 "Can't perform a React state update on an unmounted component" 警告
    expect(() => unmount()).not.toThrow();
    // 前进剩余时间，确认没有异常
    act(() => {
      vi.advanceTimersByTime(2000);
    });
@@ -133,15 +164,23 @@ describe('CopyButton', () => {
    const button = screen.getByRole('button');
    // 快速点击 3 次
    await user.click(button);
    await user.click(button);
    await user.click(button);
    // copyTextToClipboard 应该被调用 3 次（每次点击都执行）
    expect(mockedCopy).toHaveBeenCalledTimes(3);
    // 但 setTimeout 相关的 clearTimeout + setTimeout 组合应正常工作
    //  advance 1.5 秒后，copied 状态应恢复为 false
    act(() => {
      vi.advanceTimersByTime(1500);
    });
    await waitFor(() => {
      expect(button.className).not.toContain('text-emerald');
    });
  });
  it('其他 button props 通过 ...props 透传', () => {
@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { fireEvent, render, screen } from '@testing-library/react';
-import DecodeResultPaper from '../components/DecodeResultPaper';
+import DecodeResultPaper from '@/components/DecodeResultPaper';
 describe('DecodeResultPaper 组件', () => {
  const defaultProps = {
@@ -27,7 +27,7 @@ describe('DecodeResultPaper 组件', () => {
      expect(screen.getByText(/image\/png/)).toBeInTheDocument();
    });
-    it('应通过 formatBytes 渲染文件大小', () => {
+    it('应通过 formatFileSize 渲染文件大小', () => {
      render(<DecodeResultPaper {...{ ...defaultProps, blobSize: 1536 }} />);
      expect(screen.getByText(/1\.5 KB/)).toBeInTheDocument();
    });
@@ -1,48 +0,0 @@
 import { describe, expect, it } from 'vitest';
 import { render, screen } from '@testing-library/react';
 import EmptyPlaceholder from '@/components/EmptyPlaceholder';
 describe('EmptyPlaceholder 组件', () => {
  it('应渲染字符串提示文本', () => {
    render(<EmptyPlaceholder>请输入内容</EmptyPlaceholder>);
    expect(screen.getByText('请输入内容')).toBeInTheDocument();
  });
  it('应应用规范空状态容器样式', () => {
    const { container } = render(<EmptyPlaceholder>提示</EmptyPlaceholder>);
    const placeholder = container.firstChild;
    expect(placeholder).toHaveClass(
      'rounded-xl',
      'bg-muted/30',
      'border-dashed',
      'border-border/80',
      'min-h-[120px]',
    );
  });
  it('应支持 className 自定义容器样式', () => {
    const { container } = render(
      <EmptyPlaceholder className="flex-1 min-h-[320px]">提示</EmptyPlaceholder>,
    );
    expect(container.firstChild).toHaveClass('flex-1', 'min-h-[320px]');
  });
  it('应支持 messageClassName 自定义文本样式', () => {
    render(<EmptyPlaceholder messageClassName="text-sm max-w-none">提示</EmptyPlaceholder>);
    expect(screen.getByText('提示')).toHaveClass('text-sm', 'max-w-none');
  });
  it('应支持 ReactNode 类型的 children', () => {
    render(
      <EmptyPlaceholder>
        <span data-testid="custom-content">自定义内容</span>
      </EmptyPlaceholder>,
    );
    expect(screen.getByTestId('custom-content')).toBeInTheDocument();
  });
 });
@@ -1,11 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { act, fireEvent, render, screen } from '@testing-library/react';
-import ImageUploader from '../components/ImageUploader';
+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 });
@@ -21,6 +23,7 @@ vi.mock('sonner', () => ({
 describe('ImageUploader 组件', () => {
  const mockOnFileChange = vi.fn();
  const mockOnClearFile = vi.fn();
  const mockOnPreviewUrlChange = vi.fn();
  const mockOnDraggingChange = vi.fn();
  const defaultProps = {
@@ -28,6 +31,7 @@ describe('ImageUploader 组件', () => {
    onFileChange: mockOnFileChange,
    onClearFile: mockOnClearFile,
    previewUrl: '',
    onPreviewUrlChange: mockOnPreviewUrlChange,
    dragging: false,
    onDraggingChange: mockOnDraggingChange,
  };
@@ -91,7 +95,7 @@ describe('ImageUploader 组件', () => {
  });
  describe('文件选择交互', () => {
-    it('选择文件时应调用 onFileChange', async () => {
+    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' });
@@ -101,7 +105,8 @@ describe('ImageUploader 组件', () => {
      });
      expect(mockOnFileChange).toHaveBeenCalledWith(mockFile);
-      expect(mockOnFileChange).toHaveBeenCalledTimes(1);
+      expect(mockCreateObjectURL).toHaveBeenCalledWith(mockFile);
      expect(mockOnPreviewUrlChange).toHaveBeenCalledWith('blob:test-url');
    });
  });
@@ -122,7 +127,7 @@ describe('ImageUploader 组件', () => {
      expect(mockOnDraggingChange).toHaveBeenCalledWith(false);
    });
-    it('放置文件时应调用 onFileChange', () => {
+    it('放置文件时应调用 onFileChange 和 onPreviewUrlChange', () => {
      const { container } = render(<ImageUploader {...defaultProps} />);
      const dropzone = container.firstChild as HTMLElement;
      const mockFile = new File(['test'], 'test.png', { type: 'image/png' });
@@ -141,7 +146,6 @@ describe('ImageUploader 组件', () => {
      expect(mockOnDraggingChange).toHaveBeenCalledWith(false);
      expect(mockOnFileChange).toHaveBeenCalledWith(mockFile);
      expect(mockOnFileChange).toHaveBeenCalledTimes(1);
    });
  });
@@ -161,12 +165,37 @@ describe('ImageUploader 组件', () => {
  });
  describe('粘贴功能', () => {
-    it('不应注册 document 粘贴事件监听（由 ParsePanel 统一处理）', () => {
+    it('监听粘贴事件', () => {
      const addEventListenerSpy = vi.spyOn(document, 'addEventListener');
      render(<ImageUploader {...defaultProps} />);
-      const pasteListeners = addEventListenerSpy.mock.calls.filter(([event]) => event === 'paste');
+      expect(addEventListenerSpy).toHaveBeenCalledWith('paste', expect.any(Function));
-      expect(pasteListeners).toHaveLength(0);
+    });
    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();
    });
  });
 });
@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { fireEvent, render, screen } from '@testing-library/react';
-import QrCodePreview from '../components/QrCodePreview';
+import QrCodePreview from '@/components/QrCodePreview';
 describe('QrCodePreview 组件', () => {
  const mockOnDownload = vi.fn();
@@ -9,13 +9,12 @@ const mockRouterValue = {
  currentPage: 'dashboard' as PageType,
  visiblePages: ['dashboard', 'timestamp'] as PageType[],
  pageOrder: ['timestamp'] as PageType[],
  isLoaded: true,
  navigateTo: vi.fn(),
  syncNavigation: vi.fn(),
-  goHome: vi.fn(),
+  goBack: vi.fn(),
  setVisiblePages: vi.fn(),
  setPageOrder: vi.fn(),
  recentlyUsedTools: [] as PageType[],
  isLoaded: true,
 };
 vi.mock('@/providers/RouterProvider', () => ({
@@ -33,7 +32,16 @@ describe('RouterContainer 组件', () => {
  };
  describe('渲染测试', () => {
-    it('mount 后应直接渲染页面结构（不等待 storage 加载）', () => {
+    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();
@@ -69,7 +77,8 @@ describe('RouterContainer 组件', () => {
  });
  describe('页面级错误隔离', () => {
-    it('PageErrorBoundary 应包裹页面内容', () => {
+    it('PageErrorBoundary 应包裹在 Suspense 内层', () => {
      mockRouterValue.isLoaded = true;
      mockRouterValue.currentPage = 'dashboard';
      const { container } = renderWithProvider(<RouterContainer />);
@@ -1,6 +1,6 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { fireEvent, render, screen } from '@testing-library/react';
-import { StorageCleanerConfirm } from '@/pages/StorageCleaner/components/StorageCleanerConfirm';
+import { StorageCleanerConfirm } from '@/pages/StorageCleaner/StorageCleanerConfirm';
 import type { StorageCleanerOptions } from '@/types/storage';
 import React from 'react';
@@ -94,7 +94,7 @@ describe('StorageCleanerConfirm 组件', () => {
      renderComponent({ options: partialOptions });
      expect(screen.getByText(/Local Storage/)).toBeInTheDocument();
-      expect(screen.getByText(/IndexedDB/)).toBeInTheDocument();
+      expect(screen.getByText(/站点存储/)).toBeInTheDocument();
      expect(screen.queryByText(/Session Storage/)).not.toBeInTheDocument();
      expect(screen.queryByText(/Cookies$/)).not.toBeInTheDocument();
    });
@@ -18,12 +18,12 @@ describe('TextInputArea 组件', () => {
    it('默认显示清空按钮', () => {
      render(<TextInputArea value="有内容" onChange={() => {}} />);
-      expect(screen.getByRole('button', { name: '清空' })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'textInputArea.clear' })).toBeInTheDocument();
    });
    it('无内容时清空按钮应隐藏', () => {
      render(<TextInputArea value="" onChange={() => {}} />);
-      expect(screen.queryByRole('button', { name: '清空' })).not.toBeInTheDocument();
+      expect(screen.queryByRole('button', { name: 'textInputArea.clear' })).not.toBeInTheDocument();
    });
    it('disabled 时清空按钮应隐藏', () => {
@@ -57,7 +57,7 @@ describe('TextInputArea 组件', () => {
      const handleChange = vi.fn();
      render(<TextInputArea value="内容" onChange={handleChange} />);
-      fireEvent.click(screen.getByRole('button', { name: '清空' }));
+      fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
      expect(handleChange).toHaveBeenCalledWith('');
    });
@@ -81,7 +81,7 @@ describe('TextInputArea 组件', () => {
    it('清空按钮应清空内容', () => {
      render(<TextInputArea defaultValue="内容" />);
-      fireEvent.click(screen.getByRole('button', { name: '清空' }));
+      fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
      expect(screen.getByRole('textbox')).toHaveValue('');
    });
@@ -90,12 +90,14 @@ describe('TextInputArea 组件', () => {
  describe('allowCopy 复制功能', () => {
    it('allowCopy 且有内容时显示复制按钮', () => {
      render(<TextInputArea value="可复制的内容" onChange={() => {}} allowCopy />);
-      expect(screen.getByRole('button', { name: '复制内容' })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'textInputArea.copyContent' })).toBeInTheDocument();
    });
    it('allowCopy 但无内容时隐藏复制按钮', () => {
      render(<TextInputArea value="" onChange={() => {}} allowCopy />);
-      expect(screen.queryByRole('button', { name: '复制内容' })).not.toBeInTheDocument();
+      expect(
        screen.queryByRole('button', { name: 'textInputArea.copyContent' }),
      ).not.toBeInTheDocument();
    });
    it('allowCopy=false 时不显示复制按钮', () => {
@@ -111,7 +113,7 @@ describe('TextInputArea 组件', () => {
      render(<TextInputArea value="测试" onChange={() => {}} allowCopy />);
-      await user.click(screen.getByRole('button', { name: '复制内容' }));
+      await user.click(screen.getByRole('button', { name: 'textInputArea.copyContent' }));
      expect(writeTextSpy).toHaveBeenCalledWith('测试');
    });
@@ -124,7 +126,7 @@ describe('TextInputArea 组件', () => {
      render(<TextInputArea value="测试" onChange={() => {}} allowCopy />);
-      await user.click(screen.getByRole('button', { name: '复制内容' }));
+      await user.click(screen.getByRole('button', { name: 'textInputArea.copyContent' }));
      expect(writeTextSpy).toHaveBeenCalledWith('测试');
    });
@@ -156,7 +158,6 @@ describe('TextInputArea 组件', () => {
      fireEvent.change(textarea, { target: { value: '123456' } });
      expect(handleChange).not.toHaveBeenCalledWith('123456');
      expect(screen.getByText('内容不能超过 5 个字符')).toBeInTheDocument();
    });
    it('未超出 maxLength 的输入应正常触发', () => {
@@ -369,7 +370,7 @@ describe('TextInputArea 组件', () => {
      const writeTextSpy = vi.spyOn(navigator.clipboard, 'writeText').mockResolvedValue(undefined);
      render(<TextInputArea value="测试" onChange={() => {}} allowCopy />);
-      await user.click(screen.getByRole('button', { name: '复制内容' }));
+      await user.click(screen.getByRole('button', { name: 'textInputArea.copyContent' }));
      expect(writeTextSpy).toHaveBeenCalledWith('测试');
    });
@@ -380,7 +381,7 @@ describe('TextInputArea 组件', () => {
      const handleClear = vi.fn();
      render(<TextInputArea value="内容" onChange={() => {}} onClear={handleClear} />);
-      fireEvent.click(screen.getByRole('button', { name: '清空' }));
+      fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
      expect(handleClear).toHaveBeenCalledOnce();
    });
@@ -388,7 +389,7 @@ describe('TextInputArea 组件', () => {
    it('不传 onClear 时清空按钮应正常工作', () => {
      render(<TextInputArea defaultValue="内容" />);
-      fireEvent.click(screen.getByRole('button', { name: '清空' }));
+      fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
      expect(screen.getByRole('textbox')).toHaveValue('');
    });
@@ -2,7 +2,7 @@ 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 '@/layout/TopBar';
+import TopBar from '@/components/TopBar';
 import { RouterProvider } from '@/providers/RouterProvider';
 import { ThemeModeProvider } from '@/providers/ThemeModeProvider';
@@ -27,7 +27,7 @@ const mockRouterValue = {
  isLoaded: true,
  navigateTo: vi.fn(),
  syncNavigation: vi.fn(),
-  goHome: vi.fn(),
+  goBack: vi.fn(),
  setVisiblePages: vi.fn(),
  setPageOrder: vi.fn(),
 };
@@ -54,23 +54,23 @@ describe('TopBar 组件', () => {
    it('不在 dashboard 时应渲染返回按钮', () => {
      mockRouterValue.currentPage = 'timestamp';
      renderWithProvider(<TopBar />);
-      expect(screen.getByLabelText('返回首页')).toBeInTheDocument();
+      expect(screen.getByLabelText('返回')).toBeInTheDocument();
    });
    it('在 dashboard 上不应渲染返回按钮', () => {
      mockRouterValue.currentPage = 'dashboard';
      renderWithProvider(<TopBar />);
-      expect(screen.queryByLabelText('返回首页')).not.toBeInTheDocument();
+      expect(screen.queryByLabelText('返回')).not.toBeInTheDocument();
    });
  });
  describe('交互测试', () => {
-    it('点击返回按钮时应调用 goHome', () => {
+    it('点击返回按钮时应调用 goBack', () => {
      mockRouterValue.currentPage = 'timestamp';
      renderWithProvider(<TopBar />);
-      fireEvent.click(screen.getByLabelText('返回首页'));
+      fireEvent.click(screen.getByLabelText('返回'));
-      expect(mockRouterValue.goHome).toHaveBeenCalledTimes(1);
+      expect(mockRouterValue.goBack).toHaveBeenCalledTimes(1);
    });
  });
 });
@@ -21,7 +21,6 @@ const buttonVariants = cva(
        sm: 'h-9 rounded-md px-3',
        lg: 'h-11 rounded-md px-8',
        icon: 'h-10 w-10',
        iconSm: 'h-7 w-7',
      },
    },
    defaultVariants: {
@@ -16,7 +16,7 @@ const Checkbox = React.forwardRef<
    )}
    {...props}
  >
-    <CheckboxPrimitive.Indicator className="grid place-content-center text-current">
+    <CheckboxPrimitive.Indicator className={cn('grid place-content-center text-current')}>
      <Check className="h-4 w-4" />
    </CheckboxPrimitive.Indicator>
  </CheckboxPrimitive.Root>
@@ -18,7 +18,7 @@ const DialogOverlay = React.forwardRef<
  <DialogPrimitive.Overlay
    ref={ref}
    className={cn(
-      'fixed inset-0 z-50 bg-black/80 dark:bg-black/60 transition-opacity duration-200 data-[state=closed]:opacity-0 data-[state=open]:opacity-100',
+      'fixed inset-0 z-50 bg-black/80 dark:bg-black/60 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
      className,
    )}
    {...props}
@@ -41,7 +41,7 @@ const DialogContent = React.forwardRef<
    <DialogPrimitive.Content
      ref={ref}
      className={cn(
-        'fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-white dark:bg-gray-900 p-6 shadow-lg transition-all duration-200 data-[state=closed]:scale-95 data-[state=open]:scale-100 data-[state=closed]:opacity-0 data-[state=open]:opacity-100 sm:rounded-lg',
+        'fixed left-[50%] top-[50%] z-50 grid w-full max-w-lg translate-x-[-50%] translate-y-[-50%] gap-4 border bg-white dark:bg-gray-900 p-6 shadow-lg duration-200 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%] data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%] sm:rounded-lg',
        className,
      )}
      {...props}
@@ -65,7 +65,7 @@ const SelectContent = React.forwardRef<
    <SelectPrimitive.Content
      ref={ref}
      className={cn(
-        'relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md transition-all duration-200 data-[state=closed]:scale-95 data-[state=open]:scale-100 data-[state=closed]:opacity-0 data-[state=open]:opacity-100',
+        'relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
        position === 'popper' &&
          'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
        className,
@@ -0,0 +1,43 @@
 # config/
 应用级配置目录，存放功能特性的注册中心。
 ## 文件说明
 | 文件           | 用途                                     |
 | -------------- | ---------------------------------------- |
 | `features.tsx` | 核心配置文件，定义所有工具功能的注册信息 |
 ## features.tsx
 `FEATURES` 数组是路由和功能元数据的**单一事实来源**，每个功能定义包含：
 - `key`：页面类型标识（`PageType`）
 - `labelKey` / `descriptionKey`：i18n 翻译键
 - `themeColorKey`：主题色（`primary/success/warning/error/secondary/info`）
 - `icon`：lucide-react 图标组件
 - `defaultVisible`：默认是否可见
 - `components`：三种渲染模式的懒加载组件（`popup`、`sidepanel`、`tab`）
 ## 已注册功能（10 个）
 | key                  | 图标              | 说明              |
 | -------------------- | ----------------- | ----------------- |
 | `dashboard`          | —                 | 仪表盘首页        |
 | `timestamp`          | Clock             | 时间戳转换工具    |
 | `storageCleaner`     | Database          | 存储清理工具      |
 | `qrCode`             | QrCode            | 二维码工具        |
 | `textStatistics`     | FileText          | 文本统计工具      |
 | `jwt`                | Key               | JWT 解析工具      |
 | `jsonDiff`           | GitCompareArrows  | JSON 差异比较工具 |
 | `base64Converter`    | ArrowLeftRight    | Base64 转换器     |
 | `rightClickRestorer` | MousePointerClick | 右键菜单恢复工具  |
 | `testDataGenerator`  | FileSpreadsheet   | 测试数据生成器    |
 ## 导出函数
 - `getFeatureByKey(key)` — 根据 key 获取功能配置
 - `getDefaultVisibleFeatureKeys()` — 获取默认可见的功能 key 列表
 - `getAllFeatureKeys()` — 获取所有功能 key 列表
 - `getDefaultPageOrder()` — 获取默认页面排序（不含 dashboard）
 - `getEntryPointType()` — 判断当前入口类型（popup/sidepanel/tab）
@@ -1,87 +0,0 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 const pageLoadTracker = vi.hoisted(() => ({
  loaded: [] as string[],
 }));
 vi.mock('@/pages/Dashboard', () => {
  pageLoadTracker.loaded.push('Dashboard');
  return { default: () => null };
 });
 vi.mock('@/pages/Timestamp', () => {
  pageLoadTracker.loaded.push('Timestamp');
  return { default: () => null };
 });
 vi.mock('@/pages/StorageCleaner', () => {
  pageLoadTracker.loaded.push('StorageCleaner');
  return { default: () => null };
 });
 vi.mock('@/pages/QrCode', () => {
  pageLoadTracker.loaded.push('QrCode');
  return { default: () => null };
 });
 vi.mock('@/pages/TextStatistics', () => {
  pageLoadTracker.loaded.push('TextStatistics');
  return { default: () => null };
 });
 vi.mock('@/pages/Jwt', () => {
  pageLoadTracker.loaded.push('Jwt');
  return { default: () => null };
 });
 vi.mock('@/pages/JsonTools', () => {
  pageLoadTracker.loaded.push('JsonTools');
  return { default: () => null };
 });
 vi.mock('@/pages/Base64Converter', () => {
  pageLoadTracker.loaded.push('Base64Converter');
  return { default: () => null };
 });
 vi.mock('@/pages/RightClickRestorer', () => {
  pageLoadTracker.loaded.push('RightClickRestorer');
  return { default: () => null };
 });
 vi.mock('@/pages/TestDataGenerator', () => {
  pageLoadTracker.loaded.push('TestDataGenerator');
  return { default: () => null };
 });
 describe('features 懒加载', () => {
  beforeEach(() => {
    pageLoadTracker.loaded.length = 0;
    vi.resetModules();
  });
  it('仅导入工具函数时不应加载任何页面模块', async () => {
    const { getAllFeatureKeys, getDefaultPageOrder } = await import('@/config/features');
    getAllFeatureKeys();
    getDefaultPageOrder();
    expect(pageLoadTracker.loaded).toEqual([]);
  });
  it('访问 FEATURES 元数据时不应加载任何页面模块', async () => {
    const { FEATURES } = await import('@/config/features');
    expect(FEATURES).toHaveLength(10);
    expect(pageLoadTracker.loaded).toEqual([]);
  });
  it('loadPage 应仅加载对应页面模块', async () => {
    const { loadPage } = await import('@/config/pageLoaders/index');
    await loadPage('dashboard');
    expect(pageLoadTracker.loaded).toEqual(['Dashboard']);
  });
  it('loadPage 切换页面时不应加载无关页面模块', async () => {
    const { loadPage } = await import('@/config/pageLoaders/index');
    await loadPage('timestamp');
    expect(pageLoadTracker.loaded).toEqual(['Timestamp']);
    expect(pageLoadTracker.loaded).not.toContain('QrCode');
    expect(pageLoadTracker.loaded).not.toContain('TestDataGenerator');
  });
 });
@@ -9,22 +9,27 @@ import {
 describe('features', () => {
  describe('FEATURES', () => {
-    it('应该有10个功能定义', () => {
+    it('should have 10 features defined', () => {
      expect(FEATURES).toHaveLength(10);
    });
-    it('应该有每个功能的所有必需属性', () => {
+    it('should have all required properties for each feature', () => {
      FEATURES.forEach((feature) => {
        expect(feature).toHaveProperty('key');
-        expect(feature).toHaveProperty('label');
+        expect(feature).toHaveProperty('labelKey');
-        expect(feature).toHaveProperty('description');
+        expect(feature).toHaveProperty('descriptionKey');
        expect(feature).toHaveProperty('defaultVisible');
-        expect(feature).not.toHaveProperty('component');
+        expect(feature).toHaveProperty('components');
        expect(typeof feature.key).toBe('string');
-        expect(typeof feature.label).toBe('string');
+        expect(typeof feature.labelKey).toBe('string');
-        expect(typeof feature.description).toBe('string');
+        expect(typeof feature.descriptionKey).toBe('string');
        expect(typeof feature.defaultVisible).toBe('boolean');
        expect(typeof feature.components).toBe('object');
        expect(feature.components).toHaveProperty('popup');
        expect(feature.components).toHaveProperty('sidepanel');
        expect(feature.components).toHaveProperty('tab');
        // Optional UI properties for non-hidden features
        if (feature.key !== 'dashboard') {
          expect(feature).toHaveProperty('icon');
          expect(feature).toHaveProperty('themeColorKey');
@@ -33,7 +38,7 @@ describe('features', () => {
      });
    });
-    it('应该有每个功能的唯一key', () => {
+    it('should have unique keys for each feature', () => {
      const keys = FEATURES.map((f) => f.key);
      const uniqueKeys = new Set(keys);
      expect(uniqueKeys.size).toBe(keys.length);
@@ -41,36 +46,36 @@ describe('features', () => {
  });
  describe('getFeatureByKey', () => {
-    it('应该返回dashboard功能', () => {
+    it('should return dashboard feature', () => {
      const feature = getFeatureByKey('dashboard');
      expect(feature).toBeDefined();
      expect(feature?.key).toBe('dashboard');
-      expect(feature?.label).toBe('仪表盘');
+      expect(feature?.labelKey).toBe('dashboard_title');
    });
-    it('应该返回时间戳功能', () => {
+    it('should return timestamp feature', () => {
      const feature = getFeatureByKey('timestamp');
      expect(feature).toBeDefined();
      expect(feature?.key).toBe('timestamp');
-      expect(feature?.label).toBe('时间戳');
+      expect(feature?.labelKey).toBe('timestamp_title');
      expect(feature?.themeColorKey).toBeDefined();
    });
-    it('应该返回存储清理功能', () => {
+    it('should return storageCleaner feature', () => {
      const feature = getFeatureByKey('storageCleaner');
      expect(feature).toBeDefined();
      expect(feature?.key).toBe('storageCleaner');
-      expect(feature?.label).toBe('存储清理');
+      expect(feature?.labelKey).toBe('storageCleaner_title');
    });
-    it('应该返回undefined用于无效的key', () => {
+    it('should return undefined for invalid key', () => {
      const feature = getFeatureByKey('invalid' as any);
      expect(feature).toBeUndefined();
    });
  });
  describe('getDefaultVisibleFeatureKeys', () => {
-    it('应该返回仅可见的功能', () => {
+    it('should return only visible features', () => {
      const visibleKeys = getDefaultVisibleFeatureKeys();
      visibleKeys.forEach((key) => {
        const feature = getFeatureByKey(key);
@@ -78,7 +83,7 @@ describe('features', () => {
      });
    });
-    it('应该包含仪表盘、时间戳、存储清理、二维码', () => {
+    it('should include dashboard, timestamp, storageCleaner, qrCode', () => {
      const visibleKeys = getDefaultVisibleFeatureKeys();
      expect(visibleKeys).toContain('dashboard');
      expect(visibleKeys).toContain('timestamp');
@@ -88,7 +93,7 @@ describe('features', () => {
  });
  describe('getAllFeatureKeys', () => {
-    it('应该返回所有功能key', () => {
+    it('should return all feature keys', () => {
      const allKeys = getAllFeatureKeys();
      expect(allKeys).toHaveLength(10);
      expect(allKeys).toContain('dashboard');
@@ -97,7 +102,7 @@ describe('features', () => {
      expect(allKeys).toContain('qrCode');
      expect(allKeys).toContain('textStatistics');
      expect(allKeys).toContain('jwt');
-      expect(allKeys).toContain('jsonTools');
+      expect(allKeys).toContain('jsonDiff');
      expect(allKeys).toContain('base64Converter');
      expect(allKeys).toContain('rightClickRestorer');
      expect(allKeys).toContain('testDataGenerator');
@@ -105,19 +110,19 @@ describe('features', () => {
  });
  describe('getDefaultPageOrder', () => {
-    it('应该排除仪表盘从页面顺序', () => {
+    it('should exclude dashboard from page order', () => {
      const pageOrder = getDefaultPageOrder();
      expect(pageOrder).not.toContain('dashboard');
    });
-    it('应该包含时间戳、存储清理、二维码在页面顺序', () => {
+    it('should include timestamp, storageCleaner, qrCode in page order', () => {
      const pageOrder = getDefaultPageOrder();
      expect(pageOrder).toContain('timestamp');
      expect(pageOrder).toContain('storageCleaner');
      expect(pageOrder).toContain('qrCode');
    });
-    it('应该有9个项目在页面顺序', () => {
+    it('should have 9 items in page order', () => {
      const pageOrder = getDefaultPageOrder();
      expect(pageOrder).toHaveLength(9);
    });
@@ -1,122 +0,0 @@
 import type { ComponentType } from 'react';
 import type { LucideProps } from 'lucide-react';
 import type { PageType } from '@/types/storage';
 import {
  Clock,
  Database,
  QrCode,
  FileText,
  Key,
  GitCompareArrows,
  ArrowLeftRight,
  MousePointerClick,
  FileSpreadsheet,
 } from 'lucide-react';
 export type PaletteColorKey = 'primary' | 'success' | 'warning' | 'error' | 'secondary' | 'info';
 export interface FeatureConfig {
  key: PageType;
  label: string;
  description: string;
  themeColorKey?: PaletteColorKey;
  icon?: ComponentType<LucideProps>;
  defaultVisible: boolean;
 }
 export const FEATURES: FeatureConfig[] = [
  {
    key: 'dashboard',
    label: '仪表盘',
    description: '',
    defaultVisible: true,
  },
  {
    key: 'timestamp',
    label: '时间戳',
    description: 'Unix 毫秒数转换与格式化',
    themeColorKey: 'primary',
    icon: Clock,
    defaultVisible: true,
  },
  {
    key: 'storageCleaner',
    label: '存储清理',
    description: '清理缓存、Cookies 及本地存储',
    themeColorKey: 'warning',
    icon: Database,
    defaultVisible: true,
  },
  {
    key: 'qrCode',
    label: '二维码工具',
    description: '生成当前选中的 URL 的二维码',
    themeColorKey: 'success',
    icon: QrCode,
    defaultVisible: true,
  },
  {
    key: 'textStatistics',
    label: '文本统计',
    description: '实时分析文本字符、单词及字节',
    themeColorKey: 'secondary',
    icon: FileText,
    defaultVisible: true,
  },
  {
    key: 'jwt',
    label: 'JWT 解析',
    description: 'JSON Web Token 解码与查看',
    themeColorKey: 'info',
    icon: Key,
    defaultVisible: true,
  },
  {
    key: 'jsonTools',
    label: 'JSON 工具',
    description: '差异比较、格式化、YAML/TOML 转换及压缩',
    themeColorKey: 'primary',
    icon: GitCompareArrows,
    defaultVisible: true,
  },
  {
    key: 'base64Converter',
    label: 'Base64 转换器',
    description: '文本、文件与图像的 Base64 编码转换',
    themeColorKey: 'info',
    icon: ArrowLeftRight,
    defaultVisible: true,
  },
  {
    key: 'rightClickRestorer',
    label: '右键恢复',
    description: '检测并恢复被网站禁用的浏览器右键菜单',
    themeColorKey: 'success',
    icon: MousePointerClick,
    defaultVisible: true,
  },
  {
    key: 'testDataGenerator',
    label: '测试数据生成器',
    description: '自定义规则批量生成测试数据',
    themeColorKey: 'warning',
    icon: FileSpreadsheet,
    defaultVisible: true,
  },
 ];
 export function getFeatureByKey(key: PageType): FeatureConfig | undefined {
  return FEATURES.find((f) => f.key === key);
 }
 export function getDefaultVisibleFeatureKeys(): PageType[] {
  return FEATURES.filter((f) => f.defaultVisible).map((f) => f.key);
 }
 export function getAllFeatureKeys(): PageType[] {
  return FEATURES.map((f) => f.key);
 }
 export function getDefaultPageOrder(): PageType[] {
  return FEATURES.filter((f) => f.key !== 'dashboard').map((f) => f.key);
 }
@@ -1,8 +0,0 @@
 export type { FeatureConfig, PaletteColorKey } from '@/config/featureMeta';
 export {
  FEATURES,
  getAllFeatureKeys,
  getDefaultPageOrder,
  getDefaultVisibleFeatureKeys,
  getFeatureByKey,
 } from '@/config/featureMeta';
@@ -0,0 +1,200 @@
 import { type ComponentType, lazy } from 'react';
 import type { LucideProps } from 'lucide-react';
 import type { PageType } from '@/types/storage';
 import {
  Clock,
  Database,
  QrCode,
  FileText,
  Key,
  GitCompareArrows,
  ArrowLeftRight,
  MousePointerClick,
  FileSpreadsheet,
 } from 'lucide-react';
 export type PaletteColorKey = 'primary' | 'success' | 'warning' | 'error' | 'secondary' | 'info';
 // 懒加载页面组件
 const DashboardPage = lazy(() => import('@/pages/Dashboard'));
 const TimestampPage = lazy(() => import('@/pages/Timestamp'));
 const StorageCleanerPage = lazy(() => import('@/pages/StorageCleaner'));
 const QrCodePage = lazy(() => import('@/pages/QrCode'));
 const TextStatisticsPage = lazy(() => import('@/pages/TextStatistics'));
 const JwtPage = lazy(() => import('@/pages/Jwt'));
 const JsonToolsPage = lazy(() => import('@/pages/JsonTools'));
 const Base64ConverterPage = lazy(() => import('@/pages/Base64Converter'));
 const RightClickRestorerPage = lazy(() => import('@/pages/RightClickRestorer'));
 const TestDataGeneratorPage = lazy(() => import('@/pages/TestDataGenerator'));
 export interface FeatureConfig {
  key: PageType;
  labelKey: string;
  descriptionKey: string;
  themeColorKey?: PaletteColorKey;
  icon?: ComponentType<LucideProps>;
  defaultVisible: boolean;
  components: {
    popup: ComponentType;
    sidepanel: ComponentType;
    tab: ComponentType;
  };
 }
 export const FEATURES: FeatureConfig[] = [
  {
    key: 'dashboard',
    labelKey: 'dashboard_title',
    descriptionKey: '',
    defaultVisible: true,
    components: {
      popup: DashboardPage,
      sidepanel: DashboardPage,
      tab: DashboardPage,
    },
  },
  {
    key: 'timestamp',
    labelKey: 'timestamp_title',
    descriptionKey: 'timestamp_description',
    themeColorKey: 'primary',
    icon: Clock,
    defaultVisible: true,
    components: {
      popup: TimestampPage,
      sidepanel: TimestampPage,
      tab: TimestampPage,
    },
  },
  {
    key: 'storageCleaner',
    labelKey: 'storageCleaner_title',
    descriptionKey: 'storageCleaner_description',
    themeColorKey: 'warning',
    icon: Database,
    defaultVisible: true,
    components: {
      popup: StorageCleanerPage,
      sidepanel: StorageCleanerPage,
      tab: StorageCleanerPage,
    },
  },
  {
    key: 'qrCode',
    labelKey: 'qrCode_title',
    descriptionKey: 'qrCode_description',
    themeColorKey: 'success',
    icon: QrCode,
    defaultVisible: true,
    components: {
      popup: QrCodePage,
      sidepanel: QrCodePage,
      tab: QrCodePage,
    },
  },
  {
    key: 'textStatistics',
    labelKey: 'textStatistics_title',
    descriptionKey: 'textStatistics_description',
    themeColorKey: 'secondary',
    icon: FileText,
    defaultVisible: true,
    components: {
      popup: TextStatisticsPage,
      sidepanel: TextStatisticsPage,
      tab: TextStatisticsPage,
    },
  },
  {
    key: 'jwt',
    labelKey: 'jwt_title',
    descriptionKey: 'jwt_description',
    themeColorKey: 'info',
    icon: Key,
    defaultVisible: true,
    components: {
      popup: JwtPage,
      sidepanel: JwtPage,
      tab: JwtPage,
    },
  },
  {
    key: 'jsonDiff',
    labelKey: 'jsonDiff_title',
    descriptionKey: 'jsonDiff_description',
    themeColorKey: 'primary',
    icon: GitCompareArrows,
    defaultVisible: true,
    components: {
      popup: JsonToolsPage,
      sidepanel: JsonToolsPage,
      tab: JsonToolsPage,
    },
  },
  {
    key: 'base64Converter',
    labelKey: 'base64Converter_title',
    descriptionKey: 'base64Converter_description',
    themeColorKey: 'info',
    icon: ArrowLeftRight,
    defaultVisible: true,
    components: {
      popup: Base64ConverterPage,
      sidepanel: Base64ConverterPage,
      tab: Base64ConverterPage,
    },
  },
  {
    key: 'rightClickRestorer',
    labelKey: 'rightClickRestorer_title',
    descriptionKey: 'rightClickRestorer_description',
    themeColorKey: 'success',
    icon: MousePointerClick,
    defaultVisible: true,
    components: {
      popup: RightClickRestorerPage,
      sidepanel: RightClickRestorerPage,
      tab: RightClickRestorerPage,
    },
  },
  {
    key: 'testDataGenerator',
    labelKey: 'testDataGenerator_title',
    descriptionKey: 'testDataGenerator_description',
    themeColorKey: 'warning',
    icon: FileSpreadsheet,
    defaultVisible: true,
    components: {
      popup: TestDataGeneratorPage,
      sidepanel: TestDataGeneratorPage,
      tab: TestDataGeneratorPage,
    },
  },
 ];
 export function getFeatureByKey(key: PageType): FeatureConfig | undefined {
  return FEATURES.find((f) => f.key === key);
 }
 export function getDefaultVisibleFeatureKeys(): PageType[] {
  return FEATURES.filter((f) => f.defaultVisible).map((f) => f.key);
 }
 export function getAllFeatureKeys(): PageType[] {
  return FEATURES.map((f) => f.key);
 }
 export function getDefaultPageOrder(): PageType[] {
  return FEATURES.filter((f) => f.key !== 'dashboard').map((f) => f.key);
 }
 export function getEntryPointType(): 'popup' | 'sidepanel' | 'tab' {
  const pathname = window.location.pathname;
  if (pathname.includes('sidepanel')) {
    return 'sidepanel';
  }
  if (new URLSearchParams(window.location.search).get('mode') === 'tab') {
    return 'tab';
  }
  return 'popup';
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadBase64Converter(): Promise<{ default: ComponentType }> {
  return import('@/pages/Base64Converter');
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadDashboard(): Promise<{ default: ComponentType }> {
  return import('@/pages/Dashboard');
 }
@@ -1,45 +0,0 @@
 import type { ComponentType } from 'react';
 import type { PageType } from '@/types/storage';
 type PageModule = { default: ComponentType };
 let pagesStylesLoaded = false;
 function ensurePagesStyles(): Promise<unknown> {
  if (pagesStylesLoaded) {
    return Promise.resolve();
  }
  pagesStylesLoaded = true;
  return import('@/styles/pages.css');
 }
 export function loadPage(key: PageType): Promise<PageModule> {
  return ensurePagesStyles().then(() => {
    switch (key) {
      case 'dashboard':
        return import('@/config/pageLoaders/dashboard').then((m) => m.default());
      case 'timestamp':
        return import('@/config/pageLoaders/timestamp').then((m) => m.default());
      case 'storageCleaner':
        return import('@/config/pageLoaders/storageCleaner').then((m) => m.default());
      case 'qrCode':
        return import('@/config/pageLoaders/qrCode').then((m) => m.default());
      case 'textStatistics':
        return import('@/config/pageLoaders/textStatistics').then((m) => m.default());
      case 'jwt':
        return import('@/config/pageLoaders/jwt').then((m) => m.default());
      case 'jsonTools':
        return import('@/config/pageLoaders/jsonTools').then((m) => m.default());
      case 'base64Converter':
        return import('@/config/pageLoaders/base64Converter').then((m) => m.default());
      case 'rightClickRestorer':
        return import('@/config/pageLoaders/rightClickRestorer').then((m) => m.default());
      case 'testDataGenerator':
        return import('@/config/pageLoaders/testDataGenerator').then((m) => m.default());
      default: {
        const _exhaustive: never = key;
        return Promise.reject(new Error(`Unknown page: ${String(_exhaustive)}`));
      }
    }
  });
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadJsonTools(): Promise<{ default: ComponentType }> {
  return import('@/pages/JsonTools');
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadJwt(): Promise<{ default: ComponentType }> {
  return import('@/pages/Jwt');
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadQrCode(): Promise<{ default: ComponentType }> {
  return import('@/pages/QrCode');
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadRightClickRestorer(): Promise<{ default: ComponentType }> {
  return import('@/pages/RightClickRestorer');
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadStorageCleaner(): Promise<{ default: ComponentType }> {
  return import('@/pages/StorageCleaner');
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadTestDataGenerator(): Promise<{ default: ComponentType }> {
  return import('@/pages/TestDataGenerator');
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadTextStatistics(): Promise<{ default: ComponentType }> {
  return import('@/pages/TextStatistics');
 }
@@ -1,5 +0,0 @@
 import type { ComponentType } from 'react';
 export default function loadTimestamp(): Promise<{ default: ComponentType }> {
  return import('@/pages/Timestamp');
 }
@@ -0,0 +1,51 @@
 # entrypoints/
 WXT 框架要求的扩展生命周期入口点，对应 Chrome Extension 的各个上下文。
 ## 入口文件
 | 文件                            | 用途                                                                                          |
 | ------------------------------- | --------------------------------------------------------------------------------------------- |
 | `background.ts`                 | Service Worker 入口：注册右键菜单、监听菜单点击、处理消息通信、管理侧边栏状态、注入主环境脚本 |
 | `content.ts`                    | Content Script 入口：注入所有页面（`<all_urls>`），在 `document_end` 时初始化消息处理器       |
 | `rightClickRestorer.content.ts` | 专用 Content Script：处理右键菜单恢复功能，注入浮动状态徽章                                   |
 ## 子目录
 ### popup/
 Popup 弹窗页面（点击扩展图标弹出）。
 | 文件         | 用途                                                                           |
 | ------------ | ------------------------------------------------------------------------------ |
 | `index.html` | HTML 入口                                                                      |
 | `main.tsx`   | React 挂载点                                                                   |
 | `App.tsx`    | 根组件，组装 `RouterProvider` + `TopBar` + `ErrorBoundary` + `RouterContainer` |
 ### sidepanel/
 侧边栏页面，结构与 popup 类似，额外通知 background 侧边栏开启/关闭状态。
 ### options/
 设置页面，支持：
 - 拖拽排序功能顺序（`@dnd-kit`）
 - 功能可见性管理（显示/隐藏）
 - Popup/Sidepanel/Tab 三种模式独立配置
 ### content/
 Content Script 内部分模块：
 | 文件                    | 用途                                                                |
 | ----------------------- | ------------------------------------------------------------------- |
 | `messageHandler.ts`     | 消息处理器初始化入口                                                |
 | `contextMenuHandler.ts` | 右键菜单点击事件处理，执行时间戳转换/文本统计并通过 UI Popover 展示 |
 | `uiPopover.ts`          | 在页面中注入浮层 Popover UI，展示右键菜单操作结果                   |
 ## 架构说明
 - `background.ts` 是扩展的核心协调者，处理跨上下文通信
 - `content.ts` 注入到所有页面，负责接收和处理来自 background 的消息
 - `popup/`、`sidepanel/`、`options/` 共享同一套页面组件（来自 `pages/`），通过 `RouterProvider` 的不同配置实现独立路由
@@ -36,7 +36,7 @@ describe('background 菜单注册与分流', () => {
      expect(chrome.contextMenus.create).toHaveBeenCalledWith(
        expect.objectContaining({
          id: 'jwt',
-          title: '解析 JWT',
+          title: '🔑 解析 JWT',
          parentId: 'testing-tools-parent',
        }),
      );
@@ -48,7 +48,7 @@ describe('background 菜单注册与分流', () => {
      expect(chrome.contextMenus.create).toHaveBeenCalledWith(
        expect.objectContaining({
          id: 'qrCode-page',
-          title: '网页链接转二维码',
+          title: '🔗 网页链接转二维码',
          contexts: ['page'],
        }),
      );
@@ -1,6 +1,6 @@
 import '../../.wxt/types/imports.d.ts';
 import { browser } from 'wxt/browser';
-import { MessageAction, onMessage } from '@/utils/messages';
+import { MessageAction, onMessage, sendMessage } from '@/utils/messages';
 import { createAllContextMenus, parseContextMenuClick } from '@/utils/contextMenu';
 import { saveContextMenuData } from '@/utils/useContextMenuData';
 import { mainWorldInjectionScript } from '@/utils/rightClickInjection';
@@ -24,12 +24,38 @@ export default defineBackground(() => {
    const { featureKey, payload } = result.data;
    try {
      const sidePanelState = await browser.storage.local.get('sidePanelOpen');
      const isSidePanelOpen = sidePanelState.sidePanelOpen === true;
      if (isSidePanelOpen) {
        await sendMessage(MessageAction.CONTEXT_MENU_CLICKED, { featureKey, payload });
        return;
      }
    } catch (err) {
      console.debug('[Context Menu] Side panel pipeline is not available:', err);
    }
    await saveContextMenuData({ featureKey, payload });
    try {
      await browser.action.openPopup();
    } catch (err) {
-      console.warn('[Context Menu] 自动打开 popup 失败，请手动点击扩展图标，数据已暂存:', err);
+      console.warn(
        '[Context Menu] 自动打开 popup 失败，请手动点击扩展图标，暂存数据已安全保留:',
        err,
      );
    }
  });
  // 监听扩展图标点击事件，安全激活侧边栏
  browser.action.onClicked.addListener(async (tab) => {
    if (tab.id) {
      try {
        await browser.sidePanel.open({ tabId: tab.id });
      } catch (err) {
        console.error('Failed to open side panel via extension action clicked:', err);
      }
    }
  });
@@ -39,8 +65,8 @@ export default defineBackground(() => {
    const tabId = sender?.tab?.id;
    if (!tabId) {
-      console.warn('[RightClickRestorer] 注入请求缺少 tabId');
+      console.warn('[RightClickRestorer] Injection request missing tabId');
-      return { success: false, message: '缺少 tabId' };
+      return { success: false, message: 'Missing tabId' };
    }
    try {
@@ -53,7 +79,7 @@ export default defineBackground(() => {
      return { success: true };
    } catch (err) {
      const errorMsg = err instanceof Error ? err.message : String(err);
-      console.error('[RightClickRestorer] 执行脚本失败:', errorMsg);
+      console.error('[RightClickRestorer] executeScript failed:', errorMsg);
      return { success: false, message: errorMsg };
    }
  });
@@ -1,20 +1,22 @@
 import type { ContextMenuClickedPayload } from '@/utils/messages';
 import { MessageAction, onMessage } from '@/utils/messages';
 import { getTextStats } from '@/utils/textStatistics';
 import { getMessage } from '@/utils/chromeI18n';
 import { hidePopover, showTextStatsResult, showTimestampResult } from './uiPopover';
 function convertTimestamp(input: string): string {
  const invalidText = getMessage('invalidTimestamp') || 'Invalid Timestamp';
  const num = Number(input.trim());
  if (isNaN(num)) {
-    return '无效时间戳';
+    return invalidText;
  }
-  // 1e12 区分毫秒/秒级时间戳
+  // 1e12 判定毫秒级/秒级时间戳兼容
  const d = num > 1e12 ? new Date(num) : new Date(num * 1000);
  if (isNaN(d.getTime())) {
-    return '无效时间戳';
+    return invalidText;
  }
  const year = d.getFullYear();
@@ -137,11 +137,12 @@ function escapeHtml(text: string): string {
 }
 function positionPopover(popover: HTMLElement, x: number, y: number): void {
  // 此时借助 visibility: hidden，元素在隐藏状态下拥有真实的布局高宽
  const rect = popover.getBoundingClientRect();
  const viewportWidth = window.innerWidth;
  const viewportHeight = window.innerHeight;
-  let left = x + 8;
+  let left = x + 8; // 微微追加水平偏置，防范直接遮挡用户的鼠标落点
  let top = y + 8;
  if (left + rect.width > viewportWidth - 16) {
@@ -177,7 +178,7 @@ function showPopover(
    const titleSpan = document.createElement('span');
    titleSpan.className = 'popover-title';
-    titleSpan.textContent = title;
+    titleSpan.textContent = title; // ✅ 强安全性护航
    const closeBtn = document.createElement('button');
    closeBtn.className = 'popover-close';
@@ -193,9 +194,10 @@ function showPopover(
  const contentContainer = document.createElement('div');
  contentContainer.className = 'popover-content';
-  contentContainer.innerHTML = contentHtml;
+  contentContainer.innerHTML = contentHtml; // 内部拼装的方法已提前完成全消毒转义
  popover.appendChild(contentContainer);
  // 提前移除激活类名，使 visibility: hidden 起效以供测量
  popover.classList.remove('visible');
  requestAnimationFrame(() => {
@@ -224,6 +226,7 @@ export function hidePopover(): void {
 }
 export function showTimestampResult(x: number, y: number, timestamp: string, result: string): void {
  // 对外部传来的参数先全数塞入 escapeHtml 大闸进行纯氧化清洗
  const cleanTimestamp = escapeHtml(timestamp);
  const cleanResult = escapeHtml(result);
@@ -233,7 +236,7 @@ export function showTimestampResult(x: number, y: number, timestamp: string, res
    <div class="popover-label">转换结果</div>
    <div class="popover-value">${cleanResult}</div>
  `;
-  showPopover(x, y, content, '转换结果');
+  showPopover(x, y, content, '⏰ 时间戳转换');
 }
 export function showTextStatsResult(
@@ -243,6 +246,7 @@ export function showTextStatsResult(
  stats: { characters: number; words: number; lines: number; bytes: number },
 ): void {
  const truncatedText = text.length > 50 ? text.substring(0, 50) + '...' : text;
  // 对选中的脏文本先进行严格转义
  const cleanText = escapeHtml(truncatedText);
  const content = `
@@ -267,5 +271,5 @@ export function showTextStatsResult(
      </div>
    </div>
  `;
-  showPopover(x, y, content, '统计结果');
+  showPopover(x, y, content, '📊 文本统计');
 }
@@ -1,16 +1,31 @@
 import RouterProvider from '@/providers/RouterProvider';
-import TopBar from '@/layout/TopBar';
+import TopBar from '@/components/TopBar';
 import RouterContainer from '@/components/RouterContainer';
 import ErrorBoundary from '@/components/ErrorBoundary';
-
+import { getEntryPointType } from '@/config/features';
 export default function App() {
  const entryType = getEntryPointType();
  const routerConfig =
    entryType === 'tab'
      ? {
          syncKey: 'app/tabRoute' as const,
          visiblePagesKey: 'app/tabVisiblePages' as const,
          pageOrderKey: 'app/tabPageOrder' as const,
        }
      : {
          syncKey: 'app/popupRoute' as const,
          visiblePagesKey: 'app/popupVisiblePages' as const,
          pageOrderKey: 'app/popupPageOrder' as const,
        };
  return (
    <RouterProvider
-      syncKey="app/popupRoute"
+      syncKey={routerConfig.syncKey}
-      visiblePagesKey="app/popupVisiblePages"
+      visiblePagesKey={routerConfig.visiblePagesKey}
-      pageOrderKey="app/popupPageOrder"
+      pageOrderKey={routerConfig.pageOrderKey}
    >
-      <div className="flex flex-col w-[400px] max-w-[400px] min-w-[400px] h-[600px] min-h-[600px] overflow-hidden bg-background">
+      <div className="app flex flex-col w-[400px] max-w-[400px] min-w-[400px] h-[600px] min-h-[600px] overflow-hidden bg-background sm:w-screen sm:max-w-none sm:min-w-0 sm:h-screen sm:min-h-0">
        <TopBar />
        <ErrorBoundary>
          <RouterContainer />
@@ -3,21 +3,8 @@
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Testing Tools</title>
+    <title>Testing Tools - 标签页</title>
    <meta name="manifest.type" content="browser_action" />
    <script>
      (function () {
        try {
          var raw = localStorage.getItem('snapshot/app/themeMode');
          var mode = raw ? JSON.parse(raw) : 'system';
          if (mode !== 'light' && mode !== 'dark' && mode !== 'system') mode = 'system';
          var isDark =
            mode === 'dark' ||
            (mode === 'system' && window.matchMedia('(prefers-color-scheme: dark)').matches);
          if (isDark) document.documentElement.classList.add('dark');
        } catch (_error) {}
      })();
    </script>
    <style>
      /* Force initial popup size before React hydration */
      html, body {
@@ -33,6 +20,13 @@
        width: 100%;
        height: 100%;
      }
      /* If opened in a tab (mode=tab), reset the fixed size */
      @media screen and (min-width: 600px) {
        html, body {
          width: 100%;
          height: 100%;
        }
      }
    </style>
  </head>
  <body>
@@ -1,6 +1,6 @@
 import ReactDOM from 'react-dom/client';
 import AppRoot from '@/providers/AppRoot';
-import '@/styles/shell.css';
+import '@/index.css';
 import App from './App.tsx';
 ReactDOM.createRoot(document.getElementById('root')!).render(
@@ -0,0 +1,26 @@
 import { useEffect } from 'react';
 import RouterProvider from '@/providers/RouterProvider';
 import TopBar from '@/components/TopBar';
 import RouterContainer from '@/components/RouterContainer';
 import ErrorBoundary from '@/components/ErrorBoundary';
 import { MessageAction, sendMessage } from '@/utils/messages';
 export default function App() {
  useEffect(() => {
    sendMessage(MessageAction.SIDE_PANEL_STATE_CHANGED, { isOpen: true });
    return () => {
      sendMessage(MessageAction.SIDE_PANEL_STATE_CHANGED, { isOpen: false });
    };
  }, []);
  return (
    <RouterProvider defaultRoute="dashboard" syncKey="app/sidepanelRoute">
      <div className="app flex flex-col h-screen w-full overflow-hidden">
        <TopBar />
        <ErrorBoundary>
          <RouterContainer />
        </ErrorBoundary>
      </div>
    </RouterProvider>
  );
 }
@@ -0,0 +1,12 @@
 <!doctype html>
 <html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Testing Tools - Side Panel</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="./main.tsx"></script>
  </body>
 </html>
@@ -0,0 +1,10 @@
 import ReactDOM from 'react-dom/client';
 import AppRoot from '@/providers/AppRoot';
 import '@/index.css';
 import App from './App.tsx';
 ReactDOM.createRoot(document.getElementById('root')!).render(
  <AppRoot>
    <App />
  </AppRoot>,
 );
@@ -1,5 +1,3 @@
@config "../../tailwind.shell.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;
@@ -92,91 +90,3 @@
 ::-webkit-scrollbar {
  display: none;
 }
@layer components {
  .page-transition-dashboard {
    @apply motion-reduce:transition-none;
  }
  .page-transition-enter {
    @apply motion-reduce:transition-none;
    animation: tt-page-enter 200ms ease-out;
  }
 }
@layer utilities {
  .fade-in-150 {
    animation: tt-fade-in 150ms ease-out forwards;
  }
  .fade-in-200 {
    animation: tt-fade-in 200ms ease-out forwards;
  }
  .fade-in-300 {
    animation: tt-fade-in 300ms ease-out forwards;
  }
  .fade-in-zoom-95 {
    animation: tt-fade-in-zoom-95 150ms ease-out forwards;
  }
  .fade-in-slide-top-1 {
    animation: tt-fade-in-slide-top-1 150ms ease-out forwards;
  }
  .fade-in-slide-top-2 {
    animation: tt-fade-in-slide-top-2 150ms ease-out forwards;
  }
 }
@keyframes tt-fade-in {
  from {
    opacity: 0;
  }
  to {
    opacity: 1;
  }
 }
@keyframes tt-fade-in-zoom-95 {
  from {
    opacity: 0;
    transform: scale(0.95);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
 }
@keyframes tt-fade-in-slide-top-1 {
  from {
    opacity: 0;
    transform: translateY(-0.25rem);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
 }
@keyframes tt-fade-in-slide-top-2 {
  from {
    opacity: 0;
    transform: translateY(-0.5rem);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
 }
@keyframes tt-page-enter {
  from {
    opacity: 0.92;
  }
  to {
    opacity: 1;
  }
 }
@@ -1,26 +0,0 @@
 # layout/
 应用壳层布局组件目录，存放与扩展入口（popup / sidepanel / tab）绑定的布局 UI，与 `components/` 中的通用可复用组件区分。
 ## 组件列表
 | 目录      | 用途                                                           |
 | --------- | -------------------------------------------------------------- |
 | `TopBar/` | 顶部导航栏：搜索（含历史记录）、主题切换、返回导航、标签页打开 |
 ## 目录结构
 遵循与 `pages/` 相同的 UI + Hook 分离模式：
 ```
 layout/TopBar/
 ├── index.tsx              # 布局入口
 ├── useTopBar.ts           # 业务逻辑 Hook
 ├── constants.ts           # 常量
 ├── SearchInput.tsx        # 搜索输入框
 ├── SearchDropdown.tsx     # 搜索结果/历史下拉面板
 ├── SearchResultItem.tsx   # 单条搜索结果项
 ├── TopBarActions.tsx      # 右侧操作按钮组
 └── __tests__/
    └── index.test.tsx
 ```
@@ -1,45 +0,0 @@
 import { type FeatureConfig } from '@/config/features';
 import SearchResultItem from './SearchResultItem';
 interface SearchDropdownProps {
  searchQuery: string;
  searchResults: FeatureConfig[];
  recentFeatures: FeatureConfig[];
  selectedIndex: number;
  onSelect: (feature: FeatureConfig) => void;
 }
 export default function SearchDropdown({
  searchQuery,
  searchResults,
  recentFeatures,
  selectedIndex,
  onSelect,
 }: SearchDropdownProps) {
  const isSearching = !!searchQuery.trim();
  const items = isSearching ? searchResults : recentFeatures;
  return (
    <div className="absolute left-0 right-0 top-full z-50 mt-1.5 max-h-80 overflow-y-auto rounded-lg border border-border bg-popover text-popover-foreground shadow-lg fade-in-slide-top-2">
      <ul role="listbox" className="p-1.5">
        {!isSearching && items.length > 0 && (
          <li className="px-3 py-1.5 text-[11px] font-semibold uppercase tracking-wider text-muted-foreground/60">
            最近搜索
          </li>
        )}
        {isSearching && items.length === 0 ? (
          <li className="px-4 py-6 text-center text-sm text-muted-foreground">未找到相关工具</li>
        ) : (
          items.map((feature, index) => (
            <SearchResultItem
              key={feature.key}
              feature={feature}
              selected={selectedIndex === index}
              onSelect={onSelect}
            />
          ))
        )}
      </ul>
    </div>
  );
 }
@@ -1,55 +0,0 @@
 import { type KeyboardEvent, type RefObject } from 'react';
 import { Search, X } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { getSearchShortcutLabel } from './constants';
 interface SearchInputProps {
  inputRef: RefObject<HTMLInputElement | null>;
  searchQuery: string;
  onSearchQueryChange: (value: string) => void;
  onFocus: () => void;
  onKeyDown: (e: KeyboardEvent) => void;
  onClear: () => void;
 }
 export default function SearchInput({
  inputRef,
  searchQuery,
  onSearchQueryChange,
  onFocus,
  onKeyDown,
  onClear,
 }: SearchInputProps) {
  return (
    <div className="group relative">
      <Search className="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground/60 transition-colors group-focus-within:text-muted-foreground" />
      <Input
        ref={inputRef}
        placeholder="搜索工具..."
        value={searchQuery}
        onChange={(e) => onSearchQueryChange(e.target.value)}
        onFocus={onFocus}
        onKeyDown={onKeyDown}
        aria-label="搜索工具..."
        className="h-9 rounded-lg border-border/60 bg-muted/40 pl-9 pr-16 shadow-none focus-visible:ring-1 focus-visible:ring-offset-0 placeholder:text-muted-foreground/50"
      />
      {searchQuery ? (
        <Button
          type="button"
          variant="ghost"
          size="icon"
          onClick={onClear}
          aria-label="清除搜索"
          className="absolute right-1 top-1/2 h-7 w-7 -translate-y-1/2 text-muted-foreground hover:text-foreground"
        >
          <X className="h-3 w-3" />
        </Button>
      ) : (
        <kbd className="pointer-events-none absolute right-3 top-1/2 hidden h-5 -translate-y-1/2 items-center rounded border border-border/60 bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground/60 sm:inline-flex">
          {getSearchShortcutLabel()}
        </kbd>
      )}
    </div>
  );
 }
@@ -1,30 +0,0 @@
 import { type FeatureConfig } from '@/config/features';
 import { cn } from '@/lib/utils';
 interface SearchResultItemProps {
  feature: FeatureConfig;
  selected: boolean;
  onSelect: (feature: FeatureConfig) => void;
 }
 export default function SearchResultItem({ feature, selected, onSelect }: SearchResultItemProps) {
  return (
    <li
      role="option"
      aria-selected={selected}
      onClick={() => onSelect(feature)}
      className={cn(
        'flex cursor-pointer items-center gap-3 rounded-md px-3 py-2.5 text-sm transition-colors',
        selected ? 'bg-accent text-accent-foreground' : 'hover:bg-muted/60',
      )}
    >
      <div className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-muted/80 text-muted-foreground">
        {feature.icon && <feature.icon className="h-4 w-4" />}
      </div>
      <div className="min-w-0 flex-1">
        <p className="truncate font-medium text-foreground">{feature.label}</p>
        <p className="mt-0.5 truncate text-xs text-muted-foreground">{feature.description}</p>
      </div>
    </li>
  );
 }
@@ -1,34 +0,0 @@
 import { type LucideIcon } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 interface TopBarAction {
  id: string;
  icon: LucideIcon;
  title: string;
  onClick: () => void;
 }
 interface TopBarActionsProps {
  actions: TopBarAction[];
 }
 export default function TopBarActions({ actions }: TopBarActionsProps) {
  return (
    <div className="flex shrink-0 items-center gap-1">
      {actions.map(({ id, icon: Icon, title, onClick }) => (
        <Button
          key={id}
          type="button"
          variant="ghost"
          size="icon"
          onClick={onClick}
          title={title}
          aria-label={title}
          className="h-8 w-8 text-muted-foreground"
        >
          <Icon className="h-4 w-4" />
        </Button>
      ))}
    </div>
  );
 }
@@ -1,37 +0,0 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { getSearchShortcutLabel } from '@/layout/TopBar/constants';
 describe('getSearchShortcutLabel', () => {
  const originalUserAgent = navigator.userAgent;
  afterEach(() => {
    vi.stubGlobal('navigator', { ...navigator, userAgent: originalUserAgent });
  });
  it('macOS 应显示 ⌘K', () => {
    vi.stubGlobal('navigator', {
      ...navigator,
      userAgent:
        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
    });
    expect(getSearchShortcutLabel()).toBe('⌘K');
  });
  it('Windows 应显示 Ctrl+K', () => {
    vi.stubGlobal('navigator', {
      ...navigator,
      userAgent:
        'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
    });
    expect(getSearchShortcutLabel()).toBe('Ctrl+K');
  });
  it('Linux 应显示 Ctrl+K', () => {
    vi.stubGlobal('navigator', {
      ...navigator,
      userAgent:
        'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
    });
    expect(getSearchShortcutLabel()).toBe('Ctrl+K');
  });
 });
@@ -1,9 +0,0 @@
 export const SEARCH_HISTORY_LIMIT = 10;
 export const SEARCH_HISTORY_DISPLAY = 5;
 export const isSearchHistory = (val: unknown): val is string[] =>
  Array.isArray(val) && val.every((item) => typeof item === 'string');
 export function getSearchShortcutLabel(): string {
  return /Mac|iPhone|iPad|iPod/i.test(navigator.userAgent) ? '⌘K' : 'Ctrl+K';
 }
@@ -1,71 +0,0 @@
 import { ArrowLeft } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import SearchDropdown from './SearchDropdown';
 import SearchInput from './SearchInput';
 import TopBarActions from './TopBarActions';
 import { useTopBar } from './useTopBar';
 export default function TopBar() {
  const {
    searchQuery,
    searchResults,
    recentFeatures,
    selectedIndex,
    isDashboard,
    ThemeIcon,
    themeTitle,
    showDropdown,
    containerRef,
    inputRef,
    handleSearchQueryChange,
    handleSearchFocus,
    handleSelectFeature,
    handleKeyDown,
    cycleThemeMode,
    goHome,
    clearSearch,
  } = useTopBar();
  const actions = [{ id: 'theme', icon: ThemeIcon, title: themeTitle, onClick: cycleThemeMode }];
  return (
    <header className="relative z-50 flex h-14 items-center justify-between border-b border-border bg-background px-4">
      <div className="flex w-10 items-center justify-start">
        {!isDashboard && (
          <Button
            type="button"
            variant="outline"
            size="icon"
            onClick={goHome}
            aria-label="返回首页"
            className="h-8 w-8 shadow-sm text-muted-foreground"
          >
            <ArrowLeft className="h-4 w-4" />
          </Button>
        )}
      </div>
      <div ref={containerRef} className="relative mx-4 max-w-md flex-1">
        <SearchInput
          inputRef={inputRef}
          searchQuery={searchQuery}
          onSearchQueryChange={handleSearchQueryChange}
          onFocus={handleSearchFocus}
          onKeyDown={handleKeyDown}
          onClear={clearSearch}
        />
        {showDropdown && (
          <SearchDropdown
            searchQuery={searchQuery}
            searchResults={searchResults}
            recentFeatures={recentFeatures}
            selectedIndex={selectedIndex}
            onSelect={handleSelectFeature}
          />
        )}
      </div>
      <TopBarActions actions={actions} />
    </header>
  );
 }
@@ -1,174 +0,0 @@
 import {
  useEffect,
  useMemo,
  useRef,
  useState,
  type KeyboardEvent as ReactKeyboardEvent,
  type RefObject,
 } from 'react';
 import { Monitor, Moon, Sun } from 'lucide-react';
 import { useRouter } from '@/providers/RouterProvider';
 import { useThemeMode } from '@/providers/ThemeModeProvider';
 import { type FeatureConfig, FEATURES } from '@/config/features';
 import { useStorageState } from '@/utils/useStorageState';
 import { isSearchHistory, SEARCH_HISTORY_DISPLAY, SEARCH_HISTORY_LIMIT } from './constants';
 export interface UseTopBarReturn {
  searchQuery: string;
  searchResults: FeatureConfig[];
  recentFeatures: FeatureConfig[];
  selectedIndex: number;
  isDashboard: boolean;
  ThemeIcon: typeof Sun;
  themeTitle: string;
  showDropdown: boolean;
  containerRef: RefObject<HTMLDivElement | null>;
  inputRef: RefObject<HTMLInputElement | null>;
  handleSearchQueryChange: (value: string) => void;
  handleSearchFocus: () => void;
  handleSelectFeature: (feature: FeatureConfig) => void;
  handleKeyDown: (e: ReactKeyboardEvent) => void;
  cycleThemeMode: () => void;
  goHome: () => void;
  clearSearch: () => void;
 }
 export function useTopBar(): UseTopBarReturn {
  const { currentPage, goHome, navigateTo } = useRouter();
  const { mode, setMode } = useThemeMode();
  const [searchQuery, setSearchQuery] = useState('');
  const [showResults, setShowResults] = useState(false);
  const [searchHistory, setSearchHistory] = useStorageState(
    'app/searchHistory',
    [],
    isSearchHistory,
  );
  const [selectedIndex, setSelectedIndex] = useState(-1);
  const containerRef = useRef<HTMLDivElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);
  useEffect(() => {
    const handleClickOutside = (event: MouseEvent) => {
      if (containerRef.current && !containerRef.current.contains(event.target as Node)) {
        setShowResults(false);
      }
    };
    document.addEventListener('mousedown', handleClickOutside);
    return () => document.removeEventListener('mousedown', handleClickOutside);
  }, []);
  useEffect(() => {
    const handleGlobalKeyDown = (e: KeyboardEvent) => {
      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
        e.preventDefault();
        inputRef.current?.focus();
        setShowResults(true);
      }
    };
    document.addEventListener('keydown', handleGlobalKeyDown);
    return () => document.removeEventListener('keydown', handleGlobalKeyDown);
  }, []);
  const searchResults = useMemo(() => {
    const query = searchQuery.trim().toLowerCase();
    if (!query) return [];
    return FEATURES.filter((f) => {
      if (f.key === 'dashboard') return false;
      return f.label.toLowerCase().includes(query) || f.description.toLowerCase().includes(query);
    });
  }, [searchQuery]);
  const recentFeatures = useMemo(() => {
    if (searchQuery.trim()) return [];
    return searchHistory
      .slice(0, SEARCH_HISTORY_DISPLAY)
      .map((key) => FEATURES.find((f) => f.key === key))
      .filter((feature): feature is FeatureConfig => !!feature && feature.key !== 'dashboard');
  }, [searchHistory, searchQuery]);
  const saveToHistory = (featureKey: string) => {
    setSearchHistory((prev) =>
      [featureKey, ...prev.filter((h) => h !== featureKey)].slice(0, SEARCH_HISTORY_LIMIT),
    );
  };
  const handleSelectFeature = (feature: FeatureConfig) => {
    navigateTo(feature.key);
    saveToHistory(feature.key);
    setSearchQuery('');
    setShowResults(false);
  };
  const cycleThemeMode = () => {
    const nextMap = { light: 'dark', dark: 'system', system: 'light' } as const;
    setMode(nextMap[mode]);
  };
  const ThemeIcon = mode === 'light' ? Sun : mode === 'dark' ? Moon : Monitor;
  const themeTitle =
    mode === 'light' ? '切换到深色模式' : mode === 'dark' ? '切换到系统模式' : '切换到浅色模式';
  const handleKeyDown = (e: ReactKeyboardEvent) => {
    const isSearching = !!searchQuery.trim();
    const items = isSearching ? searchResults : recentFeatures;
    const totalItems = items.length;
    if (e.key === 'ArrowDown') {
      e.preventDefault();
      setSelectedIndex((prev) => (prev < totalItems - 1 ? prev + 1 : prev));
    } else if (e.key === 'ArrowUp') {
      e.preventDefault();
      setSelectedIndex((prev) => (prev > 0 ? prev - 1 : prev));
    } else if (e.key === 'Enter') {
      e.preventDefault();
      let feature: FeatureConfig | undefined;
      if (selectedIndex >= 0 && selectedIndex < totalItems) {
        feature = items[selectedIndex];
      } else if (isSearching && searchResults.length > 0) {
        feature = searchResults[0];
      }
      if (feature) handleSelectFeature(feature);
    } else if (e.key === 'Escape') {
      setShowResults(false);
      inputRef.current?.blur();
    }
  };
  const clearSearch = () => {
    setSearchQuery('');
    setSelectedIndex(-1);
  };
  const handleSearchQueryChange = (value: string) => {
    setSearchQuery(value);
    setShowResults(true);
    setSelectedIndex(-1);
  };
  const handleSearchFocus = () => setShowResults(true);
  const showDropdown = showResults && (!!searchQuery.trim() || recentFeatures.length > 0);
  return {
    searchQuery,
    searchResults,
    recentFeatures,
    selectedIndex,
    showDropdown,
    isDashboard: currentPage === 'dashboard',
    ThemeIcon,
    themeTitle,
    containerRef,
    inputRef,
    handleSearchQueryChange,
    handleSearchFocus,
    handleSelectFeature,
    handleKeyDown,
    cycleThemeMode,
    goHome,
    clearSearch,
  };
 }
@@ -37,6 +37,7 @@ import { cn } from '@/lib/utils';
 | `business.ts`  | 业务数据生成器（订单号、价格、日期、状态等）   |
 | `technical.ts` | 技术数据生成器（UUID、IPv4、URL）              |
 | `basic.ts`     | 基础类型生成器（整数、浮点数、布尔值、字符串） |
 | `types.ts`     | 生成器库内部类型与通用选项                     |
 使用示例：
@@ -1,22 +0,0 @@
 import { randomInt, randomPick } from '@/lib/generators/random';
 describe('generators/random', () => {
  it('randomInt 应返回闭区间内的整数', () => {
    vi.spyOn(Math, 'random').mockReturnValue(0.5);
    expect(randomInt(1, 10)).toBe(6);
    expect(randomInt(5, 5)).toBe(5);
  });
  it('randomPick 应对单元素数组返回该元素', () => {
    vi.spyOn(Math, 'random').mockReturnValue(0);
    expect(randomPick(['only'])).toBe('only');
  });
  it('randomPick 应返回数组中的元素', () => {
    vi.spyOn(Math, 'random').mockReturnValue(0.99);
    expect(randomPick(['a', 'b', 'c'])).toBe('c');
  });
 });
@@ -1,6 +1,27 @@
-import type { GeneratorDefinition } from '@/types/testDataGenerator';
+/**
-import { randomInt, randomPick } from './random';
+ * 基础类型生成器
 * 包含：随机整数、随机浮点数、随机字符串、从列表选择
 */
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
 /**
 * 生成随机整数
 */
 function randomInt(min: number, max: number): number {
  return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 /**
 * 从数组中随机选择
 */
 function randomPick<T>(arr: T[]): T {
  return arr[Math.floor(Math.random() * arr.length)];
 }
 /**
 * 随机整数生成器
 */
 export const randomIntGenerator: GeneratorDefinition = {
  id: 'randomInt',
  name: '随机整数',
@@ -35,6 +56,9 @@ export const randomIntGenerator: GeneratorDefinition = {
  },
 };
 /**
 * 随机浮点数生成器
 */
 export const randomFloat: GeneratorDefinition = {
  id: 'randomFloat',
  name: '随机浮点数',
@@ -74,6 +98,9 @@ export const randomFloat: GeneratorDefinition = {
  },
 };
 /**
 * 随机字符串生成器
 */
 export const randomString: GeneratorDefinition = {
  id: 'randomString',
  name: '随机字符串',
@@ -152,6 +179,9 @@ export const randomString: GeneratorDefinition = {
  },
 };
 /**
 * 从列表选择生成器
 */
 export const fromList: GeneratorDefinition = {
  id: 'fromList',
  name: '从列表选择',
@@ -1,6 +1,27 @@
-import type { GeneratorDefinition } from '@/types/testDataGenerator';
+/**
-import { randomInt, randomPick } from './random';
+ * 业务数据生成器
 * 包含：订单号、价格、日期、状态、数量、评分、折扣、库存
 */
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
 /**
 * 生成随机整数
 */
 function randomInt(min: number, max: number): number {
  return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 /**
 * 从数组中随机选择
 */
 function randomPick<T>(arr: T[]): T {
  return arr[Math.floor(Math.random() * arr.length)];
 }
 /**
 * 格式化日期
 */
 function formatDate(date: Date, format: string): string {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
@@ -18,6 +39,9 @@ function formatDate(date: Date, format: string): string {
    .replace('ss', seconds);
 }
 /**
 * 订单号生成器
 */
 export const orderId: GeneratorDefinition = {
  id: 'orderId',
  name: '订单号',
@@ -57,6 +81,9 @@ export const orderId: GeneratorDefinition = {
  },
 };
 /**
 * 价格生成器
 */
 export const price: GeneratorDefinition = {
  id: 'price',
  name: '价格',
@@ -128,6 +155,9 @@ export const price: GeneratorDefinition = {
  },
 };
 /**
 * 生成心理定价（如 9.99, 19.9, 99）
 */
 function generatePsychologicalPrice(min: number, max: number): number {
  const patterns = [
    () => {
@@ -150,6 +180,9 @@ function generatePsychologicalPrice(min: number, max: number): number {
  return price;
 }
 /**
 * 生成真实分布价格（对数正态分布）
 */
 function generateRealisticPrice(min: number, max: number): number {
  const mean = (Math.log(min) + Math.log(max)) / 2;
  const stdDev = (Math.log(max) - Math.log(min)) / 4;
@@ -162,6 +195,9 @@ function generateRealisticPrice(min: number, max: number): number {
  return Math.max(min, Math.min(max, value));
 }
 /**
 * 日期生成器
 */
 export const date: GeneratorDefinition = {
  id: 'date',
  name: '日期',
@@ -212,6 +248,9 @@ export const date: GeneratorDefinition = {
  },
 };
 /**
 * 状态生成器
 */
 export const status: GeneratorDefinition = {
  id: 'status',
  name: '状态',
@@ -264,6 +303,9 @@ export const status: GeneratorDefinition = {
  },
 };
 /**
 * 数量生成器
 */
 export const quantity: GeneratorDefinition = {
  id: 'quantity',
  name: '数量',
@@ -310,6 +352,9 @@ export const quantity: GeneratorDefinition = {
  },
 };
 /**
 * 泊松分布随机数
 */
 function poissonRandom(lambda: number): number {
  const L = Math.exp(-lambda);
  let k = 0;
@@ -321,6 +366,9 @@ function poissonRandom(lambda: number): number {
  return k - 1;
 }
 /**
 * 评分生成器
 */
 export const rating: GeneratorDefinition = {
  id: 'rating',
  name: '评分',
@@ -375,6 +423,9 @@ export const rating: GeneratorDefinition = {
  },
 };
 /**
 * 偏向高分的随机数（模拟真实评分分布）
 */
 function skewedRandom(min: number, max: number): number {
  // 使用 Beta 分布模拟评分偏向
  const alpha = 3;
@@ -383,10 +434,13 @@ function skewedRandom(min: number, max: number): number {
    v = 0;
  while (u === 0) u = Math.random();
  while (v === 0) v = Math.random();
-  const x = Math.pow(u, 1 / alpha) / (Math.pow(u, 1 / alpha) + Math.pow(v, 1 / beta));
+  const x = Math.pow(u, 1 / alpha) / Math.pow(u, 1 / alpha) + Math.pow(v, 1 / beta);
  return min + x * (max - min);
 }
 /**
 * 折扣生成器
 */
 export const discount: GeneratorDefinition = {
  id: 'discount',
  name: '折扣',
@@ -438,6 +492,9 @@ export const discount: GeneratorDefinition = {
  },
 };
 /**
 * 生成心理折扣（如 5%, 10%, 20%, 30%）
 */
 function generatePsychologicalDiscount(min: number, max: number): number {
  const psychologicalDiscounts = [5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80];
  const validDiscounts = psychologicalDiscounts.filter((d) => d >= min && d <= max);
@@ -447,6 +504,9 @@ function generatePsychologicalDiscount(min: number, max: number): number {
  return randomInt(min, max);
 }
 /**
 * 库存生成器
 */
 export const stock: GeneratorDefinition = {
  id: 'stock',
  name: '库存',
@@ -1,9 +1,17 @@
 /**
 * 生成器库索引
 * 导出所有生成器和分类配置
 */
 import type { GeneratorDefinition, GeneratorCategory } from '@/types/testDataGenerator';
 import { personalGenerators } from './personal';
 import { businessGenerators } from './business';
 import { technicalGenerators } from './technical';
 import { basicGenerators } from './basic';
 /**
 * 生成器分类配置
 */
 export const generatorCategories: GeneratorCategory[] = [
  { id: 'personal', name: '个人信息', icon: 'User' },
  { id: 'business', name: '业务数据', icon: 'Briefcase' },
@@ -11,6 +19,9 @@ export const generatorCategories: GeneratorCategory[] = [
  { id: 'basic', name: '基础类型', icon: 'Hash' },
 ];
 /**
 * 所有生成器列表
 */
 export const allGenerators: GeneratorDefinition[] = [
  ...personalGenerators,
  ...businessGenerators,
@@ -18,14 +29,23 @@ export const allGenerators: GeneratorDefinition[] = [
  ...basicGenerators,
 ];
 /**
 * 根据 ID 获取生成器
 */
 export function getGeneratorById(id: string): GeneratorDefinition | undefined {
  return allGenerators.find((g) => g.id === id);
 }
 /**
 * 根据分类 ID 获取生成器列表
 */
 export function getGeneratorsByCategory(categoryId: string): GeneratorDefinition[] {
  return allGenerators.filter((g) => g.categoryId === categoryId);
 }
 /**
 * 搜索生成器
 */
 export function searchGenerators(query: string): GeneratorDefinition[] {
  const lowerQuery = query.toLowerCase();
  return allGenerators.filter(
@@ -1,6 +1,11 @@
-import type { GeneratorDefinition } from '@/types/testDataGenerator';
+/**
-import { randomInt, randomPick } from './random';
+ * 个人信息生成器
 * 包含：中文姓名、邮箱、手机号、身份证号、中文地址、年龄
 */
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
 // 中文姓氏
 const SURNAMES = [
  '王',
  '李',
@@ -54,6 +59,7 @@ const SURNAMES = [
  '阎',
 ];
 // 中文名字常用字
 const NAME_CHARS = [
  '伟',
  '芳',
@@ -107,8 +113,10 @@ const NAME_CHARS = [
  '慧',
 ];
 // 邮箱域名
 const EMAIL_DOMAINS = ['qq.com', '163.com', '126.com', 'gmail.com', 'outlook.com', 'hotmail.com'];
 // 省份
 const PROVINCES = [
  '北京市',
  '天津市',
@@ -144,6 +152,7 @@ const PROVINCES = [
  '新疆维吾尔自治区',
 ];
 // 城市
 const CITIES: Record<string, string[]> = {
  北京市: ['东城区', '西城区', '朝阳区', '海淀区'],
  上海市: ['黄浦区', '徐汇区', '长宁区', '静安区'],
@@ -153,6 +162,23 @@ const CITIES: Record<string, string[]> = {
  四川省: ['成都市', '绵阳市', '德阳市', '宜宾市'],
 };
 /**
 * 生成随机整数
 */
 function randomInt(min: number, max: number): number {
  return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 /**
 * 从数组中随机选择
 */
 function randomPick<T>(arr: T[]): T {
  return arr[Math.floor(Math.random() * arr.length)];
 }
 /**
 * 中文姓名生成器
 */
 export const chineseName: GeneratorDefinition = {
  id: 'chineseName',
  name: '中文姓名',
@@ -166,6 +192,9 @@ export const chineseName: GeneratorDefinition = {
  },
 };
 /**
 * 邮箱生成器
 */
 export const email: GeneratorDefinition = {
  id: 'email',
  name: '邮箱',
@@ -192,6 +221,9 @@ export const email: GeneratorDefinition = {
  },
 };
 /**
 * 手机号生成器
 */
 export const chinesePhone: GeneratorDefinition = {
  id: 'chinesePhone',
  name: '手机号',
@@ -222,6 +254,9 @@ export const chinesePhone: GeneratorDefinition = {
  },
 };
 /**
 * 身份证号生成器
 */
 export const idCard: GeneratorDefinition = {
  id: 'idCard',
  name: '身份证号',
@@ -246,12 +281,20 @@ export const idCard: GeneratorDefinition = {
  generate: (params) => {
    const regions = ['110101', '310101', '440103', '440305', '510104', '330102'];
    const region = params.region === 'random' ? randomPick(regions) : (params.region as string);
    // 出生日期 1960-2005年
    const year = randomInt(1960, 2005);
    const month = String(randomInt(1, 12)).padStart(2, '0');
    const day = String(randomInt(1, 28)).padStart(2, '0');
    const birthday = `${year}${month}${day}`;
    // 顺序码
    const sequence = String(randomInt(1, 999)).padStart(3, '0');
    // 前17位
    const prefix17 = region + birthday + sequence;
    // 校验码
    const weights = [7, 9, 10, 5, 8, 4, 2, 1, 6, 3, 7, 9, 10, 5, 8, 4, 2];
    const checkCodes = ['1', '0', 'X', '9', '8', '7', '6', '5', '4', '3', '2'];
    let sum = 0;
@@ -287,6 +330,9 @@ export const idCard: GeneratorDefinition = {
  },
 };
 /**
 * 中文地址生成器
 */
 export const chineseAddress: GeneratorDefinition = {
  id: 'chineseAddress',
  name: '中文地址',
@@ -315,6 +361,9 @@ export const chineseAddress: GeneratorDefinition = {
  },
 };
 /**
 * 年龄生成器
 */
 export const age: GeneratorDefinition = {
  id: 'age',
  name: '年龄',
@@ -366,6 +415,9 @@ export const age: GeneratorDefinition = {
  },
 };
 /**
 * 正态分布随机数
 */
 function normalRandom(min: number, max: number): number {
  const mean = (min + max) / 2;
  const stdDev = (max - min) / 6;
@@ -378,6 +430,9 @@ function normalRandom(min: number, max: number): number {
  return Math.max(min, Math.min(max, value));
 }
 /**
 * 人口统计分布随机数（模拟真实年龄分布）
 */
 function demographicRandom(): number {
  const ageGroups = [
    { min: 0, max: 14, weight: 0.18 },
@@ -1,7 +0,0 @@
 export function randomInt(min: number, max: number): number {
  return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 export function randomPick<T>(arr: readonly T[]): T {
  return arr[Math.floor(Math.random() * arr.length)];
 }
@@ -1,6 +1,27 @@
-import type { GeneratorDefinition } from '@/types/testDataGenerator';
+/**
-import { randomInt, randomPick } from './random';
+ * 技术数据生成器
 * 包含：UUID、IPv4、URL
 */
 import type { GeneratorDefinition } from '@/types/testDataGenerator';
 /**
 * 生成随机整数
 */
 function randomInt(min: number, max: number): number {
  return Math.floor(Math.random() * (max - min + 1)) + min;
 }
 /**
 * 从数组中随机选择
 */
 function randomPick<T>(arr: T[]): T {
  return arr[Math.floor(Math.random() * arr.length)];
 }
 /**
 * UUID 生成器
 */
 export const uuid: GeneratorDefinition = {
  id: 'uuid',
  name: 'UUID',
@@ -57,6 +78,9 @@ export const uuid: GeneratorDefinition = {
  },
 };
 /**
 * 生成 UUID v4
 */
 function generateUUIDv4(): string {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
    const r = (Math.random() * 16) | 0;
@@ -65,6 +89,9 @@ function generateUUIDv4(): string {
  });
 }
 /**
 * 生成 UUID v1（简化版本，模拟时间戳）
 */
 function generateUUIDv1(): string {
  const now = Date.now();
  const timeLow = (now & 0xffffffff).toString(16).padStart(8, '0');
@@ -78,6 +105,9 @@ function generateUUIDv1(): string {
  return `${timeLow}-${timeMid}-${timeHi.toString(16)}-${clockSeq.toString(16)}-${node}`;
 }
 /**
 * IPv4 生成器
 */
 export const ipv4: GeneratorDefinition = {
  id: 'ipv4',
  name: 'IPv4',
@@ -112,10 +142,16 @@ export const ipv4: GeneratorDefinition = {
  },
 };
 /**
 * 生成完全随机 IPv4
 */
 function generateRandomIPv4(): string {
  return Array.from({ length: 4 }, () => randomInt(0, 255)).join('.');
 }
 /**
 * 生成内网 IPv4
 */
 function generatePrivateIPv4(): string {
  const ranges = [
    { prefix: '10', second: () => randomInt(0, 255) },
@@ -130,6 +166,9 @@ function generatePrivateIPv4(): string {
  return `${range.prefix}.${range.second()}.${randomInt(1, 254)}.${randomInt(1, 254)}`;
 }
 /**
 * 生成公网 IPv4
 */
 function generatePublicIPv4(): string {
  let first: number;
  do {
@@ -139,6 +178,9 @@ function generatePublicIPv4(): string {
  return `${first}.${randomInt(0, 255)}.${randomInt(0, 255)}.${randomInt(1, 254)}`;
 }
 /**
 * URL 生成器
 */
 export const url: GeneratorDefinition = {
  id: 'url',
  name: 'URL',
@@ -208,6 +250,8 @@ export const url: GeneratorDefinition = {
        path = `/${randomPick(['about', 'contact', 'products', 'services', 'blog'])}`;
      }
    }
    // 添加查询参数
    let query = '';
    if (Math.random() > 0.5) {
      const params = new URLSearchParams();
@@ -1,5 +1,6 @@
 import { type ClassValue, clsx } from 'clsx';
 import { twMerge } from 'tailwind-merge';
 export function cn(...inputs: ClassValue[]) {
-  return clsx(inputs);
+  return twMerge(clsx(inputs));
 }
@@ -1,14 +1,14 @@
 import { Image as ImageIcon, Trash2, Upload } from 'lucide-react';
 import TextInputArea from '@/components/TextInputArea';
 import { useI18n } from '@/utils/chromeI18n';
 import { CopyButton } from '@/components/CopyButton';
-import DecodeResultPaper from './DecodeResultPaper';
+import DecodeResultPaper from '@/components/DecodeResultPaper';
 import { Button } from '@/components/ui/button';
-import { downloadBlob } from '@/utils/base64Converter';
+import { downloadBlob, formatFileSize } from '@/utils/base64Converter';
 import { formatBytes } from '@/utils/format';
 import { useStorageState } from '@/utils/useStorageState';
 import type { Base64ConvertDirection } from '@/types/storage';
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
-import { useBase64Converter } from '../useBase64Converter';
+import { useBase64Converter } from './useBase64Converter';
 import { cn } from '@/lib/utils';
 const isValidDirection = (val: unknown): val is Base64ConvertDirection =>
@@ -19,6 +19,8 @@ interface Base64ConverterSectionProps {
 }
 export default function Base64ConverterSection({ mode }: Base64ConverterSectionProps) {
  const { t } = useI18n('base64Converter');
  const [direction, setDirection] = useStorageState(
    `base64Converter/${mode}Mode/direction`,
    'encode',
@@ -40,24 +42,28 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
    decodedFileName,
    setCustomFileName,
    resetAll,
-    handleFileSelect,
+    safeFileSelect,
    maxFileSizeStr,
  } = useBase64Converter({ mode });
  const handleDirectionChange = (next: Base64ConvertDirection) => {
-    if (next === direction) return;
+    if (!next || next === direction) return;
    resetAll();
    setDirection(next);
  };
  const handleDownload = () => {
    if (decoded) downloadBlob(decoded.blob, decodedFileName);
  };
  return (
    <div className="w-full flex flex-col space-y-4 px-2">
      <div className="flex h-11 items-center px-1.5 bg-secondary/40 rounded-xl border border-border/60 w-fit">
        <SwitchButtonGroup
          value={direction}
          options={[
-            { value: 'encode', label: '编码' },
+            { value: 'encode', label: t('encode') },
-            { value: 'decode', label: '解码' },
+            { value: 'decode', label: t('decode') },
          ]}
          onChange={handleDirectionChange}
          size="small"
@@ -76,7 +82,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
              e.preventDefault();
              setIsDragging(false);
              const file = e.dataTransfer.files[0];
-              if (file) void handleFileSelect(file);
+              if (file) safeFileSelect(file);
            }}
            onClick={() => fileInputRef.current?.click()}
            className={cn(
@@ -95,7 +101,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
              hidden
              onChange={(e) => {
                const file = e.target.files?.[0];
-                if (file) void handleFileSelect(file);
+                if (file) safeFileSelect(file);
              }}
            />
            {isLoading ? (
@@ -111,15 +117,15 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
                    />
                  </div>
                )}
-                <Upload className="w-8 h-8 text-primary" />
+                <Upload className={cn('w-8 h-8 text-primary')} />
                <span className="text-sm font-bold text-foreground/90 max-w-[280px] truncate">
                  {info.name}
                </span>
                <span className="text-xs text-muted-foreground/80 font-mono tabular-nums">
-                  {formatBytes(info.size)} · {info.type}
+                  {formatFileSize(info.size)} · {info.type}
                </span>
                <span className="text-[11px] font-medium text-primary/80 mt-1">
-                  点击或拖拽以替换文件
+                  {t('clickOrDropToReplace')}
                </span>
              </div>
            ) : (
@@ -130,14 +136,14 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
                  <Upload className="w-8 h-8 text-muted-foreground/60" />
                )}
                <span className="text-xs font-bold text-foreground/80">
-                  {mode === 'image' ? '点击或拖拽图像到此处' : '点击或拖拽文件到此处'}
+                  {mode === 'image' ? t('clickOrDropToImage') : t('clickOrDropToFile')}
                </span>
                <span className="text-[10px] font-medium text-muted-foreground/60">
-                  最大文件大小：{maxFileSizeStr}
+                  {t('maxFileSize', { max: maxFileSizeStr })}
                </span>
                {mode === 'image' && (
                  <span className="text-[10px] font-medium text-muted-foreground/50">
-                    支持 PNG、JPG、WEBP、GIF、BMP、SVG 等格式
+                    {t('supportedFormats')}
                  </span>
                )}
              </div>
@@ -154,17 +160,17 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
            <div className="p-4 rounded-2xl bg-card border border-border shadow-sm flex flex-col space-y-3">
              <div className="flex justify-between items-center select-none">
                <span className="text-[10px] font-bold uppercase tracking-wider text-muted-foreground/90">
-                  Base64 编码结果
+                  {t('base64Output')}
                </span>
                <div className="flex gap-2">
                  <CopyButton
                    text={result.rawBase64}
-                    tooltip="复制纯 Base64"
+                    tooltip={t('copyRaw')}
                    className="h-6 px-2 rounded-md border text-[10px] font-bold"
                  />
                  <CopyButton
                    text={result.output}
-                    tooltip="复制 Data URI"
+                    tooltip={t('copyDataUri')}
                    className="h-6 px-2 rounded-md border text-[10px] font-bold"
                  />
                </div>
@@ -182,16 +188,16 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
              <div className="flex items-center justify-between font-mono text-[10px] text-muted-foreground/70 select-none pt-1">
                <div className="flex gap-4 items-center tabular-nums">
                  <span>
-                    原始大小:{' '}
+                    {t('originalSize')}:{' '}
                    <span className="font-semibold text-foreground/80">
-                      {formatBytes(result.originalBytes)}
+                      {formatFileSize(result.originalBytes)}
                    </span>
                  </span>
                  <span className="text-border/60">|</span>
                  <span>
-                    编码大小:{' '}
+                    {t('encodedSize')}:{' '}
                    <span className="font-semibold text-foreground/80">
-                      {formatBytes(result.outputBytes)}
+                      {formatFileSize(result.outputBytes)}
                    </span>
                  </span>
                </div>
@@ -202,7 +208,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
                  className="h-7 rounded-md text-muted-foreground hover:text-destructive text-[11px] gap-1 px-2"
                >
                  <Trash2 className="w-3.5 h-3.5" />
-                  清空
+                  {t('clear')}
                </Button>
              </div>
            </div>
@@ -211,7 +217,7 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
      ) : (
        <div className="flex flex-col space-y-4">
          <TextInputArea
-            placeholder="输入需要解码的 Base64 或 data URI..."
+            placeholder={t('decodeBase64Placeholder')}
            value={decodeInput}
            onChange={setDecodeInput}
            externalError={decodeError || undefined}
@@ -222,12 +228,12 @@ export default function Base64ConverterSection({ mode }: Base64ConverterSectionP
          />
          {decoded && (
            <DecodeResultPaper
-              title={mode === 'image' ? '解码图像' : '解码文件'}
+              title={mode === 'image' ? t('decodedImageOutput') : t('decodedFileOutput')}
              mimeType={decoded.mimeType}
              blobSize={decoded.blob.size}
              fileName={decodedFileName}
              onFileNameChange={setCustomFileName}
-              onDownload={() => downloadBlob(decoded.blob, decodedFileName)}
+              onDownload={handleDownload}
            >
              {mode === 'image' && (
                <div className="relative p-1.5 border border-border bg-background dark:bg-muted/10 rounded-xl max-w-[220px] mb-3 overflow-hidden shadow-sm">
@@ -0,0 +1,162 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import TextInputArea from '@/components/TextInputArea';
 import { useI18n } from '@/utils/chromeI18n';
 import { CopyButton } from '@/components/CopyButton';
 import { base64ToText, textToBase64 } from '@/utils/base64Converter';
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
 import { useContextMenuData } from '@/utils/useContextMenuData';
 import { Button } from '@/components/ui/button';
 const IMAGE_DATA_URI_PATTERN = /^\s*data:image\//i;
 const ERROR_MESSAGE_TO_I18N: Record<string, string> = {
  'Invalid Base64 string': 'invalidBase64',
  'Input appears to be binary data (e.g. an image). Please use the Image tab instead.':
    'binaryDataDetected',
 };
 interface TextModeProps {
  onSwitchToImageMode?: () => void;
 }
 export default function TextMode({ onSwitchToImageMode }: TextModeProps = {}) {
  const { t } = useI18n('base64Converter');
  const [input, setInput] = useState('');
  const [debouncedInput, setDebouncedInput] = useState('');
  const [direction, setDirection] = useState<'encode' | 'decode'>('encode');
  useEffect(() => {
    const handle = setTimeout(() => {
      setDebouncedInput(input);
    }, 200);
    return () => clearTimeout(handle);
  }, [input]);
  const handleContextMenuData = useCallback((payload: string) => {
    setInput(payload);
    setDebouncedInput(payload);
    setDirection('decode');
  }, []);
  useContextMenuData({ featureKey: 'base64Converter', onData: handleContextMenuData });
  const conversionPipeline = useMemo(() => {
    const trimmed = debouncedInput.trim();
    if (!trimmed) return { output: '', error: null };
    try {
      if (direction === 'encode') {
        const result = textToBase64(debouncedInput);
        return { output: result.output, error: null };
      } else {
        const decoded = base64ToText(trimmed);
        return { output: decoded, error: null };
      }
    } catch (e) {
      const message = e instanceof Error ? e.message : '';
      const i18nKey = ERROR_MESSAGE_TO_I18N[message];
      return {
        output: '',
        error: i18nKey ? t(i18nKey) : message || t('conversionFailed'),
      };
    }
  }, [debouncedInput, direction, t]);
  const output = conversionPipeline.output;
  const error = conversionPipeline.error;
  const placeholder =
    direction === 'encode' ? t('textInputPlaceholder') : t('base64InputPlaceholder');
  const outputLabel = direction === 'encode' ? t('base64Output') : t('textOutput');
  const showImageHint = useMemo(
    () => direction === 'decode' && IMAGE_DATA_URI_PATTERN.test(input),
    [direction, input],
  );
  const handleDirectionChange = (value: 'encode' | 'decode') => {
    if (value === direction) return;
    setDirection(value);
    setInput('');
    setDebouncedInput('');
  };
  const handleClear = () => {
    setInput('');
    setDebouncedInput('');
  };
  return (
    <div className="w-full flex flex-col space-y-4 px-2">
      {/* 受控方向切流中枢 */}
      <div className="flex h-11 items-center px-1.5 bg-secondary/40 rounded-xl border border-border/60 w-fit">
        <SwitchButtonGroup
          value={direction}
          options={[
            { value: 'encode', label: t('encode') },
            { value: 'decode', label: t('decode') },
          ]}
          onChange={handleDirectionChange}
          size="small"
        />
      </div>
      {/* 高性能受控文本输入端 */}
      <TextInputArea
        placeholder={placeholder}
        value={input}
        onChange={setInput}
        externalError={error || undefined}
        showClear={true}
        allowCopy={true}
        minRows={5}
        maxRows={10}
        onClear={handleClear}
      />
      {/* 图片 URI 类型劫持警告引导区：
        - 💡 修复点：彻底废除原生亮色硬编码 hover:bg-blue-100 类名，
        - 完美向全站 shadcn 暗黑生态看齐，采用标准的 bg-primary/10 混合变体。
      */}
      {showImageHint && (
        <div className="flex items-center justify-between p-3.5 rounded-xl bg-primary/10 border border-primary/20">
          <span className="text-xs font-semibold text-primary tracking-tight">
            {t('imageDataUriHint')}
          </span>
          <Button
            type="button"
            variant="ghost"
            size="sm"
            onClick={onSwitchToImageMode}
            className="h-7 rounded-md text-xs font-bold text-primary hover:text-primary hover:bg-primary/20 dark:hover:bg-primary/10 px-2.5"
          >
            {t('switchToImageMode')}
          </Button>
        </div>
      )}
      {/* 5. 编码/解码核心数据承载流卡片 */}
      {output && (
        <div className="p-4 rounded-2xl bg-card border border-border shadow-sm flex flex-col space-y-3">
          <div className="flex justify-between items-center select-none">
            <span className="text-[10px] font-bold uppercase tracking-wider text-muted-foreground/90">
              {outputLabel}
            </span>
            <CopyButton
              text={output}
              className="h-6 px-2 rounded-md border text-[10px] font-bold"
            />
          </div>
          <TextInputArea
            readOnly
            value={output.length > 2000 ? `${output.substring(0, 2000)}...` : output}
            showClear={false}
            minRows={4}
          />
        </div>
      )}
    </div>
  );
 }
@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
-import TextMode from '../components/TextMode';
+import TextMode from '../TextMode';
 // Mock CopyButton
 vi.mock('@/components/CopyButton', () => ({
@@ -76,7 +76,7 @@ describe('TextMode', () => {
    });
    await waitFor(() => {
-      expect(screen.getByText('无效的 Base64 字符串')).toBeInTheDocument();
+      expect(screen.getByText('Base64 字符串无效')).toBeInTheDocument();
    });
  });
@@ -118,7 +118,7 @@ describe('TextMode', () => {
      expect(screen.getByRole('button', { name: 'SGVsbG8=' })).toBeInTheDocument();
    });
-    fireEvent.click(screen.getByRole('button', { name: '清空' }));
+    fireEvent.click(screen.getByRole('button', { name: 'textInputArea.clear' }));
    await waitFor(() => {
      expect(screen.queryByRole('button', { name: 'SGVsbG8=' })).not.toBeInTheDocument();
@@ -182,7 +182,9 @@ describe('TextMode', () => {
    });
    await waitFor(() => {
-      expect(screen.getByText('检测到二进制数据（如图像），请使用图像选项卡')).toBeInTheDocument();
+      expect(
        screen.getByText('输入似乎是二进制数据（如图片）。请切换到「图像」选项卡。'),
      ).toBeInTheDocument();
    });
  });
 });
@@ -2,8 +2,17 @@ import { describe, expect, it, vi } from 'vitest';
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import Base64ConverterPage from '../index';
 // Mock getEntryPointType
 vi.mock('@/config/features', async (importOriginal) => {
  const actual = await importOriginal<typeof import('@/config/features')>();
  return {
    ...actual,
    getEntryPointType: () => 'sidepanel',
  };
 });
 // Mock 子组件
-vi.mock('../components/TextMode', () => ({
+vi.mock('../TextMode', () => ({
  default: ({ onSwitchToImageMode }: { onSwitchToImageMode?: () => void }) => (
    <div data-testid="text-mode">
      TextMode
@@ -12,10 +21,8 @@ vi.mock('../components/TextMode', () => ({
  ),
 }));
-vi.mock('../components/Base64ConverterSection', () => ({
+vi.mock('../Base64ConverterSection', () => ({
-  default: ({ mode }: { mode: 'file' | 'image' }) => (
+  default: ({ mode }: { mode: string }) => <div data-testid={`${mode}-mode`}>{mode}</div>,
    <div data-testid={`${mode}-mode`}>{mode.toUpperCase()} Mode</div>
  ),
 }));
 const waitForStorageInit = () =>
@@ -1,53 +0,0 @@
 import { Download } from 'lucide-react';
 import { Button } from '@/components/ui/button';
 import { Input } from '@/components/ui/input';
 import { Label } from '@/components/ui/label';
 import { formatBytes } from '@/utils/format';
 interface DecodeResultPaperProps {
  title: string;
  mimeType: string;
  blobSize: number;
  fileName: string;
  onFileNameChange: (name: string) => void;
  onDownload: () => void;
  children?: React.ReactNode;
 }
 export default function DecodeResultPaper({
  title,
  mimeType,
  blobSize,
  fileName,
  onFileNameChange,
  onDownload,
  children,
 }: DecodeResultPaperProps) {
  return (
    <div className="p-4 rounded-xl bg-primary/10 border border-primary/30">
      <span className="block mb-2 text-xs font-bold text-muted-foreground">{title}</span>
      {children}
      <div className="flex gap-4 mb-3">
        <span className="text-xs text-muted-foreground">推断的 MIME 类型: {mimeType}</span>
        <span className="text-xs text-muted-foreground">解码大小: {formatBytes(blobSize)}</span>
      </div>
      <div className="mb-3">
        <Label className="block text-xs font-medium text-muted-foreground mb-1">解码后文件名</Label>
        <Input value={fileName} onChange={(e) => onFileNameChange(e.target.value)} />
      </div>
      <Button
        variant="default"
        onClick={onDownload}
        disabled={!fileName.trim()}
        className="w-full rounded-lg font-bold"
      >
        <Download className="mr-2 h-4 w-4" />
        下载
      </Button>
    </div>
  );
 }
@@ -1,90 +0,0 @@
 import TextInputArea from '@/components/TextInputArea';
 import { CopyButton } from '@/components/CopyButton';
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
 import { Button } from '@/components/ui/button';
 import { useTextMode } from '../useTextMode';
 interface TextModeProps {
  onSwitchToImageMode?: () => void;
 }
 export default function TextMode({ onSwitchToImageMode }: TextModeProps) {
  const {
    input,
    setInput,
    direction,
    handleDirectionChange,
    placeholder,
    output,
    outputLabel,
    error,
    showImageHint,
    handleClear,
  } = useTextMode();
  return (
    <div className="w-full flex flex-col space-y-4 px-2">
      <div className="flex h-11 items-center px-1.5 bg-secondary/40 rounded-xl border border-border/60 w-fit">
        <SwitchButtonGroup
          value={direction}
          options={[
            { value: 'encode', label: '编码' },
            { value: 'decode', label: '解码' },
          ]}
          onChange={handleDirectionChange}
          size="small"
        />
      </div>
      <TextInputArea
        placeholder={placeholder}
        value={input}
        onChange={setInput}
        externalError={error || undefined}
        showClear={true}
        allowCopy={true}
        minRows={5}
        maxRows={10}
        onClear={handleClear}
      />
      {showImageHint && (
        <div className="flex items-center justify-between p-3.5 rounded-xl bg-primary/10 border border-primary/20">
          <span className="text-xs font-semibold text-primary tracking-tight">
            检测到图片的 data URI，请使用「图像」选项卡进行解码。
          </span>
          <Button
            type="button"
            variant="ghost"
            size="sm"
            onClick={onSwitchToImageMode}
            className="h-7 rounded-md text-xs font-bold text-primary hover:text-primary hover:bg-primary/20 dark:hover:bg-primary/10 px-2.5"
          >
            切换到图像模式
          </Button>
        </div>
      )}
      {output && (
        <div className="p-4 rounded-2xl bg-card border border-border shadow-sm flex flex-col space-y-3">
          <div className="flex justify-between items-center select-none">
            <span className="text-[10px] font-bold uppercase tracking-wider text-muted-foreground/90">
              {outputLabel}
            </span>
            <CopyButton
              text={output}
              className="h-6 px-2 rounded-md border text-[10px] font-bold"
            />
          </div>
          <TextInputArea
            readOnly
            value={output.length > 2000 ? `${output.substring(0, 2000)}...` : output}
            showClear={false}
            minRows={4}
          />
        </div>
      )}
    </div>
  );
 }
@@ -1,7 +1,8 @@
 import { useI18n } from '@/utils/chromeI18n';
 import { useStorageState } from '@/utils/useStorageState';
 import type { Base64ConverterPageMode } from '@/types/storage';
-import TextMode from './components/TextMode';
+import TextMode from './TextMode';
-import Base64ConverterSection from './components/Base64ConverterSection';
+import Base64ConverterSection from './Base64ConverterSection';
 import SwitchButtonGroup from '@/components/SwitchButtonGroup';
 const VALID_PAGE_MODES: readonly Base64ConverterPageMode[] = ['text', 'file', 'image'];
@@ -11,6 +12,7 @@ const isValidPageMode = (val: unknown): val is Base64ConverterPageMode =>
 type PageMode = Base64ConverterPageMode;
 export default function Index() {
  const { t } = useI18n('base64Converter');
  const [pageMode, setPageMode] = useStorageState(
    'base64Converter/pageMode',
    'text',
@@ -22,9 +24,9 @@ export default function Index() {
      <SwitchButtonGroup
        value={pageMode}
        options={[
-          { value: 'text', label: '文本' },
+          { value: 'text', label: t('base64Converter:textMode') },
-          { value: 'file', label: '文件' },
+          { value: 'file', label: t('base64Converter:fileMode') },
-          { value: 'image', label: '图像' },
+          { value: 'image', label: t('base64Converter:imageMode') },
        ]}
        onChange={(value: PageMode) => setPageMode(value)}
        size="small"
@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useI18n } from '@/utils/chromeI18n';
 import type { FileToBase64Result } from '@/utils/base64Converter';
 import {
  base64ToBlob,
@@ -20,6 +21,8 @@ interface UseBase64ConverterProps {
 }
 export function useBase64Converter({ mode }: UseBase64ConverterProps) {
  const { t } = useI18n('base64Converter');
  const [result, setResult] = useState<FileToBase64Result | null>(null);
  const [info, setInfo] = useState<FileInfo | null>(null);
  const [isLoading, setIsLoading] = useState(false);
@@ -59,7 +62,7 @@ export function useBase64Converter({ mode }: UseBase64ConverterProps) {
      setInfo(null);
      if (!isFileSizeValid(file.size)) {
-        setEncodeError(`文件大小超出限制（最大 ${MAX_FILE_SIZE / 1024 / 1024} MB）`);
+        setEncodeError(t('fileSizeExceeded', { max: `${MAX_FILE_SIZE / 1024 / 1024} MB` }));
        return;
      }
@@ -68,7 +71,7 @@ export function useBase64Converter({ mode }: UseBase64ConverterProps) {
        !isSupportedImageType(file.type) &&
        !isSupportedImageExtension(file.name)
      ) {
-        setEncodeError('不支持的图像格式');
+        setEncodeError(t('unsupportedImageType'));
        return;
      }
@@ -84,16 +87,25 @@ export function useBase64Converter({ mode }: UseBase64ConverterProps) {
        if (!cancelRef.current) setResult(res);
      } catch (e) {
        if (!cancelRef.current) {
-          setEncodeError(e instanceof Error ? e.message : '转换失败');
+          setEncodeError(e instanceof Error ? e.message : t('conversionFailed'));
        }
      } finally {
        if (!cancelRef.current) setIsLoading(false);
      }
    },
-    [mode],
+    [mode, t],
  );
-  const decodeResult = useMemo(() => {
+  const safeFileSelect = useCallback(
    (file: File) => {
      handleFileSelect(file).catch((err) => {
        console.error(`Base64 [${mode}] pipeline crash:`, err);
      });
    },
    [handleFileSelect, mode],
  );
  const decodePipeline = useMemo(() => {
    const cleanedInput = debouncedDecodeInput.replace(/^data:image\/[a-z+]+;base64,/i, '').trim();
    if (!cleanedInput) return { decoded: null, error: null };
@@ -104,13 +116,13 @@ export function useBase64Converter({ mode }: UseBase64ConverterProps) {
      const message = e instanceof Error ? e.message : '';
      return {
        decoded: null,
-        error: message === 'Invalid Base64 string' ? 'Base64 字符串无效' : '转换失败',
+        error: message === 'Invalid Base64 string' ? t('invalidBase64') : t('conversionFailed'),
      };
    }
-  }, [debouncedDecodeInput]);
+  }, [debouncedDecodeInput, t]);
-  const decoded = decodeResult.decoded;
+  const decoded = decodePipeline.decoded;
-  const decodeError = decodeResult.error;
+  const decodeError = decodePipeline.error;
  const decodedFileName = useMemo(() => {
    if (customFileName) return customFileName;
@@ -135,7 +147,7 @@ export function useBase64Converter({ mode }: UseBase64ConverterProps) {
    decodedFileName,
    setCustomFileName,
    resetAll,
-    handleFileSelect,
+    safeFileSelect,
    maxFileSizeStr,
  };
 }
@@ -1,86 +0,0 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import { base64ToText, textToBase64 } from '@/utils/base64Converter';
 import { useContextMenuData } from '@/utils/useContextMenuData';
 const IMAGE_DATA_URI_PATTERN = /^\s*data:image\//i;
 const ERROR_MESSAGES: Record<string, string> = {
  'Invalid Base64 string': '无效的 Base64 字符串',
  'Input appears to be binary data (e.g. an image). Please use the Image tab instead.':
    '检测到二进制数据（如图像），请使用图像选项卡',
 };
 export function useTextMode() {
  const [input, setInput] = useState('');
  const [debouncedInput, setDebouncedInput] = useState('');
  const [direction, setDirection] = useState<'encode' | 'decode'>('encode');
  useEffect(() => {
    const handle = setTimeout(() => {
      setDebouncedInput(input);
    }, 200);
    return () => clearTimeout(handle);
  }, [input]);
  const handleContextMenuData = useCallback((payload: string) => {
    setInput(payload);
    setDebouncedInput(payload);
    setDirection('decode');
  }, []);
  useContextMenuData({ featureKey: 'base64Converter', onData: handleContextMenuData });
  const conversion = useMemo(() => {
    const trimmed = debouncedInput.trim();
    if (!trimmed) return { output: '', error: null };
    try {
      if (direction === 'encode') {
        const result = textToBase64(debouncedInput);
        return { output: result.output, error: null };
      }
      const decoded = base64ToText(trimmed);
      return { output: decoded, error: null };
    } catch (e) {
      const message = e instanceof Error ? e.message : '';
      return {
        output: '',
        error: ERROR_MESSAGES[message] || message || '转换失败',
      };
    }
  }, [debouncedInput, direction]);
  const output = conversion.output;
  const error = conversion.error;
  const placeholder =
    direction === 'encode' ? '输入需要编码为 Base64 的文本...' : '输入需要解码的 Base64 字符串...';
  const outputLabel = direction === 'encode' ? 'Base64 编码结果' : '解码文本结果';
  const showImageHint = direction === 'decode' && IMAGE_DATA_URI_PATTERN.test(input);
  const handleDirectionChange = (value: 'encode' | 'decode') => {
    if (value === direction) return;
    setDirection(value);
    setInput('');
    setDebouncedInput('');
  };
  const handleClear = () => {
    setInput('');
    setDebouncedInput('');
  };
  return {
    input,
    setInput,
    direction,
    handleDirectionChange,
    placeholder,
    output,
    outputLabel,
    error,
    showImageHint,
    handleClear,
  };
 }
@@ -1,49 +0,0 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import * as featureConfig from '@/config/features';
 import { resolveDashboardFeatures } from '../dashboardFeatures';
 describe('resolveDashboardFeatures', () => {
  beforeEach(() => {
    vi.restoreAllMocks();
  });
  it('应按 keys 顺序返回可见工具，并排除 dashboard', () => {
    const items = resolveDashboardFeatures(['jwt', 'timestamp'], ['dashboard', 'timestamp', 'jwt']);
    expect(items.map((item) => item.key)).toEqual(['jwt', 'timestamp']);
    expect(items.map((item) => item.feature.label)).toEqual(['JWT 解析', '时间戳']);
  });
  it('缺少 themeColorKey 但有 icon 的工具仍应显示', () => {
    const originalGetFeatureByKey = featureConfig.getFeatureByKey;
    vi.spyOn(featureConfig, 'getFeatureByKey').mockImplementation((key) => {
      const feature = originalGetFeatureByKey(key);
      if (key === 'timestamp' && feature) {
        return { ...feature, themeColorKey: undefined };
      }
      return feature;
    });
    const items = resolveDashboardFeatures(['timestamp'], ['dashboard', 'timestamp']);
    expect(items.map((item) => item.key)).toEqual(['timestamp']);
  });
  it('应过滤不在 visiblePages 中的工具', () => {
    const items = resolveDashboardFeatures(['jwt', 'timestamp'], ['dashboard', 'timestamp']);
    expect(items.map((item) => item.key)).toEqual(['timestamp']);
  });
  it('visiblePages 无匹配工具时应返回空列表', () => {
    const items = resolveDashboardFeatures(['jwt', 'timestamp'], ['dashboard']);
    expect(items).toEqual([]);
  });
  it('应过滤缺少 icon 的工具', () => {
    const items = resolveDashboardFeatures(['dashboard', 'timestamp'], ['dashboard', 'timestamp']);
    expect(items.map((item) => item.key)).toEqual(['timestamp']);
  });
 });
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Cursor Agent	d5907ce25b	docs(工程文档): 格式化文档表格 Co-authored-by: LingandRX <LingandRX@users.noreply.github.com>	2026-06-26 08:43:20 +00:00
Cursor Agent	3cac909683	docs(工程文档): 同步当前架构说明 Co-authored-by: LingandRX <LingandRX@users.noreply.github.com>	2026-06-26 08:42:28 +00:00
		`@@ -0,0 +1 @@`
							<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="35.93" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 228"><path fill="#00D8FF" d="M210.483 73.824a171.49 171.49 0 0 0-8.24-2.597c.465-1.9.893-3.777 1.273-5.621c6.238-30.281 2.16-54.676-11.769-62.708c-13.355-7.7-35.196.329-57.254 19.526a171.23 171.23 0 0 0-6.375 5.848a155.866 155.866 0 0 0-4.241-3.917C100.759 3.829 77.587-4.822 63.673 3.233C50.33 10.957 46.379 33.89 51.995 62.588a170.974 170.974 0 0 0 1.892 8.48c-3.28.932-6.445 1.924-9.474 2.98C17.309 83.498 0 98.307 0 113.668c0 15.865 18.582 31.778 46.812 41.427a145.52 145.52 0 0 0 6.921 2.165a167.467 167.467 0 0 0-2.01 9.138c-5.354 28.2-1.173 50.591 12.134 58.266c13.744 7.926 36.812-.22 59.273-19.855a145.567 145.567 0 0 0 5.342-4.923a168.064 168.064 0 0 0 6.92 6.314c21.758 18.722 43.246 26.282 56.54 18.586c13.731-7.949 18.194-32.003 12.4-61.268a145.016 145.016 0 0 0-1.535-6.842c1.62-.48 3.21-.974 4.76-1.488c29.348-9.723 48.443-25.443 48.443-41.52c0-15.417-17.868-30.326-45.517-39.844Zm-6.365 70.984c-1.4.463-2.836.91-4.3 1.345c-3.24-10.257-7.612-21.163-12.963-32.432c5.106-11 9.31-21.767 12.459-31.957c2.619.758 5.16 1.557 7.61 2.4c23.69 8.156 38.14 20.213 38.14 29.504c0 9.896-15.606 22.743-40.946 31.14Zm-10.514 20.834c2.562 12.94 2.927 24.64 1.23 33.787c-1.524 8.219-4.59 13.698-8.382 15.893c-8.067 4.67-25.32-1.4-43.927-17.412a156.726 156.726 0 0 1-6.437-5.87c7.214-7.889 14.423-17.06 21.459-27.246c12.376-1.098 24.068-2.894 34.671-5.345a134.17 134.17 0 0 1 1.386 6.193ZM87.276 214.515c-7.882 2.783-14.16 2.863-17.955.675c-8.075-4.657-11.432-22.636-6.853-46.752a156.923 156.923 0 0 1 1.869-8.499c10.486 2.32 22.093 3.988 34.498 4.994c7.084 9.967 14.501 19.128 21.976 27.15a134.668 134.668 0 0 1-4.877 4.492c-9.933 8.682-19.886 14.842-28.658 17.94ZM50.35 144.747c-12.483-4.267-22.792-9.812-29.858-15.863c-6.35-5.437-9.555-10.836-9.555-15.216c0-9.322 13.897-21.212 37.076-29.293c2.813-.98 5.757-1.905 8.812-2.773c3.204 10.42 7.406 21.315 12.477 32.332c-5.137 11.18-9.399 22.249-12.634 32.792a134.718 134.718 0 0 1-6.318-1.979Zm12.378-84.26c-4.811-24.587-1.616-43.134 6.425-47.789c8.564-4.958 27.502 2.111 47.463 19.835a144.318 144.318 0 0 1 3.841 3.545c-7.438 7.987-14.787 17.08-21.808 26.988c-12.04 1.116-23.565 2.908-34.161 5.309a160.342 160.342 0 0 1-1.76-7.887Zm110.427 27.268a347.8 347.8 0 0 0-7.785-12.803c8.168 1.033 15.994 2.404 23.343 4.08c-2.206 7.072-4.956 14.465-8.193 22.045a381.151 381.151 0 0 0-7.365-13.322Zm-45.032-43.861c5.044 5.465 10.096 11.566 15.065 18.186a322.04 322.04 0 0 0-30.257-.006c4.974-6.559 10.069-12.652 15.192-18.18ZM82.802 87.83a323.167 323.167 0 0 0-7.227 13.238c-3.184-7.553-5.909-14.98-8.134-22.152c7.304-1.634 15.093-2.97 23.209-3.984a321.524 321.524 0 0 0-7.848 12.897Zm8.081 65.352c-8.385-.936-16.291-2.203-23.593-3.793c2.26-7.3 5.045-14.885 8.298-22.6a321.187 321.187 0 0 0 7.257 13.246c2.594 4.48 5.28 8.868 8.038 13.147Zm37.542 31.03c-5.184-5.592-10.354-11.779-15.403-18.433c4.902.192 9.899.29 14.978.29c5.218 0 10.376-.117 15.453-.343c-4.985 6.774-10.018 12.97-15.028 18.486Zm52.198-57.817c3.422 7.8 6.306 15.345 8.596 22.52c-7.422 1.694-15.436 3.058-23.88 4.071a382.417 382.417 0 0 0 7.859-13.026a347.403 347.403 0 0 0 7.425-13.565Zm-16.898 8.101a358.557 358.557 0 0 1-12.281 19.815a329.4 329.4 0 0 1-23.444.823c-7.967 0-15.716-.248-23.178-.732a310.202 310.202 0 0 1-12.513-19.846h.001a307.41 307.41 0 0 1-10.923-20.627a310.278 310.278 0 0 1 10.89-20.637l-.001.001a307.318 307.318 0 0 1 12.413-19.761c7.613-.576 15.42-.876 23.31-.876H128c7.926 0 15.743.303 23.354.883a329.357 329.357 0 0 1 12.335 19.695a358.489 358.489 0 0 1 11.036 20.54a329.472 329.472 0 0 1-11 20.722Zm22.56-122.124c8.572 4.944 11.906 24.881 6.52 51.026c-.344 1.668-.73 3.367-1.15 5.09c-10.622-2.452-22.155-4.275-34.23-5.408c-7.034-10.017-14.323-19.124-21.64-27.008a160.789 160.789 0 0 1 5.888-5.4c18.9-16.447 36.564-22.941 44.612-18.3ZM128 90.808c12.625 0 22.86 10.235 22.86 22.86s-10.235 22.86-22.86 22.86s-22.86-10.235-22.86-22.86s10.235-22.86 22.86-22.86Z"></path></svg>