docs: record TS side-by-side + legacy-peer-deps conventions (AGENTS.md + .npmrc)

docs: changelog for component testing + bundle review (B4 done, spec ④ complete)
docs: README frontend gates (lint/e2e/analyze), bilingual
2026-09-16 11:43:21 +08:00 · 2026-09-16 11:28:12 +08:00 · 2026-09-16 11:21:35 +08:00 · 2026-09-16 11:18:44 +08:00 · 2026-09-16 11:06:58 +08:00 · 2026-09-16 11:00:22 +08:00
15 changed files with 673 additions and 12 deletions
@@ -0,0 +1,41 @@
+name: e2e
+on: workflow_dispatch
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Render configs
+        working-directory: deploy
+        run: ./prepare.sh
+      - name: Start dev stack
+        working-directory: deploy
+        env:
+          JWT_SECRET: ci-e2e-only-secret
+          ADMIN_USER: admin
+          ADMIN_PASSWORD: ci-e2e-password
+        run: docker compose -f docker-compose.dev.yml up -d --build
+      - name: Wait for web
+        run: |
+          for i in $(seq 1 90); do
+            if curl -fsS http://localhost:5173/ >/dev/null 2>&1; then exit 0; fi
+            sleep 5
+          done
+          echo "web not up in 450s"; docker compose -f deploy/docker-compose.dev.yml logs --tail 50; exit 1
+      - run: cd frontend && npm ci
+      - run: cd frontend && npx playwright install --with-deps chromium
+      - name: Run e2e
+        working-directory: frontend
+        env:
+          E2E_ADMIN_USER: admin
+          E2E_ADMIN_PASSWORD: ci-e2e-password
+        run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: frontend/playwright-report
@@ -28,6 +28,7 @@ Root: `docs` (docs + changelogs), `backend` (Go webui service), `frontend` (node
 - Talks to the backend only over the HTTP APIs in `backend/cmd/webui/api` — no direct infra access (DB, redis) from the browser app.
 - Build output (`dist/`) is disposable and git-ignored; only `src`/`public` are committed.
 - Dev runs from the source mount with `node_modules` provided by the image — install new deps inside the container and commit the lockfile.
+- TypeScript runs side-by-side (`frontend/package.json`): `typescript` = TS 6.0.2 JS API for tooling (typescript-eslint doesn't support TS 7 yet), `@typescript/native` = native 7.0.2 providing `tsc`. Do not re-alias `typescript` to 7.x until typescript-eslint ships TS 7 support. Plain `npm install` needs `--legacy-peer-deps` (also pinned in `frontend/.npmrc`); `npm ci` is unaffected.

 ### deploy
 - Only config templates/examples are tracked by git; rendered `*.conf` and `logs/` are git-ignored.
@@ -10,6 +10,12 @@ The format loosely follows Keep a Changelog and can be adapted to the team's hab

 ### Added / 新增

+- Developer tooling: component testing infrastructure (vitest jsdom project + Testing Library) with sample tests for shared UI components; reader component tests are deferred to the reader redesign. Bundle analysis available via `npm run analyze`, findings documented in `docs/bundle-review.md`.
+- 开发工具链：组件测试基建（vitest jsdom project + Testing Library），公共 UI 组件配样板测试；阅读器组件测试留待阅读器改版。`npm run analyze` 可出 bundle 体积报告，结论见 `docs/bundle-review.md`。
+
+- E2E test suite (Playwright + axe-core) covering login→shelf→CBZ reading→bookmark→logout and an admin create-library/scan smoke, run against the dev compose stack via `npm run e2e` (manual pre-release gate); critical/serious a11y violations fail the run.
+- 新增 e2e 测试套件（Playwright + axe-core）：覆盖 登录→书架→CBZ 阅读→书签→退出 主流程与 admin 建库/扫描冒烟，针对 dev compose 栈以 `npm run e2e` 手动门禁运行；critical/serious 级 a11y 违规会使测试失败。
+
 - Developer tooling: ESLint (flat config, typescript-eslint + react-hooks + jsx-a11y) and Prettier are now part of `npm run check` and CI; the whole codebase passes with zero eslint errors.
 - 开发工具链：ESLint（flat config，typescript-eslint + react-hooks + jsx-a11y）与 Prettier 纳入 `npm run check` 和 CI；全库 0 eslint error。

@@ -57,6 +63,9 @@ The format loosely follows Keep a Changelog and can be adapted to the team's hab
 - Whole UI restyled to a warm library palette (stone surfaces + amber accents, replacing cool zinc + emerald): warmer dark chrome, amber primary buttons/links, hover/press feedback on shelf cards (cover lift + glow), reader header with format badge and blur, pill-style CBZ page indicator, EPUB spread centered like a book page.
 - 全站换为暖色「书房」配色（stone 深灰面 + amber 琥珀强调，替代冷色 zinc + emerald）：书架封面悬停上浮高亮、阅读器顶栏带格式徽章与毛玻璃、CBZ 页码改为悬浮胶囊、EPUB 页面居中成书卷感，主按钮/链接统一琥珀色并补齐悬停/焦点反馈。

+- Creating a library on the admin Libraries page no longer asks for a server-side absolute path; just a name (the directory lands at `BOOKS_DIR/<name>` automatically).
+- 库管理页建库不再要求填写服务端绝对路径，只需库名（目录自动落在 `BOOKS_DIR/<库名>` 下）。
+
 ### Removed / 移除

 - The admin 删除 button is gone from the reader header: deleting books now lives only in the shelf cover-card menu (with a confirm dialog), so a destructive tap can't happen one step away from the page-turn zone while reading.
@@ -64,6 +73,9 @@ The format loosely follows Keep a Changelog and can be adapted to the team's hab

 ### Fixed / 修复

+- Accessibility fixes: login screen muted text meets WCAG AA contrast in light theme (muted-foreground token darkened); the CBZ reading pane is now keyboard-scrollable (scroll container is focusable).
+- 无障碍修复：登录页弱化文本在亮色主题下达到 WCAG AA 对比度（muted-foreground 色值加深）；CBZ 阅读面板现在可用键盘滚动（滚动容器可聚焦）。
+
 - CBZ reader no longer snaps to the top (or visibly bounces) when scrolling or dragging the scrollbar near the end of a long chapter: re-estimating every unmeasured page from each newly measured page made the scroll geometry oscillate on books with mixed page orientations (and the correction was computed from a stale anchor), so the estimator now learns once from the first measured page and then stays put; after a geometry change the viewport is re-anchored absolutely (keep the current page under the same screen spot) instead of by a delta, and while the scrollbar is being dragged the reader doesn't write scrollTop at all, leaving the browser in sole control.
 - CBZ 阅读器在长章节末尾滚动或拖滚动条时不再出现"到底后被重置到上方"的跳变：此前每量完一页就用它重估所有未量页的高度，横竖版混排的书里估高来回翻转、滚动几何剧烈呼吸，且补偿量基于已过期的 anchor 计算；现改为估高只从首个实测页学习一次、之后保持稳定，几何变化后按"当前页钉回原屏幕位置"绝对重锚（不再用增量补偿），拖拽滚动条期间阅读器完全不写 scrollTop，避免与浏览器抢滚动控制权。

@@ -79,10 +91,3 @@ The format loosely follows Keep a Changelog and can be adapted to the team's hab
 - GBK/GB2312/GB18030 或 UTF-16 编码的 .txt/.md（网文导出常见）不再乱码：阅读器先按 UTF-8 严格解码，失败自动回退 GB18030，UTF-16 靠 BOM 识别。
 - Reading a large .txt no longer freezes the browser: the text is split into chapters (「第X章」/Chapter X/序章… markers, pseudo-sections for unmarked files) and rendered one chapter at a time with a chapter selector and prev/next navigation; 「第X卷/部」 are volume groupings (dropdown optgroups), not chapter breaks, and books with only volumes split by volume; reading progress restores to the saved chapter.
 - 阅读大 txt 不再卡死浏览器：正文按章节切分（识别「第X章」/Chapter X/序章等标题，无标记的按段落切成小节），每次只渲染一章，并提供章节目录选择与上一章/下一章导航；「第X卷/部」按卷分组（下拉框分组标签）而非章节边界，只有卷没有章的书按卷切分；阅读进度会恢复到上次的章节。
-
-### Changed / 变更
-
- Creating a library on the admin Libraries page no longer asks for a server-side absolute path; just a name (the directory lands at `BOOKS_DIR/<name>` automatically).
- 库管理页建库不再要求填写服务端绝对路径，只需库名（目录自动落在 `BOOKS_DIR/<库名>` 下）。
-
-_No WebUI user-visible changes in this release; the structural refactor (`web/` → `frontend/`) does not affect the served app._
@@ -48,7 +48,7 @@ go test -p 1 -count=1 ./...

 `-p 1` is required: integration tests share one PG database and each clears tables with `DELETE FROM ...` — running in parallel deletes each other's data and fails randomly. Bring the dev stack down with `down` (not `rm`), or the anonymous node_modules volume becomes an orphan. Tests that need PG/Redis skip automatically when absent; Redis downtime doesn't break functionality (the whole chain degrades to miss/passthrough, see spec §9).

-Frontend gate: `cd frontend && npm run check` (tsc + vitest + vite build).
+Frontend gate: `cd frontend && npm run check` (tsc + eslint + prettier + vitest + vite build). E2E is a separate manual pre-release gate against the dev stack: `cd frontend && npm run e2e` (requires `E2E_ADMIN_USER`/`E2E_ADMIN_PASSWORD`, or source `deploy/.env`; one-off browser install inside the web container: `npx playwright install --with-deps chromium`). Bundle report: `npm run analyze` → `dist-stats/stats.html`.

 ## Old-volume migration (one-off, upgrading from the previous deploy layout)

@@ -48,7 +48,7 @@ go test -p 1 -count=1 ./...

 `-p 1` 是必须的:集成测试共用同一个 PG 库,各自 `DELETE FROM ...` 清表——并行跑会互相删数据导致随机失败。dev 栈起停用 `down`(不是 `rm`),否则匿名 node_modules 卷成孤儿。无 PG/Redis 时依赖它们的测试自动 skip;Redis 挂掉不影响功能(全链路降级为 miss/放行,见 spec §9)。

-前端门槛:`cd frontend && npm run check`(tsc + vitest + vite build)。
+前端门槛:`cd frontend && npm run check`(tsc + eslint + prettier + vitest + vite build)。e2e 是独立的手动发布门禁,针对 dev 栈运行:`cd frontend && npm run e2e`(需 `E2E_ADMIN_USER`/`E2E_ADMIN_PASSWORD`,或 source `deploy/.env`;浏览器一次性安装于 web 容器内:`npx playwright install --with-deps chromium`)。体积报告:`npm run analyze` → `dist-stats/stats.html`。

 ## 旧卷迁移(一次性,升级自上一版部署)

@@ -0,0 +1,59 @@
+# 前端 bundle 审视（2026-09） / Frontend bundle review
+
+> 由 `cd frontend && npm run analyze` 生成 `dist-stats/stats.html` 后人工审视得出；本期只记录结论，不实施优化（spec ④ S4）。
+> Generated from `dist-stats/stats.html` (`npm run analyze`); findings only — no optimization in this batch (spec ④ S4).
+
+## 现状 / Current state
+
+实测基线（`frontend/dist/`，rollup/rolldown 构建产物）：总计约 2.6 MB（assets 2,609,869 B；`du -sh` 显示 2.6M，含 PWA precache 全部条目）。每 chunk 构成如下。**注意两套口径**：chunk 级 `stat` 为 minified 实测产物大小（与 `ls dist/assets` 一致）；`备注` 列中的依赖级数字为**源码级（未压缩，rollup `renderedLength`）口径**，仅用于依赖之间的相对占比，**不可与 stat/minified 字节数相加或比对**。gzip/brotli 来自 visualizer 输出；总注：gzip 列为 visualizer 容器口径，与宿主机 `gzip -c | wc -c` 在多个文件上存在 ≤2% 的小数位差异（如 index 145.3 vs 143.8 kB、TextReader 27.0 vs 26.7 kB），属统计口径差异。
+
+Measured baseline (`frontend/dist/`): ~2.6 MB total (assets 2,609,869 B; `du -sh` 2.6M). Composition per chunk below. **Two calibers apply**: chunk-level `stat` is the measured minified artifact size (matches `ls dist/assets`); dependency-level figures in the `notes` column are **source-level (uncompressed rollup `renderedLength`)** and are only for relative shares among dependencies — **they must not be summed with or compared against stat/minified byte counts**. gzip/brotli come from the visualizer output; note: the gzip column uses the visualizer's in-container figure, which differs from host-side `gzip -c | wc -c` by ≤2% on several files (e.g. index 145.3 vs 143.8 kB, TextReader 27.0 vs 26.7 kB) — a statistics-caliber difference.
+
+| chunk | 入口/来源 | stat | gzip | brotli | 备注 |
+| --- | --- | --- | --- | --- | --- |
+| `index-CGr3zft8.js` | 主入口（`src/main.tsx`，shelf/login/admin + react-dom/router/query/radix） | 462.6 kB | 145.3 kB | 122.3 kB | 依赖级（源码级口径，相对占比）：react-dom 459.8 + react-router 94.9 + tailwind-merge 56 + radix-ui 各子包共 ~131 + lucide-react(34 个图标) 17.3（gzip 10.1）+ (src) 83.9 kB |
+| `pdf.worker-C0DQFlrB.js` | `PdfReader.tsx` worker（`pdfjs-dist/build/pdf.worker.mjs`，Vite worker 语法独立产物） | 1,189.3 kB | 367.0 kB | ~ | 独立文件，不进 index 主包 |
+| `PdfReader-Bv6vuw8i.js` | `pages/Reader.tsx` → `lazy(() => import(...))` | 434.4 kB | 130.5 kB | 137.9 kB | pdfjs-dist 主库 764.3 kB（源码级口径，本 chunk 最大依赖；brotli 135.4 kB） |
+| `src-BNcXNGhn.js` | 共享 chunk：EpubReader 的 `await import("epubjs")` 链 | 345.4 kB | 103.6 kB | 135.5 kB | 依赖级（源码级口径）：epubjs 229.0 + jszip 205.6 + @xmldom/xmldom 97.9 + localforage 65.2 kB + marks-pane/path-webpack/lodash 等 |
+| `TextReader-CmvYmFNB.js` | `lazy()`（txt 与 md 共用） | 79.3 kB | 27.0 kB | 30.1 kB | 依赖级（源码级口径）：marked 53.7 + dompurify 59.7 kB（gzip 14.2/14.5 kB） |
+| `CbzReader-BEFlX6jt.js` | `lazy()` | 12.6 kB | 5.1 kB | 6.2 kB | 仅 (src) 21.1 kB（源码级口径）里的渲染逻辑，jszip 共享 chunk 已含 |
+| `useProgress-BHPrULZV.js` | `lib/useProgress`（多 reader 共享） | 7.0 kB | 2.8 kB | 4.7 kB | |
+| `EpubReader-BIpid_pd.js` | `lazy()` | 3.1 kB | 1.5 kB | 1.5 kB | 仅薄壳；epubjs 全链在 `src-BNcXNGhn.js` |
+| `workbox-window.prod.es5-Bd17z0YL.js` | vite-plugin-pwa（registerSW） | 5.7 kB | 2.2 kB | 2.3 kB | |
+| `rolldown-runtime-Dd_uD5pT.js` | 运行时 | 1.1 kB | ~0.9 kB | 0.8 kB | index.html 里 `<link rel="modulepreload">` |
+| `index-C4Rgqjhl.css` | Tailwind v4 产物 | 69.4 kB | 12.1 kB | ~ | |
+
+- 五个阅读器（cbz/txt/md/pdf/epub）均已通过 `pages/Reader.tsx` 的 `lazy()` 按需加载：是（实测确认——`dist/assets` 有 Cbz/Pdf/Text/Epub 四个独立 reader chunk；txt/md 共用 TextReader 一个 chunk；pdf 另有独立 pdf.worker 文件）。
+  Yes (verified): `dist/assets` contains separate chunks for Cbz/Pdf/Text/Epub readers; txt and md share the TextReader chunk; pdf additionally has a separate pdf.worker file.
+- PWA precache（`workbox.globPatterns`）当前包含哪些大文件：generateSW 报告 "precache 15 entries (2549.92 KiB)"，实测把全部 11 个 JS/CSS 都打进 precache，15 条 = 11 JS/CSS + index.html + icon.svg×2（icon.svg 在清单中出现两次）+ manifest.webmanifest；其中最大的五个：`pdf.worker` 1,189.3 kB、`index` 主包 462.6 kB、`PdfReader` 434.4 kB、`src-BNcXNGhn.js`（epubjs 链）345.4 kB、`TextReader` 79.3 kB。`maximumFileSizeToCacheInBytes` 是 generateSW 构建配置项（`vite.config.ts` 未设置，走默认 2 MiB），非 `sw.js` 内字段——默认值下 1.19 MB 的 pdf.worker 未被排除、仍在 precache 内。
+  The precache (reported as "15 entries, 2549.92 KiB") includes all 11 JS/CSS files; the 15 entries = 11 JS/CSS + index.html + icon.svg×2 (icon.svg appears twice in the manifest) + manifest.webmanifest; the five largest are pdf.worker 1,189.3 kB, index 462.6 kB, PdfReader 434.4 kB, src-BNcXNGhn.js (epubjs chain) 345.4 kB, TextReader 79.3 kB. `maximumFileSizeToCacheInBytes` is a generateSW build-time option (not set in `vite.config.ts`, so the default 2 MiB applies), not a field inside `sw.js` — under the default, the 1.19 MB pdf.worker is not excluded and stays in the precache.
+
+## 可优化点 / Optimization backlog
+
+| # | 问题 | 证据（chunk/体积） | 建议动作 | 归属 |
+| --- | --- | --- | --- | --- |
+| 1 | PWA precache 把全站 JS 全量缓存：pdf.worker(1.19 MB)+PdfReader(434 kB)+epubjs 链(345 kB)+TextReader(79 kB) 均在首装/首启 precache 清单，未打开对应阅读器的用户也要下载这 ~2.05 MB | sw.js precache 15 entries（11 JS/CSS + html + icon.svg×2 + webmanifest，2,549.92 KiB）；globPatterns `**/*.{js,css,html,svg,woff2}` 未排除 | 首装 precache 仅保留 index/css/主包，reader chunk 改 runtime caching 或自定义 precache 过滤 | 后续 spec |
+| 2 | epubjs 依赖链以单体共享 chunk `src-BNcXNGhn.js`(345.4 kB) 存在，体积大且被 precache 全量缓存（见 #1）：虽然拆分本身是正确的——实测该 chunk 仅被 `EpubReader-*.js` 动态 import 引用，index 主包无静态引用、无 modulepreload，首屏不加载——但打开 epub 书需一次性下载 345.4 kB（gzip 103.6 kB），且单 chunk 无法按 epubjs/jszip 细分 | `src-BNcXNGhn.js` 345.4 kB：epubjs 229.0 + jszip 205.6 + @xmldom/xmldom 97.9 + localforage 65.2 kB（依赖级，源码级口径）；`grep import` 确认仅 EpubReader 动态引用 | 与 #1 的 offline 策略一并处理：reader chunk 改 runtime caching 后，此 chunk 仅在用户真正打开 epub 时下载；或评估 `advancedChunks` 按 epubjs/jszip 拆小 chunk 提升缓存粒度 | 后续 spec |
+| 3 | react-dom 459.8 kB（gzip 87.1 kB）是 index 主包内最大的单一依赖（依赖级，源码级口径），无 vendor 拆分；brotli 后 71.4 kB 仍是首屏最大单块 | index chunk rendered 明细：react-dom 459.8 kB / react-router 94.9 kB / query-core 64.2 kB | 评估 `build.rollupOptions.output.manualChunks`（或 vite advancedChunks）拆 vendor，提升缓存命中（业务代码改动不会使 react-dom 失效） | 后续 spec |
+| 4 | `lucide-react` 34 个按需 import 的图标最终以完整组件体形式进 index（17.3 kB stat / gzip 10.1 kB——压缩比 ~59%、节省 ~41%，低于典型 JS 的 ~70% 节省水平，可能与 treeshake 不足有关，需进一步确认）；且每个 reader chunk 各自带少量 lucide 模块（CbzReader 1.0 kB、PdfReader 0.7 kB、useProgress 2.8 kB）导致重复 | index 内 lucide-react rendered=17.3 kB(gzip 10.1 kB) mods=34；各 reader chunk 再零散重复 | 核查 treeshake 行为（rolldown 下 `lucide-react` named import 是否保留死代码）；必要时统一走本仓库 `components/icons.tsx` 自绘 SVG | 后续 spec |
+| 5 | radix-ui 单包多模块：`radix-ui` 包内 Select/Menu/Dialog/DropdownMenu/AlertDialog 等 ~29 个子模块共 ~131 kB（其中 react-select 43.0 kB、react-menu 22.1 kB；另有 radix 的定位依赖 floating-ui 46.5 kB，独立包）进 index 主包 | index chunk 内 @radix-ui/* 合计 rendered ≈ 131 kB（gzip ≈ 30 kB，依赖级口径） | 非首屏必需的 Select/DropdownMenu 所在页面（如 Shelf 筛选、admin 页）可评估下沉到对应 route chunk；仅在使用处再 import | 后续 spec |
+| 6 | marked+dompurify 只被 TextReader(md 格式) 用，却进了 txt 也复用的 TextReader chunk——纯 txt 用户也下载这两个库（依赖级合计 ~113 kB，源码级口径） | `TextReader-CmvYmFNB.js` 79.3 kB 内 marked 53.7 + dompurify 59.7 kB（依赖级，源码级口径） | md 渲染再拆一层：TextReader 内对 md 分支用 `await import("marked")`/`await import("dompurify")`，txt 分支零依赖 | 后续 spec |
+
+## 结论 / Verdict
+
+当前总体体积（首屏 gzip 约 145 kB + CSS 12 kB）对个人书库场景可以接受，五阅读器 lazy 拆分也确实生效（epubjs 链仅被 EpubReader 动态 import，首屏不加载），pdf.worker 已是独立文件不进主包。最优先的两项是 #1（precache 全量缓存 2.05 MB reader 代码，与 spec 的离线策略直接冲突）和 #2（epubjs 链 345 kB 单体 chunk 被 precache 全量缓存，与 #1 同根），建议在下一个 spec 批次（S5 之后的优化轮）落地；#3–#6 属于收尾打磨，可与 #1 同期或更晚处理。
+
+Total size is acceptable for a personal library (first-load gzip ≈145 kB + 12 kB CSS), and all five readers are properly split via `lazy()` (the epubjs chain is only dynamically imported by EpubReader and never loads on first paint), with pdf.worker already a standalone file. The two top priorities are #1 (precache ships ~2.05 MB of reader code users may never open — conflicts with the offline spec) and #2 (the 345 kB monolithic epubjs-chain chunk is fully precached, same root cause as #1); both belong to the next optimization round after S5. Items #3–#6 are polish that can land together with #1 or later.
+
+---
+
+### 实测数据来源 / Measurement provenance
+
+- `npm run analyze`（容器内 vite build + rollup-plugin-visualizer 7.1.1，gzip/brotli 选项开启）→ `frontend/dist-stats/stats.html`；chunk/依赖级 stat、gzip、brotli 数值用 node 脚本从 stats.html 内嵌 `nodeParts`/`nodeMetas` JSON 提取（`nodeParts[uid] = {renderedLength, gzipLength, brotliLength}`，`nodeMetas[uid].moduleParts` 给出模块归属 chunk）。
+- 产物文件级数值：`ls -la frontend/dist/assets/`（与 stats.html 的 chunk 级 stat/minified 大小一致；依赖级 `renderedLength` 是另一套源码级口径，见上）。
+- gzip 交叉核对：宿主机 `gzip -c <file> | wc -c`（index 143,763 / PdfReader 128,873 / src-BNcXNGhn 102,696 / TextReader 26,677 / pdf.worker 366,988 / CbzReader 5,061 / EpubReader 1,500 / useProgress 2,778 / index.css 12,113 字节——与 visualizer 值存在 ≤2% 小数位差异，见现状节总注）。
+- precache：`grep url:"..." frontend/dist/sw.js` 列出 15 条目（11 个 JS/CSS + index.html + icon.svg×2 + manifest.webmanifest）+ 容器内 build 输出 "precache 15 entries (2549.92 KiB)"。
+- dist 总计：`du -sh frontend/dist/` = 2.6M；assets 目录 `du -b` 求和 2,609,869 字节。
+- `Reader.tsx` lazy() 现状与 `dist/assets` 中四 reader chunk + pdf.worker 独立文件直接核对。
+
+Provenance: values come from (a) the JSON embedded in `dist-stats/stats.html` produced by `npm run analyze` (rollup-plugin-visualizer 7.1.1 with gzip+brotli), extracted with a node script over `nodeParts`/`nodeMetas`; (b) `ls -la frontend/dist/assets/`; (c) host-side `gzip -c | wc -c` cross-checks; (d) `sw.js` precache URL list and the build log line "precache 15 entries (2549.92 KiB)"; (e) `du -sh frontend/dist` (2.6M) and per-file `du -b` sum (2,609,869 B); (f) direct comparison of `Reader.tsx` `lazy()` sources with the four reader chunks and the standalone pdf.worker file in `dist/assets`.
@@ -0,0 +1 @@
+legacy-peer-deps=true
@@ -0,0 +1,24 @@
+import { expect, test } from "@playwright/test";
+import { creds } from "./helpers/api";
+
+test("admin：建库 → 触发扫描（冒烟）", async ({ page }) => {
+  const { user, pass } = creds();
+  const libName = `e2e-admin-${Date.now()}`;
+
+  await page.goto("/login");
+  await page.fill("#login-user", user);
+  await page.fill("#login-pass", pass);
+  await page.getByRole("button", { name: "登录", exact: true }).click();
+  await expect(page).toHaveURL(/\/$/);
+
+  await page.goto("/admin/libraries");
+  await page.getByPlaceholder(/库名/).fill(libName);
+  await page.getByRole("button", { name: "建库" }).click();
+  await expect(page.getByText(`库「${libName}」已创建`)).toBeVisible();
+  // name cell 加 exact:路径 cell(服务端目录 /data/books/<库名>)的名称也含库名,子串匹配会 strict 双命中。
+  await expect(page.getByRole("cell", { name: libName, exact: true })).toBeVisible();
+
+  const row = page.getByRole("row", { name: new RegExp(libName) });
+  await row.getByRole("button", { name: /扫描/ }).click();
+  await expect(page.getByText("扫描已触发")).toBeVisible();
+});
@@ -0,0 +1,68 @@
+import { expect, test, type APIRequestContext } from "@playwright/test";
+import { adminApi, creds, ensureSampleBook } from "./helpers/api";
+import { scanA11y } from "./helpers/axe";
+
+let admin: APIRequestContext;
+let bookId: number;
+let title: string;
+
+test.beforeAll(async () => {
+  admin = await adminApi();
+  bookId = await ensureSampleBook(admin, "e2e");
+  // 标题以 API 实况为准:后端 titleOf 可能改写文件名(下划线→空格等),书架卡按真实标题找。
+  title = ((await (await admin.get(`/api/books/${bookId}`)).json()) as { title: string }).title;
+});
+
+test.afterAll(async () => {
+  await admin?.dispose();
+});
+
+test("登录 → 书架 → CBZ 阅读翻页 → 书签 → 退出", async ({ page }) => {
+  const { user, pass } = creds();
+
+  // 登录页 + axe
+  await page.goto("/login");
+  await scanA11y(page, "login");
+  await page.fill("#login-user", user);
+  await page.fill("#login-pass", pass);
+  await page.getByRole("button", { name: "登录", exact: true }).click();
+  await expect(page).toHaveURL(/\/$/);
+
+  // 书架 + axe;样本卡可见并点进阅读器。
+  // 卡片用「结构 + 文本」定位:可访问名匹配会同时命中卡片的《…》操作菜单钮(含书名 aria-label)。
+  const card = page.locator(".group > button", { hasText: title });
+  await expect(card).toBeVisible();
+  await scanA11y(page, "shelf");
+  await card.click();
+  await expect(page).toHaveURL(new RegExp(`/book/${bookId}$`));
+
+  // 阅读器(chrome 默认展开)+ axe
+  const reader = page.getByLabel("漫画阅读器,点按左右两侧翻屏,点按中间显示工具栏");
+  await expect(reader).toBeVisible();
+  await expect(page.getByText("1/3")).toBeVisible();
+  await scanA11y(page, "reader-chrome");
+
+  // 右缘点击翻屏 → 页码前进。
+  // 单次 scrollBy 一屏未必把视口中心推过第 1 页底(页高 > 一屏),故按实况重试点击直到 2/3。
+  const box = await reader.boundingBox();
+  if (!box) throw new Error("阅读器容器无 boundingBox");
+  await expect(async () => {
+    await page.mouse.click(box.x + box.width * 0.9, box.y + box.height / 2);
+    await expect(page.getByText("2/3")).toBeVisible();
+  }).toPass({ timeout: 20_000 });
+
+  // 导航抽屉(本 fixture 无内嵌目录,抽屉直接落在书签面板)→ 加书签 → toast
+  await page.getByRole("button", { name: "导航", exact: true }).click();
+  const nav = page.locator("#reader-nav");
+  await expect(nav).toBeVisible();
+  await nav.getByRole("button", { name: "加书签" }).click();
+  await expect(page.getByText("已加书签")).toBeVisible();
+  await page.getByRole("button", { name: "关闭导航" }).click();
+
+  // 回书架 → 退出登录
+  await page.getByRole("link", { name: "书架" }).click();
+  await expect(page).toHaveURL(/\/$/);
+  await page.getByRole("button", { name: new RegExp(`账户 ${user}`) }).click();
+  await page.getByText("退出登录").click();
+  await expect(page).toHaveURL(/\/login/);
+});
@@ -12,16 +12,34 @@ interface Waiver {
 * 仅允许「属于将被 ② 阅读器改版重写的旧 chrome」的问题进这里，reason 必须写明归属。
 * 例：{ page: "reader-chrome", rule: "color-contrast", reason: "旧 rd-* chrome 配色，② 迁移 shadcn token 后移除本豁免" }
 */
-const WAIVERS: Waiver[] = [];
+const WAIVERS: Waiver[] = [
+  {
+    page: "reader-chrome",
+    rule: "color-contrast",
+    reason:
+      "旧 chrome:Reader.tsx 头栏(书架返回钮/书名/库名/进度)用 stone-* 配色,对比不足;② 阅读器改版迁移 shadcn token 后移除本豁免",
+  },
+];

 export async function scanA11y(page: Page, name: string): Promise<void> {
+  // 等 CSS 动画/过渡收尾(如 fx-rise 入场淡入)再扫:动画途中采样会因不透明度混色造成 contrast 误报;2s 上限兜底长动画
+  await page.evaluate(() =>
+    Promise.race([
+      Promise.allSettled(document.getAnimations().map((a) => a.finished)),
+      new Promise((r) => setTimeout(r, 2000)),
+    ]),
+  );
  const results = await new AxeBuilder({ page }).withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"]).analyze();

  if (results.violations.length > 0) {
    console.log(
      `[axe:${name}]`,
      JSON.stringify(
-        results.violations.map((v) => ({ id: v.id, impact: v.impact, nodes: v.nodes.length })),
+        results.violations.map((v) => ({
+          id: v.id,
+          impact: v.impact,
+          nodes: v.nodes.map((n) => n.target.join(" ")),
+        })),
        null,
        2,
      ),
@@ -43,6 +43,7 @@
        "eslint-plugin-react-hooks": "^7.1.1",
        "jsdom": "^30.0.1",
        "prettier": "^3.9.6",
+        "rollup-plugin-visualizer": "^7.1.1",
        "tailwindcss": "^4.3.3",
        "typescript": "npm:@typescript/typescript6@^6.0.2",
        "typescript-eslint": "^8.70.0",
@@ -6361,6 +6362,22 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/bundle-name": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/bundle-name/-/bundle-name-4.1.0.tgz",
+      "integrity": "sha512-tjwM5exMg6BGRI+kNmTntNsvdZS1X8BFYS6tnJ2hdH0kVxM6/eVZ2xy+FqStSWvYmtfFMDLIxurorHwDKfDz5Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "run-applescript": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/cacheable": {
      "version": "2.5.0",
      "resolved": "https://registry.npmjs.org/cacheable/-/cacheable-2.5.0.tgz",
@@ -6468,6 +6485,46 @@
        "url": "https://polar.sh/cva"
      }
    },
+    "node_modules/cliui": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-9.0.1.tgz",
+      "integrity": "sha512-k7ndgKhwoQveBL+/1tqGJYNz097I7WOvwbmmU2AR5+magtbjPWQTS1C5vzGkBC8Ym8UWRzfKUzUUqFLypY4Q+w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^7.2.0",
+        "strip-ansi": "^7.1.0",
+        "wrap-ansi": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/cliui/node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
+      "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/cliui/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/clsx": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
@@ -6756,6 +6813,36 @@
        "node": ">=0.10.0"
      }
    },
+    "node_modules/default-browser": {
+      "version": "5.5.1",
+      "resolved": "https://registry.npmjs.org/default-browser/-/default-browser-5.5.1.tgz",
+      "integrity": "sha512-m1pAzaJgZ/gssEqlOhJkPJp8Xly7QyW6xcrkUa2KKcDeDSEMP7X8xipU3snUcfisTQx0w1AGae+9UtJSfVnXGw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bundle-name": "^4.1.0",
+        "default-browser-id": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/default-browser-id": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/default-browser-id/-/default-browser-id-5.0.1.tgz",
+      "integrity": "sha512-x1VCxdX4t+8wVfd1so/9w+vQ4vx7lKd2Qp5tDRutErwmR85OgmfX7RlLRMWafRMY7hbEiXIbudNrjOAPa/hL8Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/define-data-property": {
      "version": "1.1.4",
      "resolved": "https://registry.npmjs.org/define-data-property/-/define-data-property-1.1.4.tgz",
@@ -6774,6 +6861,19 @@
        "url": "https://github.com/sponsors/ljharb"
      }
    },
+    "node_modules/define-lazy-prop": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/define-lazy-prop/-/define-lazy-prop-3.0.0.tgz",
+      "integrity": "sha512-N+MeXYoqr3pOgn8xfyRPREN7gHakLYjhsHhWGT3fWAiL4IkAt0iDw14QiiEm2bE30c5XX5q0FtAA3CK5f9/BUg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/define-properties": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/define-properties/-/define-properties-1.2.1.tgz",
@@ -7777,6 +7877,29 @@
        "node": ">=6.9.0"
      }
    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
+    "node_modules/get-east-asian-width": {
+      "version": "1.6.0",
+      "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.6.0.tgz",
+      "integrity": "sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/get-intrinsic": {
      "version": "1.3.0",
      "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz",
@@ -8258,6 +8381,22 @@
        "url": "https://github.com/sponsors/ljharb"
      }
    },
+    "node_modules/is-docker": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-3.0.0.tgz",
+      "integrity": "sha512-eljcgEDlEns/7AXFosB5K/2nCM4P7FQPkGc/DWLy5rmFEWvZayGrik1d9/QIY5nJ4f9YsVvBkA6kJpHn9rISdQ==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/is-document.all": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/is-document.all/-/is-document.all-1.0.0.tgz",
@@ -8333,6 +8472,38 @@
        "node": ">=0.10.0"
      }
    },
+    "node_modules/is-in-ssh": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/is-in-ssh/-/is-in-ssh-1.0.0.tgz",
+      "integrity": "sha512-jYa6Q9rH90kR1vKB6NM7qqd1mge3Fx4Dhw5TVlK1MUBqhEOuCagrEHMevNuCcbECmXZ0ThXkRm+Ymr51HwEPAw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-inside-container": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/is-inside-container/-/is-inside-container-1.0.0.tgz",
+      "integrity": "sha512-KIYLCCJghfHZxqjYBE7rEy0OBuTd5xCHS7tHVgvCLkx7StIoaxwNW3hCALgEUjFfeRk+MG/Qxmp/vtETEF3tRA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-docker": "^3.0.0"
+      },
+      "bin": {
+        "is-inside-container": "cli.js"
+      },
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/is-map": {
      "version": "2.0.3",
      "resolved": "https://registry.npmjs.org/is-map/-/is-map-2.0.3.tgz",
@@ -8568,6 +8739,22 @@
        "url": "https://github.com/sponsors/ljharb"
      }
    },
+    "node_modules/is-wsl": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-3.1.1.tgz",
+      "integrity": "sha512-e6rvdUCiQCAuumZslxRJWR/Doq4VpPR82kqclvcS0efgt430SlGIk05vdCN58+VrzgtIcfNODjozVielycD4Sw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-inside-container": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/isarray": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
@@ -9400,6 +9587,27 @@
        "node": ">=12.20.0"
      }
    },
+    "node_modules/open": {
+      "version": "11.0.4",
+      "resolved": "https://registry.npmjs.org/open/-/open-11.0.4.tgz",
+      "integrity": "sha512-++Zlftm0kVLPmzC06t6epuWmcRMDbI4z5P3NNX979WA/k23+NtSOynEGzsVfZwguKw2mi5umVgnBlJQMwRz4Pg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "default-browser": "^5.5.1",
+        "define-lazy-prop": "^3.0.0",
+        "is-in-ssh": "^1.0.0",
+        "is-inside-container": "^1.0.0",
+        "powershell-utils": "^0.2.1",
+        "wsl-utils": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/optionator": {
      "version": "0.9.4",
      "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz",
@@ -9655,6 +9863,19 @@
        "node": "^10 || ^12 || >=14"
      }
    },
+    "node_modules/powershell-utils": {
+      "version": "0.2.1",
+      "resolved": "https://registry.npmjs.org/powershell-utils/-/powershell-utils-0.2.1.tgz",
+      "integrity": "sha512-C+y9x90UElAddDZmV4qOx9W53B61PO7cIqWz2dQsWlwswuq4mr8NEwytdGKboYbQlGZ3awrkTeNvcZiZNHnQ8A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/prelude-ls": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/prelude-ls/-/prelude-ls-1.2.1.tgz",
@@ -10200,6 +10421,50 @@
        "fsevents": "~2.3.2"
      }
    },
+    "node_modules/rollup-plugin-visualizer": {
+      "version": "7.1.1",
+      "resolved": "https://registry.npmjs.org/rollup-plugin-visualizer/-/rollup-plugin-visualizer-7.1.1.tgz",
+      "integrity": "sha512-ThaGiHTU8XW02OkK80TrTHATraJmM9OAduU4otal+7gyXLpYEtmGBLfx5kW+EHvvLwn03YGW2NnwKUIqsYlJAA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "open": "^11.0.0",
+        "picomatch": "^4.0.5",
+        "source-map": "^0.8.0",
+        "yargs": "^18.1.0"
+      },
+      "bin": {
+        "rollup-plugin-visualizer": "dist/bin/cli.js"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "rolldown": "1.x || ^1.0.0-beta || ^1.0.0-rc",
+        "rollup": "2.x || 3.x || 4.x"
+      },
+      "peerDependenciesMeta": {
+        "rolldown": {
+          "optional": true
+        },
+        "rollup": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/run-applescript": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/run-applescript/-/run-applescript-7.1.0.tgz",
+      "integrity": "sha512-DPe5pVFaAsinSaV6QjQ6gdiedWDcRCbUuiQfQa2wmWV7+xC9bGulGI8+TdRmoFkAPaBXk8CrAbnlY2ISniJ47Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/safe-array-concat": {
      "version": "1.1.4",
      "resolved": "https://registry.npmjs.org/safe-array-concat/-/safe-array-concat-1.1.4.tgz",
@@ -10582,6 +10847,23 @@
        "safe-buffer": "~5.1.0"
      }
    },
+    "node_modules/string-width": {
+      "version": "8.2.2",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.2.2.tgz",
+      "integrity": "sha512-GaPUh5gfdrYzqeVNZvUfT23vYYxXzKYidUcnMtJg/3rxRV63EFZy3k6xfKlmfeJD0176lnUV/Usr3XcwSvFzpg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.5.0",
+        "strip-ansi": "^7.1.2"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/string.prototype.includes": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/string.prototype.includes/-/string.prototype.includes-2.0.1.tgz",
@@ -10700,6 +10982,35 @@
        "node": ">=4"
      }
    },
+    "node_modules/strip-ansi": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.2.0.tgz",
+      "integrity": "sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^6.2.2"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/strip-ansi/node_modules/ansi-regex": {
+      "version": "6.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.3.0.tgz",
+      "integrity": "sha512-WpDfL7NO6j7tH88IDBNVdUJxDh9nmCteAVW9dsep846XdwF4naCBK+/tGLX3KJgcpgMRXCFlTM2hKGoK9FsdrQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
+      }
+    },
    "node_modules/strip-comments": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/strip-comments/-/strip-comments-2.0.1.tgz",
@@ -12148,6 +12459,92 @@
        "workbox-core": "7.4.1"
      }
    },
+    "node_modules/wrap-ansi": {
+      "version": "9.0.2",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz",
+      "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "string-width": "^7.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
+      "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/wrap-ansi/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/wsl-utils": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/wsl-utils/-/wsl-utils-1.0.0.tgz",
+      "integrity": "sha512-Hl0ZOAs672vg+06kfujwRhoS6/jehvULrlFkuF2dRu6pHgA8U06h3xqNIqNNU1LTXPcedxByAR4GS6pwQK0mgA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-wsl": "^3.1.0",
+        "powershell-utils": "^0.1.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/wsl-utils/node_modules/powershell-utils": {
+      "version": "0.1.0",
+      "resolved": "https://registry.npmjs.org/powershell-utils/-/powershell-utils-0.1.0.tgz",
+      "integrity": "sha512-dM0jVuXJPsDN6DvRpea484tCUaMiXWjuCn++HGTqUWzGDjv5tZkEZldAJ/UMlqRYGFrD/etByo4/xOuC/snX2A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
    "node_modules/xml-name-validator": {
      "version": "5.0.0",
      "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz",
@@ -12165,6 +12562,16 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
    "node_modules/yallist": {
      "version": "3.1.1",
      "resolved": "https://registry.npmjs.org/yallist/-/yallist-3.1.1.tgz",
@@ -12172,6 +12579,34 @@
      "dev": true,
      "license": "ISC"
    },
+    "node_modules/yargs": {
+      "version": "18.1.0",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-18.1.0.tgz",
+      "integrity": "sha512-2rAgRKu54VsHkqI0/tYkmluGXHD4KW7yZoycuqDQ15QOTnc2VVfy0nN/1eMhnQLO00A+dwtK20xuCnc1YGeUyg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^9.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "string-width": "^8.2.1",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^22.0.0"
+      },
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "22.0.0",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-22.0.0.tgz",
+      "integrity": "sha512-rwu/ClNdSMpkSrUb+d6BRsSkLUq1fmfsY6TOpYzTwvwkg1/NRG85KBy3kq++A8LKQwX6lsu+aWad+2khvuXrqw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "^20.19.0 || ^22.12.0 || >=23"
+      }
+    },
    "node_modules/yocto-queue": {
      "version": "0.1.0",
      "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
@@ -9,6 +9,7 @@
    "e2e": "playwright test",
    "e2e:ui": "playwright test --ui",
    "build": "tsc --noEmit && vite build",
+    "analyze": "ANALYZE=1 vite build",
    "preview": "vite preview",
    "check": "tsc --noEmit && eslint . && prettier --check . && vitest run && vite build",
    "lint": "eslint .",
@@ -56,6 +57,7 @@
    "eslint-plugin-react-hooks": "^7.1.1",
    "jsdom": "^30.0.1",
    "prettier": "^3.9.6",
+    "rollup-plugin-visualizer": "^7.1.1",
    "tailwindcss": "^4.3.3",
    "typescript": "npm:@typescript/typescript6@^6.0.2",
    "typescript-eslint": "^8.70.0",
@@ -16,7 +16,7 @@
  --secondary: oklch(0.95 0.003 80);
  --secondary-foreground: oklch(0.32 0.01 70);
  --muted: oklch(0.95 0.003 80);
-  --muted-foreground: oklch(0.55 0.008 70);
+  --muted-foreground: oklch(0.52 0.008 70);
  --accent: oklch(0.68 0.16 46);
  --accent-strong: oklch(0.55 0.17 46);
  --accent-foreground: oklch(0.985 0.002 80);
@@ -312,6 +312,8 @@ export default function CbzReader({ book, initialLocator, initialPercent, chrome
    >
      <div
        ref={attachBox}
+        // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex -- 滚动容器须可聚焦(axe scrollable-region-focusable,键盘滚动可达);div 无交互语义属滚动区可聚焦的通行做法
+        tabIndex={0}
        onScroll={onScroll}
        onClick={onZoneClick}
        onPointerDown={(e) => {
@@ -2,6 +2,7 @@ import react from "@vitejs/plugin-react";
 import { VitePWA } from "vite-plugin-pwa";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
+import { visualizer } from "rollup-plugin-visualizer";

 export default defineConfig({
  resolve: { alias: { "@": "/src" } },
@@ -46,6 +47,10 @@ export default defineConfig({
        ],
      },
    }),
+    // npm run analyze：体积报告输出到 dist-stats/（git-ignore，不进发布产物）
+    ...(process.env.ANALYZE
+      ? [visualizer({ filename: "dist-stats/stats.html", gzipSize: true, brotliSize: true })]
+      : []),
  ],
  server: { proxy: { "/api": process.env.VITE_PROXY_TARGET ?? "http://localhost:8080" } },
 });
Author	SHA1	Message	Date
XingfenD	2fccf3f2b3	docs: record TS side-by-side + legacy-peer-deps conventions (AGENTS.md + .npmrc) CI / frontend (push) Canceled after 0s Details CI / backend (push) Canceled after 0s Details	2026-09-16 11:43:21 +08:00
XingfenD	caacaf9c30	docs: changelog for component testing + bundle review (B4 done, spec ④ complete)	2026-09-16 11:28:12 +08:00
XingfenD	5ba522753a	docs: README frontend gates (lint/e2e/analyze), bilingual	2026-09-16 11:21:35 +08:00
XingfenD	8f4c34c949	docs: bundle-review — align dependency sizes to source-level caliber, rewrite epubjs finding	2026-09-16 11:18:44 +08:00
XingfenD	0bf8129f6e	docs: bundle review findings (B4)	2026-09-16 11:06:58 +08:00
XingfenD	f5c33f538e	chore(frontend): bundle analyzer via npm run analyze (B4)	2026-09-16 11:00:22 +08:00
XingfenD	cd02a88b59	ci(e2e): render configs from templates before compose up	2026-09-16 10:56:47 +08:00
XingfenD	4ba55fcf2a	ci: e2e workflow (workflow_dispatch) + changelog (B3 done)	2026-09-16 10:53:23 +08:00
XingfenD	f2f06a516b	test(frontend): e2e admin smoke (create library + scan)	2026-09-16 10:48:23 +08:00
XingfenD	9c6339d35e	test(frontend): e2e main flow (login→shelf→cbz→bookmark→logout) + axe scans	2026-09-15 17:29:20 +08:00