diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
new file mode 100644
index 0000000..35bf485
--- /dev/null
+++ b/.github/workflows/pages.yml
@@ -0,0 +1,47 @@
+# 把介绍页与纯内存演示页（make dist 生成的 dist/index.html、dist/demo.html）发布到 GitHub Pages。
+# 演示页不连后端，评论数据只存在访问者浏览器内存里。
+# 首次使用需在仓库 Settings → Pages 把 Source 设为「GitHub Actions」。
+name: Pages
+
+on:
+  push:
+    branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - run: npm ci
+
+      - run: make dist
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/AGENTS.md b/AGENTS.md
index fc4d113..6823d0a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,6 +2,84 @@
 
 面向 AI agent 的项目约定。与 `CLAUDE.md`（通用编码行为准则）配合使用。
 
+## 笔记功能设计约定
+
+以下是用户确认的目标设计，后续实现、接口对接和 UI 文案应遵循。阅读器一侧已按此实现；数据由宿主 talebook 通过 `annotation_callbacks` 提供，阅读器不直接调用 BRS 或任何评论、账号接口（契约见 `README.md`）。
+
+### 统一模型
+
+- 划线、文字笔记和整书评论统一属于「笔记」，不能再作为相互独立的数据和产品体系设计。
+- 每条笔记至少包含：类型、笔记内容、公开范围，以及必要的作者、书籍和位置关联信息。
+- 类型包括「划线」「文字」「整书评论」。「段落评论」「章节评论」「本书评论」是查看范围，不是额外的笔记类型；「整书评论」类型表示针对整本书撰写的笔记。
+- 公开范围区分私密与公开。私密笔记仅作者可查看；公开笔记可以被其他读者查看。
+- 新建文字笔记和整书评论在没有已保存偏好时默认公开。用户可以修改公开范围，并持久记忆最近一次选择，后续新建时沿用，刷新页面或重新打开阅读器后仍应保留。
+- 公开范围偏好只影响后续新建笔记，不修改已有记录；创建私密划线不能覆盖文字笔记和整书评论的公开范围偏好。
+- 划线固定为私密笔记，不提供公开划线选项。划线记录应保存所选原文和准确选区，不能要求用户填写文字内容。
+- 文字笔记有用户填写的内容和公开范围；公开的章段文字笔记必须出现在对应的段落、章节和本书查看范围中。保存时标记为公开、却无法从评论面板读到，不符合设计。
+- 宿主回调、评论 API 或本地存储是实现细节，界面中的创建、查询和展示必须遵循同一个笔记模型。仅保存在当前浏览器的数据不能被视为已经向其他读者公开。
+
+### 选区与评论归属
+
+- 单段文字笔记关联所在段落。
+- 允许多段选择后创建文字笔记，不能因跨段选择直接禁用文字笔记功能。
+- 多段文字笔记在章段评论查询、展示时，归属到选区最后一个段落的 CFI；本段评论入口也应使用同一归属规则。
+- 评论归属 CFI 与原始选区范围应分开保存或表达：归属最后一段不意味着丢弃前面选中的文字，也不能改变划线的真实范围。
+- 同一条公开笔记可以出现在多个查看范围中，但仍是同一条记录，不得为段落、章节、全书分别保存副本。
+
+### 入口与功能面板
+
+- 界面中原「笔记」文案统一改为「评论」，总入口为「评论」，创建按钮为「写评论」；划线、文字和整书评论仍使用同一统一模型。
+- 从总入口打开的笔记弹窗默认展示当前章节的所有评论。弹窗顶部提供「查看更多评论」入口，右侧带箭头，点击进入完整评论页面。
+- 评论弹窗采用底部抽屉模式，顶部不显示独立标题栏或 × 关闭按钮，内容顶部直接展示「本章评论」小标题与「查看更多评论 ›」入口；「写评论」按钮放在抽屉底部。
+- 笔记抽屉不额外展示「当前段落」引用区；从段尾气泡进入本段评论时也不展示该区域。编辑笔记时所需的原文引用仍由编辑框承载。
+- 抽屉与完整评论页面都不提供搜索功能。
+- 评论列表采用分页加载，滚动到底部时自动加载下一页；展示加载中、加载失败可重试和没有更多的状态。切换范围或筛选条件时重置分页，加载期间不能重复请求；过期请求不能混入新范围。自己评论优先的排序必须覆盖整个结果集，不能仅对每一页分别排序。
+- 移动端笔记抽屉占底部菜单上方可用阅读区域高度的 90%，贴底部菜单上沿展开，顶部保留 10% 的外部区域用于展示阅读上下文和点击收起。
+- 桌面端采用侧边栏：目录从左侧打开，笔记和设置从右侧打开；侧边栏覆盖在阅读区域上，不将正文改为双栏或压缩正文宽度。不同功能面板互斥，点击侧边栏外收起。原型暂用 850px 作为桌面断点，宽度值不是已确认的产品约定。
+- 阅读中的侧边栏、抽屉以及外部遮罩都必须避开底部菜单；这些面板展开时底部菜单可见、可点击，仍可直接切换目录、评论和设置。独立的完整评论页不保留阅读菜单。
+- 抽屉支持向下拖拽收起，也支持点击抽屉外区域收起。完整评论页面的返回导航与抽屉的收起操作是不同动作。
+- 完整评论页面支持「本章评论」与「全书评论」范围切换，并提供返回笔记弹窗的入口；弹窗承担阅读中的快速查看，完整页面承担更多评论的浏览。
+- 「查看更多评论」进入独立的完整评论页面，不是在抽屉或侧边栏内扩大列表；完整页占满整个内容区域，不保留阅读正文、底部阅读菜单或其他阅读界面元素，支持页面返回导航及浏览器返回。
+- 完整评论页从右侧进入，是独立页面容器和导航状态，不能通过改变原抽屉尺寸模拟新页面；返回时恢复原抽屉查看范围、筛选和滚动位置。
+- 完整评论页不显示独立 titlebar，顶部直接是「本章评论／全书评论」Tab 导航；返回入口融入同一导航行，不另占标题栏。「写评论」与抽屉保持一致，固定放在页面底部。
+- 选区工具栏的「划线」创建私密划线笔记；文字笔记入口打开文字笔记编辑框，编辑框应明确笔记内容和公开范围。
+- 面板支持三个查看范围：「本段评论」「当前章节的所有评论」「本书评论」。范围必须明确显示在面板标题或筛选状态中。
+- 「本段评论」查询归属当前段落的公开笔记；选区工具栏与正文段落评论气泡应进入相同的段落范围。
+- 正文段尾保留评论数量气泡，显示归属本段的公开笔记数量（不计私密划线或私密文字笔记），点击进入该段评论；调整抽屉或桌面侧边栏时不能丢失这个入口。
+- 「当前章节的所有评论」汇总本章的公开笔记，包含本章各段的公开文字笔记，不能仅查询旧接口中 `segment_id=0` 的章节级记录。
+- 本章评论列表直接展示每个人的作者信息和评论内容，不逐条展示所关联的正文引用；笔记编辑框中的原文引用不受影响。
+- 评论列表先列当前用户自己的评论，再列其他人的评论。其他人的条目仅展示名字、时间和评论内容；自己的条目额外提供「修改」按钮，打开该记录的编辑框，不得为其他人的评论提供修改入口。
+- 自己评论的「修改」入口使用文字按钮，紧跟评论正文末尾，与正文自然行内排版，不单独占据底部操作行。
+- 「本书评论」查看这本书的公开笔记，包含各章段的公开笔记和整书评论类型；不能被理解为仅查看「整书评论」类型。
+- 公开笔记的创建入口和查看入口必须互通，不能出现「看本段评论」实际只打开另一套本段笔记数据的情况。
+- 完整评论页的 Tab 为「本章评论／全书评论／我的」。「我的」列出当前用户在本书的全部记录，包含私密划线、私密文字和自己的公开评论；私密记录只在「我的」中出现，不混入「本章评论」「全书评论」等公开范围。游客进入「我的」时引导登录。
+- 整书评论关联到全书最开头的位置（首章起始处），不留空位置；它与其他记录使用同一套位置字段。
+
+- 设置里只有两个相互独立的评论开关：「显示全部划线和评论」（正文划线标记与段尾评论气泡）和「选中文字后显示工具栏」。不再设「启用划线和笔记功能」总开关；关闭任一开关都不删除数据，评论入口始终可用。
+
+### 互动：赞、踩、回复
+
+以下为用户确认的规则。
+
+- 公开评论及其回复都支持赞、踩、回复；阅读器中的单条记录直接展示「赞 N／踩 N／回复 N」操作行，其中赞和踩用图标加数字表示，不显示「赞」「踩」文字（保留无障碍标签）；已投的一项用实心图标和主色区分。游客可浏览，点击操作时引导登录。私密记录不开放他人互动。
+- 赞与踩互斥：重复点击取消，点另一项则替换；每个用户对每个目标只有一个投票。允许给自己的评论投票，也允许回复自己的评论。请求失败时界面恢复到操作前状态。
+- 自己评论的「修改」入口仍紧跟正文末尾，不并入操作行。
+- 详情页中，直接回复主评论的第一层回复不缩进，与主评论左对齐；第二层及之后的回复（回复的回复）统一只缩进一级，归在所属的第一层回复下面，彼此同级排列并显示回复对象。不得出现更深的层级缩进。
+- 回复挂在主评论下，不单独出现在段落、章节、全书的顶层列表中。段尾气泡只统计公开顶层评论，不计投票和回复。
+- 查看回复时进入独立的评论详情页面，评论列表内不展开回复。点击列表中的单条评论（按钮以外的区域）或其「回复 N」都进入详情页；赞、踩、修改、删除等按钮在列表中原地生效，不跳转。详情页结构：顶部是返回入口，正文是主评论及其操作行，下面是回复列表（缩进规则见上），回复输入固定在页面底部。详情页与完整评论页一样占满整个内容区域、从右侧进入，支持页面返回和浏览器返回；返回后恢复原列表（抽屉或完整评论页）的范围、已加载数量和滚动位置，计数与列表保持同步。
+- 删除是真删除，不做软删除，不保留「已删除」占位。删除主评论时，其下全部回复以及相关投票一并删除。
+- 作者可以修改自己的评论和回复；修改后不显示「已编辑」标记。
+- 回复没有独立的公开范围，跟随主评论。公开评论改为私密后，其下已有回复只有该评论作者自己能看到，其他人（包括回复的作者）不可见，也不能再对其投票或回复。
+- 整书评论虽然关联到全书开头，但不出现在首章的「本章评论」中，只出现在「全书评论」和作者的「我的」里。
+- 不迁移旧 BRS 评论数据，升级时直接清空。
+
+尚未确认，实现前需先问用户，不要把临时选择当成已确认的设计：
+
+- 评论详情页中回复的排序与分页方式。当前实现：时间正序，每页 20 条，滚动到底继续加载。
+- 抽屉和完整评论页底部的「写评论」在没有选区时写什么。当前实现：本段范围写该段的文字评论，本章／全书／我的范围写整书评论。
+- 删除第一层回复时，其下第二层及之后的回复是否一并删除。
+- 私密评论重新改回公开后，原有回复和投票是否恢复可见。
+
 ## 提交 PR 前必须跑 e2e 测试
 
 **任何改动在提交 / 推送 PR 之前，必须本地跑通 Playwright e2e 测试。** CI 会跑同一套用例，本地先验证可避免红 CI 来回。
@@ -18,5 +96,5 @@ npm run test:e2e
   E2E_PORT=5009 npm run test:e2e               # 让 Playwright 复用它
   ```
 
-- 全量套件应全部通过（当前 33 passed）。失败用例的现场快照在 `test-results/<用例名>/error-context.md`。
-- 改了底部导航 / 登录 / 评论面板等 UI 时，重点核对 `tests/e2e/{auth,user-center,reader-ui,comments-login}.spec.js`：这些用例按文案（如「评论」「点击登录，发表评论」）定位元素，改文案会连带改测试。
+- 全量套件应全部通过（当前 61 passed）。失败用例的现场快照在 `test-results/<用例名>/error-context.md`。
+- 改了底部导航 / 评论面板等 UI 时，重点核对 `tests/e2e/{comments,annotations,panel-focus,reader-ui}.spec.js`：这些用例按文案（如「评论」「查看更多评论」「写评论」）定位元素，改文案会连带改测试。
diff --git a/CLAUDE.md b/CLAUDE.md
index e92d28f..5621069 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -3,18 +3,20 @@
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 > 提交 / 推送 PR 前必须本地跑通 e2e（见 `AGENTS.md`）。通用编码准则见仓库外层 `~/CLAUDE.md`。
+> 架构、职责边界和宿主回调规范见 `DESIGN.md`，改动前先读；改了其中描述的行为或接口要同步更新它。
 
 ## 这是什么
 
-candle-reader（秉烛夜读）是一个**可嵌入的 EPUB 阅读器**，以 Vue 3 + Vuetify 写成、用 Vite **library 模式**打包，供 talebook 书库服务嵌入使用。它不是独立 SPA：`src/main.js` 导出一个 `Reader` 类，宿主页面 `new Reader('#app', { server, book_url, display_url, themes_css })` 即挂载。
+candle-reader（秉烛夜读）是一个**可嵌入的 EPUB 阅读器**，以 Vue 3 + Vuetify 写成、用 Vite **library 模式**打包，供 talebook 书库服务嵌入使用。它不是独立 SPA：`src/main.js` 导出一个 `Reader` 类，宿主页面 `new Reader('#app', { book_url, display_url, themes_css, book_id, annotation_callbacks })` 即挂载。
 
 ## 常用命令
 
 ```bash
 make dev              # 解压 public/demo/*.epub 后启动 vite（首次开发用这个，不是 npm run dev）
+                      # 演示页 http://localhost:5001/demo.html ：西游记 + 纯内存版宿主，可体验全部评论功能
 npm run dev           # vite dev server，端口 5001
 npm run build         # vite build --lib → dist/candle-reader.es.js（并清理 demo 产物）
-make all              # build + 给 dist/demo.html 资源打时间戳版本号（缓存刷新）
+make dist             # build + 生成 dist/demo.html（同一份演示页，改为引用打包产物并带时间戳版本号）和介绍页 dist/index.html（源文件 intro.html）；make all 等同
 make install          # 把 dist/ 拷进本地 talebook 的 static 目录
 npm run lint          # eslint --fix（standard 风格）
 
@@ -30,20 +32,22 @@ npm run test:e2e:ui                   # 带调试面板
 
 **EPUB 渲染依赖全局 UMD 脚本，不是 npm 依赖。** `index.html` / 测试 harness 里先后引入 `js/jszip-*.js` 和 `js/epub-*.js`，epub.js 靠全局 `window.JSZip` 解压 `.epub`，**JSZip 必须在 epub.js 之前加载**。因此 headless 环境下正文渲染不完整——e2e 刻意不断言 epub 正文/目录渲染（属第三方渲染器行为）。
 
-**所有后端数据走 `$backend`。** `src/plugins/server.js` 注入全局 `this.$backend(url, options)`，对 `server + url` 发 `fetch`（`credentials: 'include'`）。`server` 在构造 `Reader` 时传入。约定返回 `{ err, msg, data }`：`err === 'ok'` 为成功；`err === 'exception'` 会触发全局 alert；`need_login` 类表示游客态。网络失败兜底返回 `{ err: 'network_error', data: {} }`，所以**调用方需对 `rsp.data.*` 做空值兜底**（如列表赋值 `rsp.data.list || []`）。
+**评论数据只走宿主回调，阅读器不直接请求后端。** 划线、文字评论、整书评论、回复、赞踩和登录态都通过构造 `Reader` 时注入的 `annotation_callbacks` 交给宿主（talebook）；契约见 `README.md`。`src/annotations.js` 把回调包成 `annotation_repository`，并在未注入回调时提供 `localStorage` 实现。不要在阅读器里新增对评论服务（BRS）或账号接口的直接请求。
 
-**组件树几乎全在一个文件里。** `CandleReader.vue`（根，仅透传 props）→ `EpubReader.vue`（~1300 行，承载底部导航、epub.js 集成、主题、阅读进度、评论逻辑的「全家桶」组件）。各面板是它的子组件：
-- `Settings.vue` 设置面板、`BookToc.vue` 目录、`Guest.vue` 登录对话框、`UserCenter.vue` 已登录用户中心
-- `BookReview.vue` —— 底部「评论」按钮打开的**本书评论**面板（panel 名为 `more`）。游客态显示「点击登录」入口（emit `login`），已登录显示用户行（emit `open-settings`）
-- `BookComments.vue` —— **章评/段评**面板（panel 名 `comments`），从正文 iframe 选段触发
+**组件树。** `CandleReader.vue`（根，仅透传 props）→ `EpubReader.vue`（承载底部导航、epub.js 集成、主题、阅读进度、选区工具栏、评论编辑框、正文标记与段尾气泡）。子组件：
+- `Settings.vue` 设置面板、`BookToc.vue` 目录、`AudiobookPlayer.vue` 听书
+- `comments/ReaderComments.vue` —— 评论抽屉（panel 名 `annotations`）以及从它进入的完整评论页、评论详情页、删除确认；列表与单条评论分别是 `CommentList.vue`、`CommentItem.vue`。写评论和修改通过事件交回 `EpubReader` 的编辑框。
 
-**面板切换靠 `set_menu(name)`。** 一次只开一个底部面板（`toc`/`settings`/`more`/`comments`/`ai`/`hide`），它会把其余 `menu.panels[*]` 置 false。登录框（`show_login`）和用户中心（`show_user_center`）是独立 overlay，由 `BookReview` 的事件触发，不走 `set_menu`。改动导航文案或入口时，相关 e2e 按可见文案（如「评论」「点击登录，发表评论」）定位元素，务必同步。
+**面板切换靠 `set_menu(name)`。** 一次只开一个底部面板（`toc`/`settings`/`annotations`/`ai`/`hide`），它会把其余 `menu.panels[*]` 置 false。移动端是底部抽屉，≥850px 时目录是左侧侧边栏、评论和设置是右侧侧边栏。完整评论页和详情页是独立的全屏页面，用浏览器历史记录逐层返回，离开评论抽屉时一并退出。打开评论用 `open_comments(scope, paragraph)`。改动导航文案或入口时，相关 e2e 按可见文案（如「评论」「查看更多评论」）定位元素，务必同步。
+
+**演示页。** 根目录 `demo.html` + `demo/memory-host.js`（`annotation_callbacks` 的纯内存参照实现，e2e 的 `mock-host.js` 也基于它）。改了回调契约要同步这两处和 `README.md`。
 
 **主题。** `src/themes.js` + `themes_css`（运行时注入的皮肤 CSS）。图片皮肤需把 color-scheme / 透明背景注入正文 iframe 防白屏，相关回归在 `tests/e2e/reader-theme.spec.js`。顶部状态栏/灵动岛颜色由 `apply_theme_color` 改 `index.html` 里静态声明的 `<meta theme-color>`。
 
 ## 测试架构
 
-后端**全量 mock**，不依赖真实 talebook。
-- 入口用 `tests/e2e/fixtures/reader-harness.html`（复刻 `index.html`，但 `server` 指同源、`book_url` 用体积小的 `/demo/book1.epub`），**不要用 `index.html`**。
-- `helpers/mock-api.js` 的 `setupApiMock(page, overrides)`：默认游客态；未显式 mock 的接口返回安全空响应 `{ err:'ok', data:{} }`（注意：这意味着 `data.list` 等字段会是 `undefined`，需在应用侧兜底）。
-- `helpers/reader.js`：`gotoReader`、以及通过 Vue 内部实例直接调 `EpubReader.set_menu()` 的 `openPanel` / `openCommentsPanel`（避免依赖 iframe 内选段，减少 flaky）；`readState` 读组件响应式数据做断言。
+评论数据由内存版宿主提供，不依赖真实 talebook。
+- 入口用 `tests/e2e/fixtures/reader-harness.html`（复刻 `index.html`，`book_url` 用体积小的 `/demo/book1.epub`），**不要用 `index.html`**。加 `?host=1` 注入内存版宿主 `fixtures/mock-host.js`（完整回调契约，含多位读者、分页、投票、回复；`&guest=1` 为游客，`&extra=N` 追加 N 条评论）；不加时阅读器走 `localStorage`。测试里用 `window.__host` 检查调用记录（`calls`）、制造失败（`fail`）或挂起某次调用（`hold` / `release`）。
+- `helpers/mock-api.js` 的 `setupApiMock(page, overrides)` 只用于仍走 HTTP 的接口（有声书）；它记录的 `calls` 也用来断言阅读器没有请求评论或账号接口。
+- `helpers/reader.js`：`gotoReader`、`gotoHostReader`、`readerProxy`、通过 Vue 内部实例直接调 `EpubReader.set_menu()` 的 `openPanel`（避免依赖 iframe 内选段，减少 flaky）、`readState` 读组件响应式数据做断言。
+- 浮层有展开动画：读几何位置或用键盘操作前，先用 `expect.poll` 等位置稳定、焦点进入浮层。
diff --git a/DESIGN.md b/DESIGN.md
new file mode 100644
index 0000000..1342baf
--- /dev/null
+++ b/DESIGN.md
@@ -0,0 +1,330 @@
+# DESIGN.md
+
+candle-reader（秉烛夜读）的架构设计与对外接口规范。改动阅读器之前先读这份文档；产品交互的细节约定见 `AGENTS.md`，开发命令与测试方式见 `CLAUDE.md`，接入示例见 `README.md`。
+
+本文描述的是**当前实现**。改了这里描述的行为或接口，必须在同一次改动里更新本文。
+
+## 1. 定位
+
+candle-reader 是一个**可嵌入的 EPUB 阅读器组件**，不是独立应用：
+
+- 用 Vue 3 + Vuetify 写成，Vite library 模式打包成 `dist/candle-reader.es.js` / `.umd.js` + `style.css`。
+- 宿主页面（目前是 talebook 的在线阅读页）`new Reader('#app', options)` 挂载，整页都交给阅读器。
+- 阅读器负责「怎么读、怎么交互」；数据「存在哪里、谁能看、怎么同步」全部属于宿主。
+
+一句话边界：**阅读器只认识回调，不认识任何后端。** 评论数据、读者身份、权限、同步通过宿主注入的 `annotation_callbacks` 完成，有声书清单和收听进度通过 `audiobook_callbacks` 完成。阅读器代码里不得出现对任何后端接口（评论服务 BRS、账号、有声书等）的直接请求；唯一由浏览器直接加载的是宿主给出的资源地址（电子书文件、有声书音频）。
+
+## 2. 职责划分
+
+| 能力 | 阅读器负责 | 宿主负责 |
+|---|---|---|
+| 电子书渲染 | 用 epub.js 渲染、翻页、主题、字号行距、阅读进度条 | 提供 `book_url`（解压目录或 `.epub`），保证可访问 |
+| 选中文字 | 选区工具栏、复制、计算 CFI 和段落归属、选区预览 | — |
+| 划线 / 评论的界面 | 抽屉、完整评论页、详情页、编辑框、赞踩按钮、删除确认、分页滚动、空态和错误态 | — |
+| 正文标记 | 把当前读者本章的划线画到正文上，点击划线进入它所在段落的本段评论；有评论的段落只用段尾气泡表示，不铺底色 | 通过 `load` 返回这些记录 |
+| 段尾评论气泡 | 把数量画到对应段落末尾，点击进入本段评论 | 通过 `summary` 返回每段的公开评论数 |
+| 评论存储 | 不存（未注入回调时才退化为本机 `localStorage`） | 唯一权威存储 |
+| 读者身份与登录 | 游客互动时调用 `login`，之后重新取 `user` | 判断登录态、执行登录流程 |
+| 可见性与权限 | 只做界面上的显示（如私密记录不显示赞踩，右下角标「私密」，自己的记录在右下角给出修改、删除） | **服务端强制**：私密不外泄、只能改删自己的、私密记录不接受投票和回复 |
+| 排序与分页 | 透传 `cursor` / `limit`，按返回顺序展示，滚动到底取下一页 | 排序（自己的在前，再按时间倒序，覆盖整个结果集后再分页）、生成游标 |
+| 计数 | 乐观更新赞踩，以宿主返回值为准 | `like_count` / `dislike_count` / `reply_count` / `user_vote` |
+| 回复结构 | 按 `thread_id` 分组、控制缩进 | 根据 `reply_to_id` 推出 `thread_id`、`reply_to_name` |
+| 删除 | 确认框、从界面移除 | 真删除及级联（见 5.4） |
+| 外部同步 | 不感知 | 公开记录同步到 BRS 等外部服务 |
+| 阅读设置、阅读位置、公开范围偏好 | 存在本机 `localStorage`（见 8） | — |
+| 听书 | 播放器界面、正文高亮跟随、本机记住收听位置 | 通过 `audiobook_callbacks` 提供章节清单、时间轴、收听进度（见 6.3） |
+
+判断一个新功能放在哪边时，问两个问题：
+
+1. **离开这个宿主还成立吗？** 换一个宿主（另一个书库、纯本地 demo）也需要的交互逻辑，放阅读器。
+2. **涉及数据归属、身份或权限吗？** 涉及就放宿主，阅读器只通过回调提出请求。
+
+## 3. 嵌入接口
+
+```js
+import { Reader } from './candle-reader.es.js'   // 需先全局加载 jszip 与 epub.js，见 3.2
+
+new Reader('#app', {
+  book_url: '/books/1/',          // 必填。解压后的 EPUB 目录或 .epub 地址
+  display_url: '',                // 首次打开的位置（章节 href 或 CFI）；有本机阅读位置时以本机为准
+  book_id: 1,                     // 书的稳定标识；作为回调上下文和本机存储的隔离键
+  themes_css: '/static/candle-reader/css/themes.css',  // 注入正文 iframe 的主题样式表
+  annotation_callbacks: { ... },  // 评论回调，见 5；不传则使用本机 localStorage
+  audiobook_callbacks: null,      // 有声书回调，见 6.3；不传则不显示「听书」
+  debug: false,
+})
+```
+
+### 3.1 选项
+
+| 选项 | 类型 | 说明 |
+|---|---|---|
+| `book_url` | string | 必填 |
+| `display_url` | string | 无本机阅读位置时的起始位置 |
+| `book_id` | number / string | 回调上下文 `book_id`；缺省时本机存储改用 `book_url` 隔离 |
+| `themes_css` | string | 默认 `theme.css`；须包含 `src/themes.js` 中纯色主题的同名 class 和评论气泡样式 |
+| `annotation_callbacks` | object / null | 见 5 |
+| `audiobook_callbacks` | object / null | 传了才显示「听书」入口 |
+| `debug` | boolean | 在顶栏显示 epub.js 事件名，并在点击处画点，仅调试用 |
+
+`server`、`audiobook_edition_id`、`audiobook_manifest_url` 选项已废弃，传入会被忽略。
+
+### 3.2 宿主页面的要求
+
+- 先加载 `js/jszip-*.js`，再加载 `js/epub-*.js`。epub.js 依赖全局 `window.JSZip` 解压 `.epub`，顺序不能反。
+- 阅读器占满整个页面：它会把 `html, body` 设为 `position: fixed; overflow: hidden`，防止 iOS Safari 整页回弹、地址栏收起导致正文重排。宿主不要在同一页面放需要滚动的其他内容。
+- 页面需要 `<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`；如需顶部状态栏随主题变色，静态声明 `<meta name="theme-color">`。
+- 引入打包产物时给 `candle-reader.es.js` 和 `style.css` 带版本号，避免手机浏览器使用旧缓存（`make dist` 的做法）。
+
+## 4. 内部架构
+
+```
+CandleReader.vue          根组件，只透传 props
+└─ EpubReader.vue         epub.js 集成、底部菜单、面板切换、主题、选区工具栏、
+   │                      评论编辑框、正文标记、段尾气泡、设置的应用与保存
+   ├─ Settings.vue        设置面板
+   ├─ BookToc.vue         目录
+   ├─ AudiobookPlayer.vue 听书
+   └─ comments/
+      ├─ ReaderComments.vue  评论抽屉 + 完整评论页 + 评论详情页 + 删除确认
+      ├─ CommentList.vue     分页列表（滚动到底取下一页、加载/错误/空态）
+      └─ CommentItem.vue     单条记录（作者、时间、正文、修改/删除、赞/踩/回复）
+
+src/annotations.js        把 annotation_callbacks 包装成 annotation_repository；本机 localStorage 实现
+src/audiobook.js          把 audiobook_callbacks 包装成 audiobook_repository
+src/note-settings.js      旧设置迁移
+src/themes.js             主题数据
+demo/memory-host.js       回调契约的纯内存参照实现（演示页与 e2e 共用）
+```
+
+### 4.1 数据流
+
+```
+宿主回调  ←→  annotation_repository（src/annotations.js：补上下文、校验返回形状）
+                 ├─ EpubReader：load / summary / save（划线、写评论、编辑）/ user / login
+                 └─ ReaderComments：list / replies / save（回复）/ remove / vote
+```
+
+- 组件**只**通过 `annotation_repository` 访问数据，不直接调用 `annotation_callbacks`。
+- `ReaderComments` 不自己打开编辑框：写评论和修改通过 `write` / `edit` 事件交回 `EpubReader`，保存成功后由 `EpubReader` 调用 `ReaderComments.apply_saved()` 刷新列表，并通过 `on_comments_changed()` 同步正文标记和段尾气泡。
+- 同一条记录可能同时出现在抽屉、完整页、详情页里（是不同的对象副本）。修改计数或内容时用 `ReaderComments.patch(id, fields)` 同步所有副本。
+
+### 4.2 面板与页面
+
+- **底部面板**：`toc` / `settings` / `annotations`（评论抽屉）/ `ai`，一次只开一个，统一由 `EpubReader.set_menu(name)` 切换，`set_menu('hide')` 全部收起。打开评论请用 `open_comments(scope, paragraph)`，不要直接 `set_menu('annotations')`，否则列表不会按范围加载。
+- **布局**：移动端为底部抽屉（评论抽屉占底部菜单上方区域的 90%）；宽度 ≥ 850px 时目录是左侧侧边栏，评论和设置是右侧侧边栏。都覆盖在正文上，不压缩正文，底部菜单保持可点。侧边栏内侧边缘有胶囊形分隔条（`PanelResizer`，role=separator）：9px 拖拽热区覆盖在面板真实边界上、不占布局，1px 分隔线与边界重合，中间是 8×24 的胶囊；悬停、聚焦、拖动时分隔线和胶囊变为深蓝 `#2563eb`、握持刻度为白色。可拖动或用方向键（每次 16px）调整宽度，双击或 Home 恢复默认；宽度按面板分别记在 localStorage（`candle-reader:panel-widths`），范围 260px 到 min(720px, 窗口宽度 − 360px)。分隔条放在面板浮层外面（浮层内容区会裁掉越过边框的部分），宽屏时侧边栏不锁定焦点，键盘可以移到分隔条上。
+- **独立页面**：完整评论页、评论详情页是全屏 `v-dialog`（class `rc-standalone`，z-index 2600，盖住顶栏和底部菜单）。每进入一层就 `history.pushState({ candle_comments: 层数 })`，返回按钮、Esc、浏览器后退都走 `history.back()`，由 `popstate` 统一退出到对应层数。离开评论抽屉时 `close_pages()` 会一并退回历史记录。
+- **层级**：编辑框、删除确认在独立页面之上（class `rc-above-standalone`，z-index 2700）；Vuetify 给嵌套浮层的层级只比父级高一档，所以这两个值用 class 显式抬高，新增浮层时沿用。
+- **焦点**：面板最终关闭时焦点回到打开它的入口（`panel_trigger`）；从详情页返回时焦点回到列表里那条评论的「回复」按钮。
+
+### 4.3 选中文字与工具栏
+
+- 选中事件**只用 epub.js 的 `rendition.on('selected')`**，不要自己监听 `selectionchange` 另起一套（曾经这样做，在 iOS 上问题更多，已回退）。
+- `on_select_content` 计算：真实选区 `cfi`、所在段落 `paragraph_cfi` 与整段原文、是否跨段（跨段时归属**最后一个段落**）、章节（`find_toc`）。
+- 工具栏位置：默认放在选区上方；触屏设备（`pointer: coarse`）优先放下方，避开 iOS 系统文字菜单。
+- 选区预览（蓝色底色）只在开启「选中文字后显示工具栏」时绘制；`hide_toolbar()` 会一并清掉。
+- 点击正文的判定（`on_click_content`）：
+  - 快速拖选（按下到松开移动超过 8px）、双击选词：按选字处理，不翻页。
+  - 已经选中文字后再点一下：只取消选中、收起工具栏，这一下不翻页。iOS 在 click 之前就会清掉系统选区，所以以 `selection_active`（epub.js 报告过选中）为准，不以点击时读到的选区为准。
+- 开启工具栏时，正文注入 `-webkit-touch-callout: none` 尝试关闭 iOS 系统文字菜单；关闭工具栏时保留系统菜单用于复制。
+- 正文 iframe 里**不拦截** `touchmove`：iOS 拖动选区两端的手柄依赖原生拖动。左右翻页模式下只拦截阅读区域外框（`#main`、顶栏、底部菜单）的拖动。
+
+### 4.4 章节识别
+
+- 章节标识是目录项的 `label`（去首尾空白），作为回调里的 `chapter` 字段。宿主必须原样保存并用它查询，不要自行改写。
+- 目录项都带锚点、多章共用一个正文文件时（如《西游记》），按位置取光标之前最近的一章（`find_toc_in_same_file`）。
+- 正文文件不在目录里时，取文件内第一个标题作为章节名，没有标题则为「正文 N」。
+
+## 5. 评论回调规范（annotation_callbacks）
+
+### 5.1 统一模型
+
+划线、文字评论、整书评论是**同一种记录**（统称「评论」），回复也是记录（带 `root_id`）。「本段 / 本章 / 全书 / 我的」是**查看范围**，不是记录类型；同一条公开记录可以出现在多个范围里，宿主不得为不同范围保存副本。
+
+### 5.2 回调一览
+
+```js
+annotation_callbacks: {
+  user(ctx),                                // → { id, nickname, avatar } | null
+  login(ctx),                               // → void；游客互动时调用
+  load({ ...ctx, chapter }),                // → Record[] 或 { annotations }
+  list({ ...ctx, scope, chapter, paragraph_cfi, cursor, limit }),  // → Page
+  summary({ ...ctx, chapter }),             // → [{ paragraph_cfi, count }] 或 { items }
+  get({ ...ctx, id }),                      // → Record
+  replies({ ...ctx, root_id, cursor, limit }),                     // → Page
+  save(record, ctx),                        // → Record 或 { annotation }
+  remove({ ...ctx, id }),                   // → 任意
+  vote({ ...ctx, id, value }),              // → { like_count, dislike_count, user_vote }
+}
+// ctx = { book_id, book_url }
+// Page = { items: Record[], next_cursor: string | null, has_more: boolean }（也接受纯数组，视为没有下一页）
+```
+
+- 所有回调都是异步函数（返回 Promise）。除 `save` 外，第一个参数都已并入 `ctx`；`save` 的上下文在第二个参数。
+- `load` 和 `save` 必须提供，否则初始化失败。其余回调缺失时，用到的功能会显示「宿主未提供 xx 回调」错误，**不会静默退化到本机存储**。
+- `user` 缺失视为游客；`login` 缺失时游客互动只会提示「请先登录」。
+
+| 回调 | 何时调用 | 宿主要做的 |
+|---|---|---|
+| `user` | 初始化、`login` 完成后 | 返回当前读者；游客返回 `null` |
+| `login` | 游客点赞踩、回复、写评论、划线、看「我的」时 | 引导登录（跳转、弹窗均可）；resolve 后阅读器重新调用 `user` |
+| `load` | 进入新章节、保存后、打开「显示全部划线和评论」时 | 返回**当前读者自己**在该章节的顶层记录（含私密），用于正文标记 |
+| `list` | 打开抽屉 / 切换范围 / 滚动到底 | 按 `scope` 过滤、排序、分页（见 5.3） |
+| `summary` | 进入新章节（同一章 1 分钟内不重复）、评论增删后、打开「显示全部划线和评论」时 | 返回该章节各段**公开顶层文字评论**的数量 |
+| `get` | 预留：按 id 取单条（如深链进入详情） | 不可见时按不存在处理 |
+| `replies` | 进入详情页 / 滚动到底 | 返回某主评论的回复，**按时间正序**分页 |
+| `save` | 划线、写评论、写整书评论、修改、回复、修改回复 | 按 `id` 或 `client_id` 判断新建还是修改（幂等）；返回保存后的完整记录 |
+| `remove` | 删除确认后 | 真删除并级联（见 5.4） |
+| `vote` | 点赞 / 踩 / 再点取消 | 每人每条一票；返回最新计数和当前读者的票 |
+
+### 5.3 list 的范围
+
+| scope | 返回 | 不含 |
+|---|---|---|
+| `paragraph` | 归属 `paragraph_cfi` 这一段的公开顶层评论 | 私密记录、回复 |
+| `chapter` | `chapter` 这一章的全部公开顶层评论 | 整书评论、私密记录、回复 |
+| `book` | 全书公开顶层评论，含整书评论 | 私密记录、回复 |
+| `mine` | 当前读者在本书的全部顶层记录，含私密划线、私密文字 | 别人的记录、回复 |
+
+排序：当前读者自己的在前，其余按时间倒序。**排序必须覆盖整个结果集后再分页**，不能每页各自排序。游标由宿主生成，阅读器原样回传；切换范围时游标重置，迟到的旧范围响应会被丢弃。
+
+### 5.4 记录字段
+
+| 字段 | 谁填 | 说明 |
+|---|---|---|
+| `id` | 宿主 | 稳定 id |
+| `client_id` | 阅读器 | 新建时生成的 UUID；宿主用它做幂等 |
+| `annotation_type` | 阅读器 | `highlight` 划线 / `note` 文字评论 / `book_comment` 整书评论；回复也是 `note` |
+| `is_private` | 阅读器 | 划线固定 `true`；回复不使用（跟随主评论） |
+| `chapter` | 阅读器 | 章节名（见 4.4）；整书评论为空串 |
+| `cfi` | 阅读器 | **归属位置**：划线是精确选区；文字评论是所在段落（跨段归属最后一段）；整书评论是全书开头 `epubcfi(<第一个正文文件>!/4)` |
+| `range_cfi` | 阅读器 | 真实选区；与 `cfi` 分开保存，不得用归属位置覆盖 |
+| `quote_text` | 阅读器 | 单段文字评论为整段原文；跨段评论和划线为所选文字 |
+| `content` | 阅读器 | 评论内容；划线为空串 |
+| `color` | 阅读器 | 标记颜色：划线 `yellow`，评论 `blue` |
+| `root_id` | 阅读器 | 回复所属的主评论；顶层记录为空 |
+| `reply_to_id` | 阅读器 | 回复对象（主评论或另一条回复）；空表示直接回复主评论 |
+| `thread_id` | 宿主 | 所属第一层回复；直接回复主评论的为空。由宿主根据 `reply_to_id` 推出，不信任客户端 |
+| `reply_to_name` | 宿主 | 回复对象的昵称，用于显示「回复 某人：」 |
+| `author_name` / `is_mine` | 宿主 | 作者昵称；是否当前读者所写（决定修改、删除入口） |
+| `created_at` | 宿主 | ISO 时间 |
+| `like_count` / `dislike_count` / `user_vote` / `reply_count` | 宿主 | 计数与当前读者的票（`1` / `-1` / `0`）；`reply_count` 只对顶层记录有意义 |
+
+修改时阅读器只发 `{ id, client_id, annotation_type, content, is_private }`（回复为 `{ id, client_id, root_id, content }`），宿主只更新这些字段。
+
+### 5.5 宿主必须在服务端保证的规则
+
+1. 私密记录及其全部回复，只有主评论作者可见；对其他人按「不存在」处理，包括 `get` / `replies` / `vote` / 回复的 `save`。
+2. 回复没有自己的公开范围，跟随主评论。公开评论改为私密后，已有回复只有主评论作者能看到，不能再投票或回复。
+3. 只能修改、删除自己的记录。
+4. 删除是真删除：删主评论连同全部回复和投票；删第一层回复连同其下回复。
+5. 划线固定私密；私密记录不接受投票。
+6. 回复的 `root_id` / `reply_to_id` 必须属于同一本书、同一主评论。
+7. `summary` 只统计公开的顶层文字评论，不计私密记录、回复、投票。
+
+### 5.6 错误约定
+
+- 回调失败时 **reject 一个 `Error`，`message` 写给读者看的原因**（如「请先登录」「这条评论已不存在」），阅读器会原样展示。
+- 需要登录才能查看：`list` / `replies` 以 `code` 为 `need_login` 的错误拒绝（`Object.assign(new Error('登录后查看评论'), { code: 'need_login' })`），阅读器显示「登录后查看评论」和「去登录」按钮（调用 `login`），读者登录后自动重新加载。宿主不开放游客浏览时这样做。
+- 列表失败：显示可重试的错误态，已加载的内容保留。
+- 保存失败：编辑框不关、选区不丢，可以再次保存；划线失败时正文不出现标记。
+- 投票失败：界面恢复到投票前的计数和状态。
+- 阅读器不重试，重试由读者触发。
+
+### 5.7 本机实现与参照实现
+
+- **不传 `annotation_callbacks`**：使用 `src/annotations.js` 的 `localStorage` 实现，按 `book_id`（缺省为 `book_url`）隔离，键为 `candle-reader:annotations:v1:<book>`。只有当前浏览器这一位读者，「公开」不会真的对他人生效，编辑框会提示这一点。
+- **参照实现**：`demo/memory-host.js` 完整实现了本节所有规则，是写新宿主时的对照样本；`demo.html` 和 e2e 的 `tests/e2e/fixtures/mock-host.js` 都基于它。改契约时三处（本文、`README.md`、`memory-host.js`）同步修改。
+
+## 6. 其他对外依赖
+
+### 6.1 主题样式表（themes_css）
+
+- 纯色主题以 class 形式写在样式表里（`.white` / `.eyecare` / `.grey` / `.dark`），epub.js 把它注入正文 iframe 并给 body 加上对应 class。
+- 段尾气泡（`.comment-anchor` / `.comment-icon` / `.comment-count`）的样式也在这里；锚点与气泡的定位规则（零宽锚点 + 绝对定位）是「气泡不改变排版」的前提，宿主自带样式表时需同步。深色主题的 `.grey *` / `.dark *` 会给所有元素刷底色，新增插入正文的元素时注意显式设透明。
+- 图片皮肤不靠样式表：阅读器把背景图铺在外层 `#main`，并向 iframe 注入透明背景、`color-scheme` 和文字色（`apply_custom_style`）。
+
+### 6.2 阅读器向正文注入的内容
+
+- 段尾评论气泡：段落末尾插入零宽锚点 `span.comment-anchor`，气泡 `div.comment-icon` 绝对定位挂在锚点上，**不参与正文排版**——插入、移除气泡都不会让文字折行或后文移动。epub.js 的划线标记按绘制那一刻的文字位置画、之后不随排版重算，气泡若占位就会让标记错位。气泡以段落**最后一个可见字**定位（段尾常有 `<br>` 或换行空白，锚点本身会落到下一行），与末行垂直居中、紧跟其后；末行写满时伸进右侧页边距，超出页边距的部分向左收回（`fit_comment_icon`）。字号、行距等设置变化或窗口尺寸变化后重新定位（`refit_comment_icons`）。计算段落原文和 CFI 时会跳过气泡，不影响选区与引用。一屏可能从上一章末尾跨进下一章，短章、宽屏或连续滚动时还会跨好几章（一个正文文件里有多章时常见），正文标记和段尾气泡按这一屏从页首到页尾出现的每一章分别读取（`tocs_between` / `visible_chapters`）；本段评论按段落自己所在的章节查询，不用页首章节。
+- epub.js 标记（class `candle-reader-annotation`）：只画划线，文字评论不铺底色；同一 CFI 只画一个，记录可以有多条。
+- 行距、字距、`-webkit-touch-callout` 等通过 `rendition.themes.default()` 注入。
+
+### 6.3 有声书回调（audiobook_callbacks）
+
+```js
+audiobook_callbacks: {
+  manifest(ctx),        // → { manifest: { id, chapters: [Chapter] }, progress: { chapter_id, position_ms, version } | null }
+  timeline({ ...ctx, manifest_id, chapter }),            // → Segment[]，或 { segments }，或 { timeline: { segments } }
+  start_session({ ...ctx, manifest_id, source, device_id }),   // 可选 → { session_id }
+  report_progress({ ...ctx, session_id, chapter_id, position_ms, segment_id,
+                    listened_delta_ms, completed, version }),   // 可选 → { version }
+  end_session({ ...ctx, session_id }),                   // 可选
+}
+// Chapter = { id, number, title, source_key, duration_ms, audio_url, timeline_url? }
+// Segment = { id, index, start_ms, end_ms, text, locator: { type: 'epub-dom-text', href, dom_path, start_char, end_char } }
+```
+
+- `manifest`、`timeline` 必须提供；三个会话回调可选，不提供时只在本机记住收听位置（`candle:audiobook:<book_id>`）。
+- `audio_url` 由 `<audio>` 直接加载，必须是浏览器能访问、支持 Range 请求的地址；`source_key` 是该章在电子书里的 href，用于翻到对应正文。
+- `chapter` 参数是清单里的整个章节对象，宿主可以用其中的 `timeline_url` 或 `number` 定位时间轴。
+- `report_progress` 播放中约每 10 秒调用一次，暂停和一章播完时立即调用（播完最后一章时 `completed` 为 `true`）；版本冲突时宿主同样返回最新 `version`，阅读器下次上报以它为准。
+- 清单失败时播放器显示错误信息（Error 的 `message`）；时间轴、会话失败不打断播放，只是不能高亮跟随或不上报进度。
+
+## 7. 设置
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `flow` | `paginated` | `paginated` 左右点击翻页 / `scrolled` 上下滑动 |
+| `paging_control` | `mouse_and_keyboard` | 或 `keyboard_only` |
+| `wheel_paging` | `true` | 左右翻页时鼠标滚轮翻页 |
+| `font_size` / `line_height` / `letter_spacing` / `brightness` | 18 / 1.5 / 0 / 100 | |
+| `theme` / `theme_mode` / `theme_day` / `theme_night` | `white` / `day` / `white` / `grey` | 白天/夜晚按钮在最近使用的两套之间切换 |
+| `show_comments` | `true` | 「显示全部划线和评论」：正文划线标记与段尾气泡 |
+| `show_selection_toolbar` | `true` | 「选中文字后显示工具栏」 |
+
+两个评论开关相互独立，关闭都不删除数据，评论入口始终可用。早期的总开关 `notes_enabled` 已去掉，迁移规则见 `src/note-settings.js`。
+
+## 8. 本机存储
+
+| 键 | 内容 |
+|---|---|
+| `readerSettings` | 第 7 节的设置 |
+| `lastReadPosition_<book_url>` | 上次阅读位置（CFI）；有值时优先于 `display_url` |
+| `candle-reader:comment-public` | 新建评论的公开范围偏好；只在新建保存成功后更新，编辑已有记录、划线不改它 |
+| `candle-reader:annotations:v1:<book>` | 未注入回调时的本机评论数据 |
+
+所有读写都要 `try/catch`：无痕模式等情况下 `localStorage` 可能不可用，不能因此挡住阅读。
+
+## 9. 加载与错误处理
+
+- 正文 60 秒未显示时提示「加载较慢」但不中断加载，加载完成后提示自动关闭；真正加载失败时提示「加载失败」。两者都可「重试」，重试会先销毁上一次的 rendition。
+- 回调错误见 5.6。阅读器内部计算（如段落序号）失败不得挡住主流程（工具栏、翻页）。
+
+## 10. 扩展指引
+
+**新增一个需要数据的功能**
+
+1. 先判断归属（第 2 节）。属于宿主的数据，设计为新的回调，参数并入 `ctx`，返回值形状写进第 5 节。
+2. 在 `src/annotations.js` 的仓库包装里加方法：补上下文、校验返回形状；回调缺失时抛出明确错误，不要静默退化。
+3. 在 `demo/memory-host.js` 实现它，让演示页和 e2e 可用（有声书回调由 e2e 的 `reader-harness.html` 模拟宿主实现）。
+4. 组件只通过 `annotation_repository` 调用。
+5. 同步更新本文、`README.md`、`AGENTS.md`（若改变产品交互）。
+
+**新增一个面板或页面**
+
+- 底部面板加入 `menu.panels`，通过 `set_menu` 切换；独立全屏页面沿用 `rc-standalone` 和历史记录栈，新增浮层沿用 `rc-above-standalone`。
+
+**不要做的事**
+
+- 不要在阅读器里请求任何后端接口（评论、账号、有声书……），也不要新增 `$backend` 一类的全局请求工具；新的数据需求一律设计成回调。
+- 不要在阅读器里做权限判断来「保护」数据：界面上的隐藏只是体验，权限以宿主为准。
+- 不要为段落、章节、全书分别保存同一条评论的副本。
+- 不要另起一套选区监听替代 epub.js 的 `selected` 事件。
+- 不要在正文 iframe 里拦截 `touchmove`。
+
+## 11. 测试与演示
+
+- e2e：Playwright，全部 mock，不依赖真实宿主。入口 `tests/e2e/fixtures/reader-harness.html`；加 `?host=1` 注入内存宿主（`&guest=1` 游客，`&extra=N` 追加 N 条评论），不加则走本机存储。提交前全量通过（见 `AGENTS.md`）。
+- 演示：`make dev` 后打开 `/demo.html`；`make dist` 生成可直接部署的 `dist/demo.html` 和介绍页 `dist/index.html`，合并进 main 后由 `.github/workflows/pages.yml` 发布到 GitHub Pages（仓库 Pages 的 Source 需设为 GitHub Actions）。皮肤图片按打包脚本自己的地址解析，部署在子路径下也能加载。演示页加 `?diag=1` 显示选中文字相关事件，用于真机排查。
+- 真机差异：iOS Safari 的选字、系统菜单、点击时序与桌面浏览器（包括桌面 Safari 的手机模拟）不同，涉及选区和触摸的改动必须在 iPhone 上实测。
diff --git a/Makefile b/Makefile
index 13d2f3e..3ebfd14 100644
--- a/Makefile
+++ b/Makefile
@@ -1,10 +1,18 @@
 # 每次构建生成一个时间戳版本号，盖到 dist/demo.html 的静态资源引用上做缓存刷新
 VERSION := $(shell date +%Y%m%d%H%M%S)
 
-all:
+.PHONY: all dist sync install dev
+
+# 打包阅读器，并生成可直接部署的纯内存演示页 dist/demo.html（西游记 + 内存版宿主，见 demo.html）与介绍页 dist/index.html
+dist:
 	npm run build
-	sed -E 's#(/style\.css)(\?v=[0-9]+)?#\1?v=$(VERSION)#; s#(/candle-reader\.es\.js)(\?v=[0-9]+)?#\1?v=$(VERSION)#' dist/demo.html > dist/demo.html.tmp && mv dist/demo.html.tmp dist/demo.html
-	@echo "demo.html 资源已打版本号: ?v=$(VERSION)"
+	mkdir -p dist/demo
+	cp demo/memory-host.js public/demo/xi-you-ji.epub dist/demo/
+	sed -e 's#\./src/main\.js#./candle-reader.es.js?v=$(VERSION)#' -e 's#<!-- demo:style -->#<link rel="stylesheet" href="./style.css?v=$(VERSION)">#' demo.html > dist/demo.html
+	sed -e 's#__VERSION__#$(VERSION)#g' intro.html > dist/index.html
+	@echo "已生成 dist/demo.html，资源版本号: ?v=$(VERSION)"
+
+all: dist
 
 sync: all
 	rsync -rv dist/ sz:~/Q/
diff --git a/README.md b/README.md
index d351a2c..40ae6c9 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,76 @@
 # candle-reader
-秉烛夜读
+
+秉烛夜读。
+
+## 演示
+
+```bash
+make dev    # 打开 http://localhost:5001/demo.html
+make dist   # 打包，并生成可直接部署的 dist/demo.html
+            # 合并进 main 后由 .github/workflows/pages.yml 发布到 https://talebook.github.io/candle-reader/
+```
+
+演示页用《西游记》和一个纯内存版宿主（`demo/memory-host.js`，完整实现下面的回调契约），可以体验划线、评论、回复、赞踩、「我的」和游客登录引导；数据只在内存里，刷新即重置。
+
+## 划线与评论接入
+
+划线、文字评论和整书评论是同一种记录，统称「评论」。阅读器负责全部界面：选区工具栏、评论抽屉、完整评论页、评论详情页、编辑框、赞踩与回复。**阅读器自身不请求任何评论或账号服务**，数据与登录态全部通过初始化时注入的 `annotation_callbacks` 交给宿主：
+
+```js
+new Reader('#app', {
+  book_url: '/books/1/',
+  book_id: 1,
+  annotation_callbacks: {
+    async user() {},                    // 当前读者 { id, nickname, avatar }；游客返回 null
+    async login() {},                   // 游客触发互动时调用，由宿主引导登录
+    async load({ chapter }) {},         // 当前读者在本章的记录（用于正文标记），返回 Annotation[]
+    async list({ scope, chapter, paragraph_cfi, cursor, limit }) {},  // 顶层记录分页
+    async summary({ chapter }) {},      // [{ paragraph_cfi, count }]，段尾气泡的公开评论数
+    async get({ id }) {},               // 单条记录
+    async replies({ root_id, cursor, limit }) {},                     // 某条评论的回复分页
+    async save(annotation, { book_id, book_url }) {},                 // 新建或修改，返回保存后的记录
+    async remove({ id }) {},            // 真删除
+    async vote({ id, value }) {},       // value: 1 赞 / -1 踩 / 0 取消；返回 { like_count, dislike_count, user_vote }
+  },
+})
+```
+
+除 `save` 外，每个回调的第一个参数都会并入 `{ book_id, book_url }`。`load` 与 `save` 必须同时提供；其余回调缺失时，对应功能会显示明确错误，不会静默改写到本地。
+
+分页回调返回 `{ items, next_cursor, has_more }`（也接受纯数组，视为没有下一页）。`list` 的 `scope`：
+
+| scope | 返回 |
+|---|---|
+| `paragraph` | 归属 `paragraph_cfi` 这一段的公开文字评论 |
+| `chapter` | 本章全部公开文字评论，不含整书评论 |
+| `book` | 全书公开评论，含整书评论 |
+| `mine` | 当前读者在本书的全部记录，含私密划线与私密文字 |
+
+公开范围的列表由宿主排序：当前读者自己的在前，再按时间倒序，**排序覆盖整个结果集后再分页**。回复按时间正序。
+
+记录字段：
+
+- `id` / `client_id`：稳定标识；`save` 按它们判断新建还是修改。
+- `annotation_type`：`highlight`（划线）、`note`（文字评论）、`book_comment`（整书评论）。
+- `is_private`：划线固定 `true`。回复没有自己的公开范围，跟随主评论；主评论为私密时，其回复只对主评论作者可见。
+- `chapter`、`cfi`、`range_cfi`、`quote_text`：`cfi` 是评论归属的位置——划线为精确选区，文字评论为所在段落（跨段选区归属最后一段），整书评论为全书开头；`range_cfi` 保留真实选区。
+- `content`、`created_at`、`author_name`、`is_mine`。
+- `like_count`、`dislike_count`、`user_vote`（`1` / `-1` / `0`）、`reply_count`。
+- 回复：`root_id`（所属主评论）、`reply_to_id`（回复对象，空表示回复主评论）、`reply_to_name`、`thread_id`（所属第一层回复，由宿主根据 `reply_to_id` 推出；第一层回复为空）。
+
+宿主需要保证：非作者访问私密记录及其回复时按不存在处理；`remove` 主评论时连同全部回复和投票删除，删除第一层回复时连同其下回复删除；私密记录不接受投票和回复。
+
+不传 `annotation_callbacks` 时，阅读器按 `book_id`（缺省时按 `book_url`）隔离并保存到浏览器 `localStorage`：只有当前浏览器这一位读者，公开范围不会真的对他人生效。回调已经注入但执行失败时不会静默写入本地，避免宿主数据和本地数据产生不可见分叉。
+
+“设置”里有两个相互独立的开关，都不删除数据，评论入口始终可用：
+
+- 显示全部划线和评论：控制正文里的划线标记和段尾的评论数量气泡（有评论的段落只显示气泡，不铺底色）。
+- 选中文字后显示工具栏：控制选区工具栏，关闭后选中文字只出现系统自带的菜单。
+
+底部固定为目录、白天/夜晚、评论、设置，听书在顶部。完整的交互约定见 `AGENTS.md`。
+
+## 听书接入
+
+传入 `audiobook_callbacks` 后显示「听书」入口。宿主提供章节清单（`manifest`）和时间轴（`timeline`），可选提供收听会话与进度上报（`start_session` / `report_progress` / `end_session`）。阅读器不直接请求有声书接口，音频文件按清单里的 `audio_url` 由浏览器加载。完整契约见 `DESIGN.md` 第 6.3 节。
+
+旧 `readerSettings` 自动迁移：早期的总开关 `notes_enabled` 已去掉，曾经关闭它的读者迁移后两个开关都按关闭处理；`show_comments` 保留，`show_selection_toolbar` 缺失时取旧 `show_annotations`（缺失按开启）。
diff --git a/demo.html b/demo.html
new file mode 100644
index 0000000..94bf453
--- /dev/null
+++ b/demo.html
@@ -0,0 +1,194 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <link rel="icon" href="./favicon.ico" />
+  <!-- demo:style -->
+  <meta name="theme-color" content="#F6F6F6" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+  <title>秉烛夜读 · 评论功能演示（西游记）</title>
+  <!-- JSZip 必须在 epub.js 之前加载 -->
+  <script src="./js/jszip-v3.10.1.min.js"></script>
+  <script src="./js/epub-v0.3.88.js"></script>
+  <style>
+    /* 层级低于阅读器的面板与独立页面：打开评论时演示条自动被盖住，不挡操作。 */
+    #demo-bar { position: fixed; z-index: 200; top: 56px; right: 8px; max-width: min(320px, calc(100vw - 16px)); font: 12px/1.6 system-ui, sans-serif; color: #fff; background: rgba(32, 51, 63, .94); border-radius: 10px; box-shadow: 0 6px 20px rgba(0, 0, 0, .28); }
+    #demo-bar summary { display: flex; align-items: center; gap: 8px; padding: 6px 10px; cursor: pointer; list-style: none; white-space: nowrap; }
+    #demo-bar summary::-webkit-details-marker { display: none; }
+    #demo-bar .demo-body { padding: 0 12px 10px; }
+    #demo-bar button { margin: 4px 6px 4px 0; padding: 4px 10px; font: inherit; color: #20333f; background: #fff; border: 0; border-radius: 6px; cursor: pointer; }
+    #demo-bar ul { margin: 6px 0 0; padding-left: 18px; }
+    #demo-bar b { color: #ffd479; font-weight: 600; }
+  </style>
+  <script type="module">
+    // 演示页：阅读器 + 纯内存版宿主。所有划线、评论、回复、赞踩和登录态都经 annotation_callbacks，
+    // 不请求任何后端；刷新页面后数据重置。真实接入方式与这里完全相同，只是回调改为请求宿主的接口。
+    // make dist 会把这一行改成打包后的 ./candle-reader.es.js，并在上面的 demo:style 处补上样式表。
+    import { Reader } from './src/main.js'
+    import { createMemoryHost } from './demo/memory-host.js'
+
+    const ME = { id: 1, nickname: '悟空迷', avatar: '' }
+    const params = new URLSearchParams(location.search)
+    const host = createMemoryHost({ user: params.has('guest') ? null : ME })
+    const reader = () => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const ago = minutes => new Date(Date.now() - minutes * 60000).toISOString()
+    const other = (name, id) => ({ author_name: name, author_id: 1000 + id })
+    const mine = { author_name: ME.nickname, author_id: ME.id }
+
+    // ---- 示例数据：整书评论在启动时准备，章节与段落评论在第一次读到该章时按真实段落位置准备 ----
+    host.add({ ...other('三藏', 1), annotation_type: 'book_comment', chapter: '', content: '八十一难，一难都少不得。小时候看热闹，长大了才看出取经路上全是人情世故。', like_count: 36, dislike_count: 2, created_at: ago(60 * 26) })
+    const bookTalk = host.add({ ...other('白龙马', 2), annotation_type: 'book_comment', chapter: '', content: '最喜欢前七回，大闹天宫写得酣畅淋漓。', like_count: 18, created_at: ago(60 * 50) })
+    host.add({ ...other('沙和尚', 3), root_id: bookTalk.id, content: '后面的取经路其实更耐读。', like_count: 4, created_at: ago(60 * 40) })
+    host.add({ ...mine, annotation_type: 'book_comment', chapter: '', is_private: true, content: '（私密）打算今年把原著完整读一遍，这是第一遍的记录。', created_at: ago(60 * 5) })
+
+    const seeded = new Set()
+    function seedChapter(chapter) {
+      if (!chapter || seeded.has(chapter)) return
+      const r = reader()
+      const toc = r.current_toc
+      if (!toc?.elem || String(toc.label).trim() !== chapter) return
+      const contents = r.rendition.getContents().find(c => c.document === toc.elem.ownerDocument)
+      if (!contents) return
+      // 取本章标题之后的正文段落。
+      const paragraphs = Array.from(contents.document.querySelectorAll('p')).filter(p => p.textContent.trim().length > 40 && (toc.elem.compareDocumentPosition(p) & Node.DOCUMENT_POSITION_FOLLOWING))
+      if (paragraphs.length < 6) return
+      seeded.add(chapter)
+      const at = index => {
+        const location = r.paragraph_location(paragraphs[index], contents)
+        return { chapter, cfi: location.paragraph_cfi, range_cfi: location.paragraph_cfi, quote_text: location.paragraph_quote_text }
+      }
+      const first = at(0), second = at(2), third = at(5)
+
+      // 第一段：别人的公开评论，其中一条带多层回复。
+      const hot = host.add({ ...other('花果山猴', 11), ...first, content: '开篇这段写天地之数，气象很大，一下子就把人带进神话里了。', like_count: 42, dislike_count: 1, created_at: ago(90) })
+      const r1 = host.add({ ...other('菩提弟子', 12), root_id: hot.id, content: '是的，十二万九千六百岁为一元，古人的宇宙观很浪漫。', like_count: 9, created_at: ago(80) })
+      const r2 = host.add({ ...mine, root_id: hot.id, thread_id: r1.id, reply_to_id: r1.id, reply_to_name: r1.author_name, content: '原来是邵雍《皇极经世》里的说法。', like_count: 2, created_at: ago(70) })
+      host.add({ ...other('花果山猴', 11), root_id: hot.id, thread_id: r1.id, reply_to_id: r2.id, reply_to_name: ME.nickname, content: '涨知识了，谢谢。', created_at: ago(60) })
+      host.add({ ...other('天蓬', 13), root_id: hot.id, content: '我每次都想跳过这段直接看石猴出世，哈哈。', like_count: 5, dislike_count: 3, created_at: ago(30) })
+      host.add({ ...other('太白金星', 14), ...first, content: '这里的韵文读出声来特别有节奏。', like_count: 7, created_at: ago(200) })
+
+      // 第二段：我的公开评论（别人回复过），以及一条由公开改成私密、回复只有我能看的评论。
+      const myPublic = host.add({ ...mine, ...second, content: '这一段的铺垫很细，后面每个伏笔都能在这里找到影子。', like_count: 6, created_at: ago(15) })
+      host.add({ ...other('卷帘', 15), root_id: myPublic.id, content: '同感，二刷才发现。', like_count: 1, created_at: ago(10) })
+      const myPrivate = host.add({ ...mine, ...second, is_private: true, content: '（私密）这句可以抄进读书笔记。', created_at: ago(8) })
+      host.add({ ...other('菩提弟子', 12), root_id: myPrivate.id, content: '这条是评论还公开时别人留下的回复，现在只有你能看到。', created_at: ago(300) })
+
+      // 第三段：我的私密划线（正文里会画出黄色标记）。
+      const quote = third.quote_text.slice(0, 24)
+      const range = contents.document.createRange()
+      const text = contents.document.createTreeWalker(paragraphs[5], NodeFilter.SHOW_TEXT).nextNode()
+      range.setStart(text, 0)
+      range.setEnd(text, Math.min(text.length, 24))
+      host.add({ ...mine, chapter, annotation_type: 'highlight', is_private: true, cfi: contents.cfiFromRange(range), range_cfi: contents.cfiFromRange(range), quote_text: range.toString() || quote, color: 'yellow', created_at: ago(5) })
+
+      // 再补 30 条本章评论，用来体验滚动分页（不挂在具体段落上，所以不计入段尾气泡）。
+      const lines = ['石猴出世这段百读不厌。', '美猴王的称呼原来是这么来的。', '水帘洞真是个好地方。', '这回的诗词比想象中多。', '读到这里想起了八六版电视剧。']
+      for (let i = 0; i < 30; i++) host.add({ ...other(`书友${i + 1}`, 100 + i), chapter, content: lines[i % lines.length], like_count: i % 4, created_at: ago(400 + i * 37) })
+    }
+
+    // 读到新的一章时先准备示例数据，再交给内存宿主处理。
+    const callbacks = { ...host.callbacks }
+    for (const name of ['load', 'list', 'summary']) {
+      callbacks[name] = query => { try { seedChapter(query.chapter) } catch (error) { console.warn('演示数据准备失败：', error) } return host.callbacks[name](query) }
+    }
+    // 登录由宿主负责：这里用一个确认框代替登录页。
+    callbacks.login = async () => {
+      if (window.confirm(`演示：以「${ME.nickname}」的身份登录？`)) setUser(ME)
+    }
+
+    function setUser(user) {
+      host.setUser(user)
+      document.getElementById('demo-identity').textContent = user ? user.nickname : '游客'
+      document.getElementById('demo-toggle').textContent = user ? '切换为游客' : `以「${ME.nickname}」登录`
+      const r = reader()
+      r.load_user().then(() => { r.$refs.comments?.reload(); r.on_comments_changed() })
+    }
+
+    // ?fresh=1：忘掉上次读到的位置，从第一回开始（示例评论按第一回的段落准备）。
+    if (params.has('fresh')) {
+      try { localStorage.removeItem('lastReadPosition_./demo/xi-you-ji.epub') } catch (error) { /* 无痕模式等情况下不可用 */ }
+    }
+
+    new Reader('#app', {
+      debug: false,
+      themes_css: './css/themes.css',
+      book_url: './demo/xi-you-ji.epub',
+      // 直接从第一回开始，跳过电子书的版权页。
+      display_url: params.get('at') || '5039418960600707614_23962-0-0.txt.xhtml#chapter-001',
+      book_id: 'demo-xi-you-ji',
+      annotation_callbacks: callbacks,
+    })
+
+    window.__demoHost = host
+
+    // ?diag=1：诊断面板。只在阅读器外面旁观、记录事件，不参与选中逻辑，用于在真机上排查选中文字后工具栏不出现的问题。
+    if (params.has('diag')) {
+      const lines = []
+      const log = text => {
+        lines.push(`${new Date().toTimeString().slice(3, 8)} ${text}`)
+        document.getElementById('demo-diag').textContent = lines.slice(-16).join('\n')
+      }
+      document.getElementById('demo-bar').open = true
+      window.addEventListener('error', event => log(`错误 ${event.message}`))
+      window.addEventListener('unhandledrejection', event => log(`异常 ${event.reason?.message || event.reason}`))
+      const watched = new WeakSet()
+      const watch = doc => {
+        if (!doc || watched.has(doc)) return
+        watched.add(doc)
+        let last = ''
+        doc.addEventListener('selectionchange', () => {
+          const selection = doc.getSelection()
+          const text = `选区变化 rangeCount=${selection?.rangeCount} 文字="${String(selection || '').slice(0, 8)}"`
+          if (text !== last) log(last = text)
+        })
+        for (const name of ['touchstart', 'touchend', 'click']) doc.addEventListener(name, () => log(name), { passive: true })
+      }
+      const attach = setInterval(() => {
+        const r = document.querySelector('#app').__vue_app__?._instance?.subTree?.component?.proxy
+        if (!r?.rendition) return
+        clearInterval(attach)
+        r.rendition.on('selected', cfi => {
+          log(`epub.js selected ${String(cfi).slice(-24)}`)
+          // 工具栏没出现时，看是设置关掉了，还是位置算出来不对。
+          setTimeout(() => log(`设置 笔记=${r.settings.notes_enabled} 选中工具栏=${r.settings.show_selection_toolbar} 位置=${Math.round(r.toolbar_left)},${Math.round(r.toolbar_top)} 窗口=${innerWidth}x${innerHeight}`), 50)
+        })
+        r.rendition.on('rendered', () => r.rendition.getContents().forEach(c => watch(c.document)))
+        r.rendition.getContents().forEach(c => watch(c.document))
+        let shown = false
+        setInterval(() => {
+          r.rendition.getContents().forEach(c => watch(c.document))
+          const visible = r.is_toolbar_visible()
+          if (visible !== shown) log(visible ? `工具栏显示 @ ${Math.round(r.toolbar_left)},${Math.round(r.toolbar_top)}` : '工具栏隐藏')
+          shown = visible
+        }, 100)
+        log('诊断已就绪')
+      }, 200)
+    }
+    document.getElementById('demo-identity').textContent = host.getUser()?.nickname || '游客'
+    document.getElementById('demo-toggle').textContent = host.getUser() ? '切换为游客' : `以「${ME.nickname}」登录`
+    document.getElementById('demo-toggle').onclick = () => setUser(host.getUser() ? null : ME)
+    document.getElementById('demo-reset').onclick = () => location.reload()
+  </script>
+</head>
+<body>
+  <div id="app"></div>
+  <details id="demo-bar">
+    <summary>演示 · 当前身份：<b id="demo-identity"></b></summary>
+    <div class="demo-body">
+      <button id="demo-toggle" type="button"></button><button id="demo-reset" type="button">重置数据</button>
+      <pre id="demo-diag" style="margin:6px 0;white-space:pre-wrap;max-height:40vh;overflow:auto;font-size:11px"></pre>
+      <div>数据只在内存里，刷新即重置。可以试：</div>
+      <ul>
+        <li>底部「评论」：本章评论，滚动到底自动加载</li>
+        <li>「查看更多评论」：本章／全书／我的</li>
+        <li>点任意评论进详情：回复、回复的回复、修改、删除</li>
+        <li>赞、踩（再点一次取消）</li>
+        <li>正文选中文字：划线、写评论、看本段评论</li>
+        <li>正文段尾的数字气泡：进入本段评论</li>
+        <li>切换为游客后再点赞或写评论：引导登录</li>
+        <li>窗口拉宽到 850px 以上：侧边栏布局</li>
+      </ul>
+    </div>
+  </details>
+</body>
+</html>
diff --git a/demo/memory-host.js b/demo/memory-host.js
new file mode 100644
index 0000000..5d3087d
--- /dev/null
+++ b/demo/memory-host.js
@@ -0,0 +1,134 @@
+// 纯内存版宿主：完整实现 annotation_callbacks 契约（见 README.md），多位读者、分页、投票与回复俱全。
+// demo.html 用它做可离线体验的演示，e2e 的 mock-host.js 也基于它。刷新页面后数据即重置。
+// 真实宿主是 Talebook；这里只是契约的参照实现，不代表任何后端的存储方式。
+
+export function createMemoryHost({ user = null, pageSize = 20, intercept = null } = {}) {
+  let current = user
+  let seq = 100000
+  const records = []
+
+  const isMine = item => Boolean(current) && item.author_id === current.id
+  const top = item => item.root_id ? records.find(other => other.id === item.root_id) : item
+  // 回复没有独立的公开范围，跟随主评论；私密记录及其回复只有主评论作者可见。
+  const visible = item => { const main = top(item); return Boolean(main) && (main.is_private === false || isMine(main)) }
+  // chapter 为 '*' 的记录出现在任意章节。
+  const inChapter = (item, chapter) => item.chapter === '*' || item.chapter === chapter
+  const view = item => {
+    const { votes, ...rest } = item
+    return {
+      ...rest,
+      is_mine: isMine(item),
+      user_vote: current ? votes[current.id] || 0 : 0,
+      reply_count: item.root_id ? 0 : records.filter(other => other.root_id === item.id).length,
+    }
+  }
+  const page = (items, cursor, limit) => {
+    const start = Number(cursor) || 0
+    const end = start + (Number(limit) || pageSize)
+    return { items: items.slice(start, end).map(view), next_cursor: end < items.length ? String(end) : null, has_more: end < items.length }
+  }
+  const requireUser = () => { if (!current) throw new Error('请先登录') }
+  const find = id => {
+    const item = records.find(other => other.id === id)
+    if (!item || !visible(item)) throw new Error('这条评论已不存在')
+    return item
+  }
+  const enter = async (name, query) => { if (intercept) await intercept(name, query) }
+
+  // 直接写入一条记录（用于准备演示或测试数据），不做权限校验。
+  function add(fields) {
+    const id = fields.id ?? ++seq
+    const item = {
+      id, client_id: `memory-${id}`, annotation_type: 'note', is_private: false, chapter: '*', cfi: '', range_cfi: '',
+      quote_text: '', content: '', author_id: 0, author_name: '书友', created_at: new Date().toISOString(),
+      like_count: 0, dislike_count: 0, votes: {}, root_id: null, thread_id: null, reply_to_id: null, reply_to_name: '',
+      ...fields,
+    }
+    records.push(item)
+    return item
+  }
+
+  const callbacks = {
+    async user() { await enter('user'); return current },
+    async login() { await enter('login') },
+    async load(query) {
+      await enter('load', query)
+      return records.filter(item => !item.root_id && isMine(item) && (!query.chapter || inChapter(item, query.chapter))).map(view)
+    },
+    async list(query) {
+      await enter('list', query)
+      const { scope, chapter, paragraph_cfi: paragraph } = query
+      const items = records.filter(item => !item.root_id).filter(item => {
+        if (scope === 'mine') return isMine(item)
+        if (item.is_private !== false) return false
+        if (scope === 'book') return true
+        if (item.annotation_type === 'book_comment' || !inChapter(item, chapter)) return false
+        return scope !== 'paragraph' || item.cfi === paragraph
+      // 自己的评论优先的排序覆盖整个结果集，再分页。
+      }).sort((a, b) => (isMine(b) - isMine(a)) || String(b.created_at).localeCompare(String(a.created_at)))
+      return page(items, query.cursor, query.limit)
+    },
+    async summary(query) {
+      await enter('summary', query)
+      const counts = {}
+      records.forEach(item => {
+        if (item.root_id || item.is_private !== false || item.annotation_type !== 'note' || !inChapter(item, query.chapter) || !item.cfi) return
+        counts[item.cfi] = (counts[item.cfi] || 0) + 1
+      })
+      return Object.entries(counts).map(([cfi, count]) => ({ paragraph_cfi: cfi, count }))
+    },
+    async get(query) { await enter('get', query); return view(find(query.id)) },
+    async replies(query) {
+      await enter('replies', query)
+      find(query.root_id)
+      const items = records.filter(item => item.root_id === query.root_id).sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)))
+      return page(items, query.cursor, query.limit)
+    },
+    async save(input) {
+      await enter('save', input)
+      requireUser()
+      const existing = records.find(item => (input.id && item.id === input.id) || item.client_id === input.client_id)
+      if (existing) {
+        if (!isMine(existing)) throw new Error('只能修改自己的评论')
+        existing.content = input.content ?? existing.content
+        if (!existing.root_id && input.is_private !== undefined) existing.is_private = existing.annotation_type === 'highlight' ? true : input.is_private
+        return view(existing)
+      }
+      const fields = { ...input, id: ++seq, author_id: current.id, author_name: current.nickname, created_at: new Date().toISOString() }
+      if (fields.root_id) {
+        const main = find(fields.root_id)
+        if (main.is_private !== false) throw new Error('私密记录不开放互动')
+        const target = records.find(item => item.id === fields.reply_to_id && item.root_id === main.id)
+        Object.assign(fields, { thread_id: target ? target.thread_id || target.id : null, reply_to_name: target ? target.author_name : '', is_private: false, chapter: main.chapter })
+      } else if (fields.annotation_type === 'highlight') {
+        fields.is_private = true
+      }
+      return view(add(fields))
+    },
+    async remove(query) {
+      await enter('remove', query)
+      requireUser()
+      const item = find(query.id)
+      if (!isMine(item)) throw new Error('只能删除自己的评论')
+      // 真删除：主评论连同全部回复，第一层回复连同其下回复。
+      for (let i = records.length - 1; i >= 0; i--) {
+        const other = records[i]
+        if (other.id === item.id || other.root_id === item.id || other.thread_id === item.id) records.splice(i, 1)
+      }
+      return { id: query.id }
+    },
+    async vote(query) {
+      await enter('vote', query)
+      requireUser()
+      const item = find(query.id)
+      if (top(item).is_private !== false) throw new Error('私密记录不开放互动')
+      const before = item.votes[current.id] || 0
+      item.like_count += (query.value === 1) - (before === 1)
+      item.dislike_count += (query.value === -1) - (before === -1)
+      item.votes[current.id] = query.value
+      return { like_count: item.like_count, dislike_count: item.dislike_count, user_vote: query.value }
+    },
+  }
+
+  return { callbacks, records, add, getUser: () => current, setUser(next) { current = next } }
+}
diff --git a/index.html b/index.html
index 85939e1..0cd1e19 100644
--- a/index.html
+++ b/index.html
@@ -18,10 +18,8 @@
     new Reader('#app', {
       debug: true,
       themes_css: "./css/themes.css",
-      //server: window.location.origin.replace("5001", "5002"),
-      server: "https://brs.talebook.org",
       // book_url: '/demo/book1/', display_url: 'index_split_002.html#filepos160365',
-      book_url: '/demo/book3/',
+      book_url: '/demo/xi-you-ji.epub',
       // book_url: "/guimi/", display_url: "index_split_002.html#filepos160365",
     })
   </script>
diff --git a/intro.html b/intro.html
new file mode 100644
index 0000000..634886c
--- /dev/null
+++ b/intro.html
@@ -0,0 +1,85 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+  <link rel="icon" href="./favicon.ico" />
+  <title>秉烛夜读 · 评论功能演示</title>
+  <style>
+    :root { --bg: #f6f4ef; --card: #ffffff; --text: #24312b; --muted: #66706a; --line: #e4e0d6; --primary: #3c6e57; --primary-text: #ffffff; --tint: #e8f0eb; }
+    @media (prefers-color-scheme: dark) {
+      :root { --bg: #171b19; --card: #212724; --text: #e6ebe7; --muted: #9aa59f; --line: #333b37; --primary: #7fb89a; --primary-text: #102018; --tint: #26332c; }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 0; background: var(--bg); color: var(--text); font: 15px/1.7 -apple-system, BlinkMacSystemFont, "PingFang SC", "Noto Sans SC", sans-serif; }
+    main { max-width: 680px; margin: 0 auto; padding: max(32px, env(safe-area-inset-top)) 16px 48px; }
+    .eyebrow { font-size: 12px; letter-spacing: 2px; color: var(--muted); }
+    h1 { margin: 4px 0 8px; font-size: 26px; line-height: 1.3; }
+    .lead { margin: 0 0 24px; color: var(--muted); }
+    .open { display: flex; align-items: center; justify-content: center; gap: 8px; width: 100%; min-height: 52px; padding: 0 20px; border-radius: 12px; background: var(--primary); color: var(--primary-text); font-size: 17px; font-weight: 600; text-decoration: none; }
+    .open:active { transform: translateY(1px); }
+    .more { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; margin: 10px 0 0; }
+    .more a { display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 64px; padding: 8px; border: 1px solid var(--line); border-radius: 12px; background: var(--card); color: var(--text); text-decoration: none; text-align: center; font-size: 14px; line-height: 1.35; }
+    .more small { color: var(--muted); font-size: 12px; margin-top: 2px; }
+    a:focus-visible { outline: 3px solid var(--primary); outline-offset: 2px; }
+    section { margin-top: 28px; padding: 18px 20px; border: 1px solid var(--line); border-radius: 14px; background: var(--card); }
+    h2 { margin: 0 0 10px; font-size: 17px; }
+    ol, ul { margin: 0; padding-left: 20px; }
+    li + li { margin-top: 6px; }
+    .tag { display: inline-block; padding: 0 6px; margin-right: 6px; border-radius: 4px; background: var(--tint); color: var(--primary); font-size: 12px; }
+    .note { margin: 0; color: var(--muted); font-size: 13px; }
+    footer { margin-top: 24px; color: var(--muted); font-size: 12px; text-align: center; }
+    @media (max-width: 420px) { .more { grid-template-columns: 1fr; } .more a { min-height: 48px; flex-direction: row; gap: 8px; } .more small { margin: 0; } }
+  </style>
+</head>
+<body>
+  <main>
+    <div class="eyebrow">秉烛夜读 · CANDLE READER</div>
+    <h1>评论功能演示</h1>
+    <p class="lead">用《西游记》体验阅读器里的划线、段落评论、整书评论、回复与赞踩。数据只保存在当前页面的内存里，不连接任何服务器，刷新即重置。</p>
+
+    <a class="open" id="open-main" href="./demo.html?fresh=1" target="_blank" rel="noopener">从第一回开始体验 ›</a>
+    <nav class="more" aria-label="其他打开方式">
+      <a id="open-continue" href="./demo.html" target="_blank" rel="noopener">继续上次阅读<small>回到上次读到的位置</small></a>
+      <a id="open-guest" href="./demo.html?fresh=1&amp;guest=1" target="_blank" rel="noopener">以游客身份<small>体验登录引导</small></a>
+      <a id="open-diag" href="./demo.html?fresh=1&amp;diag=1" target="_blank" rel="noopener">诊断模式<small>记录选中文字相关事件</small></a>
+    </nav>
+
+    <section aria-labelledby="try-title">
+      <h2 id="try-title">可以这样试</h2>
+      <ol>
+        <li><span class="tag">评论</span>点底部「评论」，看本章评论；往下滑会自动加载更多。</li>
+        <li><span class="tag">完整页</span>点「查看更多评论 ›」，在「本章评论／全书评论／我的」之间切换。「我的」里有私密划线和私密评论。</li>
+        <li><span class="tag">详情</span>点任意一条评论进入详情：回复、回复别人的回复、修改或删除自己的内容。</li>
+        <li><span class="tag">赞踩</span>点赞或踩，再点一次取消；两者互斥。</li>
+        <li><span class="tag">选中</span>在正文里长按选中文字：复制、划线、写评论、看本段评论。</li>
+        <li><span class="tag">气泡</span>正文段落末尾的数字气泡表示本段的公开评论数，点它进入本段评论。</li>
+        <li><span class="tag">游客</span>右上角「演示」里可以切换为游客，再点赞或写评论会提示登录。</li>
+      </ol>
+    </section>
+
+    <section aria-labelledby="tips-title">
+      <h2 id="tips-title">说明</h2>
+      <ul>
+        <li>电脑上把窗口拉宽到 850px 以上，评论和设置会变成右侧侧边栏，目录在左侧。</li>
+        <li>iPhone 上选中文字时，系统自带的「拷贝」菜单会出现在选区上方（网页无法关闭），阅读器的工具栏在选区下方。</li>
+        <li>首次打开需要下载约 13 MB（电子书和样式），网速慢时请稍等。</li>
+        <li>选中文字有问题时，用「诊断模式」打开再选一次，把右上角演示条里的记录截图发给开发者。</li>
+      </ul>
+    </section>
+
+    <footer>秉烛夜读 · 版本 __VERSION__</footer>
+  </main>
+  <script>
+    // 打包时会把 __VERSION__ 换成构建时间，给演示页链接带上版本号，避免浏览器用旧缓存。
+    const version = '__VERSION__'
+    if (!version.startsWith('__')) {
+      document.querySelectorAll('a[href^="./demo.html"]').forEach(link => {
+        const url = new URL(link.getAttribute('href'), location.href)
+        url.searchParams.set('v', version)
+        link.href = url.toString()
+      })
+    }
+  </script>
+</body>
+</html>
diff --git a/playwright.config.js b/playwright.config.js
index 79d8faf..6894d01 100644
--- a/playwright.config.js
+++ b/playwright.config.js
@@ -32,7 +32,7 @@ module.exports = defineConfig({
 
   // 自动拉起 vite dev server
   webServer: {
-    command: 'npm run dev',
+    command: `npm run dev -- --port ${PORT} --strictPort`,
     url: BASE_URL,
     reuseExistingServer: !process.env.CI,
     timeout: 60 * 1000,
diff --git a/public/css/themes.css b/public/css/themes.css
index 7b34471..ba882fb 100644
--- a/public/css/themes.css
+++ b/public/css/themes.css
@@ -27,20 +27,48 @@
 
 /* 评论图标：聊天气泡作 background，评论数作为内容居中显示在气泡内（沿用 3bc8c3d 之前的历史实现） */
 .comment-icon {
-  background: url('data:image/svg+xml;utf8,<svg viewBox="0 0 1170 1024" xmlns="http://www.w3.org/2000/svg" width="200" height="200"><path fill="%23999999" d="M841.134446 1024a36.790489 36.790489 0 0 1-17.590681-4.46167L490.052242 837.487579h-110.627465C173.74912 837.487579 0 656.095108 0 441.45954V373.035081A376.681947 376.681947 0 0 1 379.424777 0.01024h411.424457A376.681947 376.681947 0 0 1 1170.274012 373.035081v68.278174a369.367735 369.367735 0 0 1-292.568503 363.955218V987.428937a36.571063 36.571063 0 0 1-36.571063 36.571063zM379.424777 72.823226A303.539822 303.539822 0 0 0 73.142126 373.035081v68.278174c0 172.139993 143.13914 323.141911 306.282651 323.141912h119.989657a36.900202 36.900202 0 0 1 17.590682 4.46167L804.563383 926.099265v-150.233927a36.571063 36.571063 0 0 1 30.28084-35.839641C994.184344 712.26826 1097.131886 595.058004 1097.131886 441.45954V373.035081a303.539822 303.539822 0 0 0-306.282652-300.358139h-411.424457z"></path></svg>') no-repeat center center;
+  background: url('data:image/svg+xml;utf8,<svg viewBox="0 0 1170 1024" xmlns="http://www.w3.org/2000/svg" width="200" height="200"><path transform="matrix(-1 0 0 1 1170.274012 0)" fill="%23999999" d="M841.134446 1024a36.790489 36.790489 0 0 1-17.590681-4.46167L490.052242 837.487579h-110.627465C173.74912 837.487579 0 656.095108 0 441.45954V373.035081A376.681947 376.681947 0 0 1 379.424777 0.01024h411.424457A376.681947 376.681947 0 0 1 1170.274012 373.035081v68.278174a369.367735 369.367735 0 0 1-292.568503 363.955218V987.428937a36.571063 36.571063 0 0 1-36.571063 36.571063zM379.424777 72.823226A303.539822 303.539822 0 0 0 73.142126 373.035081v68.278174c0 172.139993 143.13914 323.141911 306.282651 323.141912h119.989657a36.900202 36.900202 0 0 1 17.590682 4.46167L804.563383 926.099265v-150.233927a36.571063 36.571063 0 0 1 30.28084-35.839641C994.184344 712.26826 1097.131886 595.058004 1097.131886 441.45954V373.035081a303.539822 303.539822 0 0 0-306.282652-300.358139h-411.424457z"></path></svg>') no-repeat center center;
   background-size: contain;
-  position: relative;
-  display: inline-block;
+  /* 绝对定位在零宽锚点上：不占行宽也不撑高行，插入/移除都不会让正文重排（否则划线标记会错位） */
+  position: absolute;
+  left: 0;
+  top: 50%;
+  display: block;
   width: 1.5em;
   height: 1.5em;
+  margin: -0.75em 0 0 2px;
+  padding: 0;
   text-align: center;
   font-size: 16px;
-  vertical-align: middle;
-  margin-left: 2px;
   cursor: pointer;
 }
 
+/* 段尾零宽锚点：空的行内元素，宽度为 0，只给气泡提供定位基准（垂直居中于末行文字） */
+.comment-anchor {
+  position: relative;
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  background: transparent !important;
+  font-size: inherit;
+  /* 行高归零、贴基线：即使书的样式表或阅读器的行距设置作用到它，也不会撑高末行 */
+  line-height: 0 !important;
+  vertical-align: baseline !important;
+}
+
 /* 评论数：绝对居中叠在气泡体内（不受段落 text-align:justify 影响；底部留出气泡尾巴） */
+/* 气泡插在书本自己的段落里：书的 CSS 常给段落设首行缩进、行高、字距（阅读器的行距字距设置也会以 !important 作用到全部元素），
+   这些会继承进气泡把数字挤偏，这里统一归零。 */
+.comment-icon,
+.comment-icon .comment-count {
+  text-indent: 0 !important;
+  line-height: 1 !important;
+  letter-spacing: 0 !important;
+  font-style: normal;
+  font-weight: normal;
+}
+
 .comment-count {
   position: absolute;
   left: 0;
@@ -54,6 +82,12 @@
   color: #999999;
 }
 
+/* 评论数叠在气泡体上：夜灰/纯黑的 `.grey *`、`.dark *` 会给所有元素刷不透明底色，
+   评论数必须透明，否则会盖住气泡轮廓（只剩底部尾巴露出） */
+.comment-icon .comment-count {
+  background: transparent;
+}
+
 /* 热评：数字标红 */
 .hot-comment .comment-count {
   color: #ff4444;
diff --git a/public/demo/xi-you-ji.epub b/public/demo/xi-you-ji.epub
new file mode 100644
index 0000000..9adcfac
Binary files /dev/null and b/public/demo/xi-you-ji.epub differ
diff --git a/src/CandleReader.vue b/src/CandleReader.vue
index 01892ba..c8513b4 100644
--- a/src/CandleReader.vue
+++ b/src/CandleReader.vue
@@ -3,8 +3,8 @@
           :book_url="book_url" :display_url="display_url"
           :debug="debug" :themes_css="themes_css"
           :initial_book_id="book_id"
-          :audiobook_edition_id="audiobook_edition_id"
-          :audiobook_manifest_url="audiobook_manifest_url"
+          :annotation_callbacks="annotation_callbacks"
+          :audiobook_callbacks="audiobook_callbacks"
           />
 </template>
 
@@ -36,13 +36,13 @@ export default {
       type: [Number, String],
       default: null
     },
-    audiobook_edition_id: {
-      type: [Number, String],
+    annotation_callbacks: {
+      type: Object,
       default: null
     },
-    audiobook_manifest_url: {
-      type: String,
-      default: ''
+    audiobook_callbacks: {
+      type: Object,
+      default: null
     }
   },
   data: () => ({
diff --git a/src/annotations.js b/src/annotations.js
new file mode 100644
index 0000000..63d6138
--- /dev/null
+++ b/src/annotations.js
@@ -0,0 +1,225 @@
+const STORAGE_PREFIX = 'candle-reader:annotations:v1:'
+const PAGE_SIZE = 20
+const LOCAL_USER = { id: 'local', nickname: '我', avatar: '' }
+// 宿主必须提供的回调；其余回调缺失时，对应功能给出明确错误而不是静默降级到本地。
+const REQUIRED = ['load', 'save']
+
+function annotationIdentity(annotation) {
+  return annotation.client_id || annotation.id
+}
+
+function createClientId() {
+  if (window.crypto?.randomUUID) return window.crypto.randomUUID()
+  return `candle-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+}
+
+function normalizeLoadedAnnotations(result) {
+  const annotations = Array.isArray(result) ? result : result?.annotations
+  if (!Array.isArray(annotations)) throw new Error('读取评论的回调必须返回数组或 { annotations }')
+  return annotations
+}
+
+function normalizeSavedAnnotation(result) {
+  const annotation = result?.annotation || result
+  if (!annotation || typeof annotation !== 'object' || Array.isArray(annotation)) {
+    throw new Error('写入评论的回调必须返回评论对象或 { annotation }')
+  }
+  return annotation
+}
+
+function normalizePage(result) {
+  const items = Array.isArray(result) ? result : result?.items
+  if (!Array.isArray(items)) throw new Error('评论列表回调必须返回数组或 { items, next_cursor, has_more }')
+  const next = Array.isArray(result) ? null : result.next_cursor ?? null
+  return { items, next_cursor: next, has_more: Array.isArray(result) ? false : Boolean(result.has_more ?? next) }
+}
+
+function storageKey(bookId, bookUrl) {
+  const identity = bookId || bookUrl || 'unknown-book'
+  return `${STORAGE_PREFIX}${encodeURIComponent(String(identity))}`
+}
+
+function paginate(records, cursor, limit) {
+  const start = Number(cursor) || 0
+  const size = Number(limit) || PAGE_SIZE
+  const end = start + size
+  return { items: records.slice(start, end), next_cursor: end < records.length ? String(end) : null, has_more: end < records.length }
+}
+
+// 未注入宿主回调时的本地实现：只有当前浏览器这一位读者，公开范围不会真的对他人生效。
+export function createLocalAnnotationCallbacks({ bookId, bookUrl, storage } = {}) {
+  const key = storageKey(bookId, bookUrl)
+  let localStorage = storage
+  if (localStorage === undefined) {
+    try {
+      localStorage = window.localStorage
+    } catch (error) {
+      throw new Error('浏览器禁止访问本地存储，无法保存评论')
+    }
+  }
+  if (!localStorage) throw new Error('浏览器不支持本地存储，无法保存评论')
+
+  function readAll() {
+    try {
+      const value = JSON.parse(localStorage.getItem(key) || '[]')
+      return Array.isArray(value) ? value : []
+    } catch (error) {
+      console.warn('Candle Reader 本地评论损坏，已忽略：', error)
+      return []
+    }
+  }
+
+  function writeAll(annotations) {
+    localStorage.setItem(key, JSON.stringify(annotations))
+  }
+
+  function decorate(annotation, all) {
+    return {
+      like_count: 0,
+      dislike_count: 0,
+      user_vote: 0,
+      ...annotation,
+      is_mine: true,
+      author_name: LOCAL_USER.nickname,
+      reply_count: annotation.root_id ? 0 : all.filter(item => item.root_id === annotation.id).length,
+    }
+  }
+
+  const newestFirst = (a, b) => String(b.created_at).localeCompare(String(a.created_at))
+
+  return {
+    async user() {
+      return LOCAL_USER
+    },
+    async load({ chapter } = {}) {
+      const annotations = readAll().filter(annotation => !annotation.root_id)
+      if (!chapter) return annotations
+      return annotations.filter(annotation => annotation.chapter === chapter)
+    },
+    async list({ scope = 'chapter', chapter, paragraph_cfi: paragraphCfi, cursor, limit } = {}) {
+      const all = readAll()
+      const top = all.filter(annotation => !annotation.root_id).filter(annotation => {
+        if (scope === 'mine') return true
+        if (annotation.is_private !== false) return false
+        if (scope === 'book') return true
+        if (annotation.annotation_type === 'book_comment' || annotation.chapter !== chapter) return false
+        return scope !== 'paragraph' || annotation.cfi === paragraphCfi
+      }).sort(newestFirst)
+      const page = paginate(top, cursor, limit)
+      return { ...page, items: page.items.map(annotation => decorate(annotation, all)) }
+    },
+    async summary({ chapter } = {}) {
+      const counts = {}
+      readAll().forEach(annotation => {
+        if (annotation.root_id || annotation.is_private !== false || annotation.chapter !== chapter) return
+        if (annotation.annotation_type !== 'note' || !annotation.cfi) return
+        counts[annotation.cfi] = (counts[annotation.cfi] || 0) + 1
+      })
+      return Object.entries(counts).map(([cfi, count]) => ({ paragraph_cfi: cfi, count }))
+    },
+    async get({ id }) {
+      const all = readAll()
+      const annotation = all.find(item => item.id === id)
+      if (!annotation) throw new Error('这条评论已不存在')
+      return decorate(annotation, all)
+    },
+    async replies({ root_id: rootId, cursor, limit } = {}) {
+      const all = readAll()
+      const replies = all.filter(annotation => annotation.root_id === rootId).sort((a, b) => newestFirst(b, a))
+      const page = paginate(replies, cursor, limit)
+      return { ...page, items: page.items.map(annotation => decorate(annotation, all)) }
+    },
+    async save(input) {
+      const now = new Date().toISOString()
+      const annotations = readAll()
+      const identity = annotationIdentity(input) || createClientId()
+      const index = annotations.findIndex(annotation => annotationIdentity(annotation) === identity)
+      const previous = index >= 0 ? annotations[index] : null
+      const annotation = {
+        ...previous,
+        ...input,
+        id: previous?.id || input.id || identity,
+        client_id: input.client_id || previous?.client_id || identity,
+        created_at: previous?.created_at || input.created_at || now,
+        updated_at: now,
+      }
+      if (annotation.root_id && !previous) {
+        const target = annotations.find(item => item.id === annotation.reply_to_id && item.root_id === annotation.root_id)
+        annotation.thread_id = target ? target.thread_id || target.id : null
+        annotation.reply_to_name = target ? LOCAL_USER.nickname : ''
+      }
+      if (index >= 0) annotations.splice(index, 1, annotation)
+      else annotations.push(annotation)
+      writeAll(annotations)
+      return decorate(annotation, annotations)
+    },
+    async remove({ id }) {
+      // 真删除：主评论连同全部回复，第一层回复连同其下回复。
+      writeAll(readAll().filter(item => item.id !== id && item.root_id !== id && item.thread_id !== id))
+      return { id }
+    },
+    async vote({ id, value }) {
+      const annotations = readAll()
+      const annotation = annotations.find(item => item.id === id)
+      if (!annotation) throw new Error('这条评论已不存在')
+      annotation.user_vote = value
+      annotation.like_count = value === 1 ? 1 : 0
+      annotation.dislike_count = value === -1 ? 1 : 0
+      writeAll(annotations)
+      return { like_count: annotation.like_count, dislike_count: annotation.dislike_count, user_vote: value }
+    },
+  }
+}
+
+export function createAnnotationCallbacks({ callbacks, bookId, bookUrl, storage } = {}) {
+  const injected = callbacks != null
+  if (injected && REQUIRED.some(name => typeof callbacks[name] !== 'function')) {
+    throw new Error('annotation_callbacks 必须同时提供 load 和 save 函数')
+  }
+  const implementation = injected ? callbacks : createLocalAnnotationCallbacks({ bookId, bookUrl, storage })
+  const context = { book_id: bookId || null, book_url: bookUrl || '' }
+  const call = (name, query = {}) => {
+    if (typeof implementation[name] !== 'function') throw new Error(`宿主未提供 ${name} 回调，无法完成该操作`)
+    return implementation[name]({ ...context, ...query }, context)
+  }
+
+  return {
+    source: injected ? 'callback' : 'localStorage',
+    async user() {
+      return implementation.user ? (await call('user')) || null : null
+    },
+    async login() {
+      if (implementation.login) await call('login')
+    },
+    async load(query = {}) {
+      return normalizeLoadedAnnotations(await call('load', query))
+    },
+    async list(query = {}) {
+      return normalizePage(await call('list', query))
+    },
+    async summary(query = {}) {
+      const result = await call('summary', query)
+      const items = Array.isArray(result) ? result : result?.items
+      return Array.isArray(items) ? items : []
+    },
+    async get(query) {
+      return normalizeSavedAnnotation(await call('get', query))
+    },
+    async replies(query = {}) {
+      return normalizePage(await call('replies', query))
+    },
+    async save(annotation) {
+      return normalizeSavedAnnotation(await implementation.save({ ...annotation }, context))
+    },
+    async remove(query) {
+      return call('remove', query)
+    },
+    async vote(query) {
+      const result = await call('vote', query)
+      if (!result || typeof result !== 'object') throw new Error('投票回调必须返回 { like_count, dislike_count, user_vote }')
+      return result
+    },
+  }
+}
+
+export { createClientId }
diff --git a/src/audiobook.js b/src/audiobook.js
new file mode 100644
index 0000000..306f54b
--- /dev/null
+++ b/src/audiobook.js
@@ -0,0 +1,42 @@
+// 有声书回调：清单、时间轴和收听进度都由宿主提供，阅读器不直接请求任何接口。契约见 DESIGN.md。
+const REQUIRED = ['manifest', 'timeline']
+
+export function createAudiobookRepository({ callbacks, bookId, bookUrl } = {}) {
+  if (!callbacks) return null
+  if (REQUIRED.some(name => typeof callbacks[name] !== 'function')) {
+    throw new Error('audiobook_callbacks 必须同时提供 manifest 和 timeline 函数')
+  }
+  const context = { book_id: bookId || null, book_url: bookUrl || '' }
+  const call = (name, query = {}) => callbacks[name]({ ...context, ...query })
+  const has = name => typeof callbacks[name] === 'function'
+
+  return {
+    // → { manifest: { id, chapters: [...] }, progress: { chapter_id, position_ms, version } | null }
+    async manifest() {
+      const result = await call('manifest')
+      const manifest = result?.manifest
+      if (!manifest?.chapters?.length) throw new Error('当前书籍没有可播放章节')
+      return { manifest, progress: result.progress || null }
+    },
+    // → 时间轴片段数组；宿主可以返回数组、{ segments } 或 { timeline: { segments } }
+    async timeline(query) {
+      const result = await call('timeline', query)
+      const segments = Array.isArray(result) ? result : result?.segments || result?.timeline?.segments
+      return Array.isArray(segments) ? segments : []
+    },
+    // 收听进度三个回调都是可选的；宿主不提供时只在本机记住位置。
+    async startSession(query) {
+      if (!has('start_session')) return ''
+      const result = await call('start_session', query)
+      return String(result?.session_id || '')
+    },
+    async reportProgress(query) {
+      if (!has('report_progress')) return null
+      const result = await call('report_progress', query)
+      return result?.version ?? null
+    },
+    async endSession(query) {
+      if (has('end_session')) await call('end_session', query)
+    },
+  }
+}
diff --git a/src/components/AudiobookPlayer.vue b/src/components/AudiobookPlayer.vue
index 659d85e..67a07a1 100644
--- a/src/components/AudiobookPlayer.vue
+++ b/src/components/AudiobookPlayer.vue
@@ -97,10 +97,11 @@ import {
 
 const props = defineProps({
   visible: { type: Boolean, default: false },
-  editionId: { type: [Number, String], default: null },
-  manifestUrl: { type: String, default: '' },
+  // 宿主回调的包装（src/audiobook.js）
+  repository: { type: Object, required: true },
+  // 本机记住收听位置用的键，通常是书的 id
+  storageId: { type: [Number, String], default: '' },
   rendition: { type: Object, default: null },
-  request: { type: Function, required: true },
 })
 
 const emit = defineEmits(['close', 'segment-change'])
@@ -132,10 +133,10 @@ let lastProgressClock = 0
 
 const chapters = computed(() => manifest.value?.chapters || [])
 const chapterIndex = computed(() => chapters.value.findIndex(item => item.id === chapter.value?.id))
-const storageKey = computed(() => `candle:audiobook:${props.editionId || 'manifest'}`)
+const storageKey = computed(() => `candle:audiobook:${props.storageId || 'manifest'}`)
 
 watch(
-  () => [props.visible, props.editionId, props.manifestUrl],
+  () => [props.visible, props.repository],
   ([visible]) => {
     if (visible) void loadManifest()
   },
@@ -151,12 +152,8 @@ watch(
   { immediate: true },
 )
 
-function manifestEndpoint() {
-  return props.manifestUrl || (props.editionId ? `/api/audiobooks/${props.editionId}/manifest` : '')
-}
-
 function loadManifest() {
-  if (manifest.value || !manifestEndpoint()) return Promise.resolve()
+  if (manifest.value || !props.repository) return Promise.resolve()
   if (manifestPromise) return manifestPromise
   manifestPromise = loadManifestOnce().finally(() => {
     manifestPromise = null
@@ -168,10 +165,7 @@ async function loadManifestOnce() {
   loading.value = true
   error.value = ''
   try {
-    const response = await props.request(manifestEndpoint())
-    if (response.err !== 'ok' || !response.manifest?.chapters?.length) {
-      throw new Error(response.msg || '当前书籍没有可播放章节')
-    }
+    const response = await props.repository.manifest()
     manifest.value = response.manifest
     progressVersion.value = response.progress?.version || 0
 
@@ -190,9 +184,13 @@ async function loadManifestOnce() {
 }
 
 async function loadTimeline(target) {
-  const endpoint = target.timeline_url || `/api/audiobooks/${manifest.value.id}/chapters/${target.number}/timeline`
-  const response = await props.request(endpoint)
-  timeline.value = response.err === 'ok' ? (response.timeline?.segments || []) : []
+  try {
+    timeline.value = await props.repository.timeline({ manifest_id: manifest.value.id, chapter: target })
+  } catch (cause) {
+    // 没有时间轴也能播放，只是不能跟随高亮。
+    console.warn('有声书时间轴加载失败：', cause)
+    timeline.value = []
+  }
 }
 
 async function loadChapter(target, { startMs = 0, autoplay = false, navigate = true } = {}) {
@@ -235,12 +233,11 @@ async function navigateToChapter(target) {
 
 async function ensureSession() {
   if (sessionId.value || !manifest.value) return
-  const response = await props.request(`/api/audiobooks/${manifest.value.id}/sessions`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ source: 'candle', device_id: 'candle-reader' }),
-  })
-  if (response.err === 'ok') sessionId.value = response.session_id || ''
+  try {
+    sessionId.value = await props.repository.startSession({ manifest_id: manifest.value.id, source: 'candle', device_id: 'candle-reader' })
+  } catch (cause) {
+    console.warn('有声书收听会话创建失败：', cause)
+  }
 }
 
 async function startPlayback() {
@@ -459,20 +456,21 @@ async function reportProgress(force = false, completed = false) {
   const delta = playing.value && lastProgressClock ? Math.min(60000, Math.max(0, now - lastProgressClock)) : 0
   if (!force && delta < 9000) return
   lastProgressClock = now
-  const response = await props.request(`/api/audiobook-sessions/${sessionId.value}`, {
-    method: 'PATCH',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
+  try {
+    const version = await props.repository.reportProgress({
+      session_id: sessionId.value,
       chapter_id: chapter.value.id,
       position_ms: positionMs.value,
       segment_id: activeSegment.value?.id || '',
       listened_delta_ms: delta,
       completed,
       version: progressVersion.value,
-    }),
-  })
-  if (response.err === 'ok') progressVersion.value = response.version || progressVersion.value
-  else if (response.err === 'progress.conflict') progressVersion.value = response.version || progressVersion.value
+    })
+    // 版本冲突时宿主同样返回最新版本号，下次上报以它为准。
+    if (version) progressVersion.value = version
+  } catch (cause) {
+    console.warn('有声书收听进度上报失败：', cause)
+  }
 }
 
 function readSavedState() {
@@ -510,7 +508,7 @@ onBeforeUnmount(() => {
   stopTimers()
   props.rendition?.off?.('rendered', onRenditionRendered)
   clearCurrentHighlight()
-  if (sessionId.value) void props.request(`/api/audiobook-sessions/${sessionId.value}`, { method: 'POST' })
+  if (sessionId.value) props.repository.endSession({ session_id: sessionId.value }).catch(cause => console.warn('有声书收听会话结束失败：', cause))
 })
 
 defineExpose({ loadManifest, playFromSelection, returnToNarration, suspendFollow })
diff --git a/src/components/BookComments.vue b/src/components/BookComments.vue
deleted file mode 100644
index 9e37045..0000000
--- a/src/components/BookComments.vue
+++ /dev/null
@@ -1,68 +0,0 @@
-<template>
-  <v-card>
-    <v-row>
-      <v-col offset="2" cols="8" class="text-center">
-        <h4 class="mt-3">评论列表</h4>
-      </v-col>
-      <v-col cols="2">
-        <v-btn variant="plain" icon="mdi-close" @click="$emit('close')" title="关闭评论面板"></v-btn>
-      </v-col>
-    </v-row>
-    <v-divider></v-divider>
-    <v-list  v-if="comments.length == 0"  density="compact">
-      <v-list-item class="my-4">
-        <v-list-item-title class="text-center">尚未有人发表评论</v-list-item-title>
-      </v-list-item>
-    </v-list>
-    <v-list v-else id='book-comments' density="compact">
-      <template v-for="c in comments">
-        <v-list-item class="pr-0 align-self-start mb-4" :prepend-avatar="c.avatar" append-icon="mdi-thumb-up"
-          :subtitle="c.nickName">
-          {{ c.content }}
-          <v-list-item-subtitle>{{ c.level }}楼 * {{ c.createTime }} * {{ c.geo }}</v-list-item-subtitle>
-          <template v-slot:prepend>
-            <v-avatar variant="outlined" size=large color="grey" class="text-center" :icon="c.avatar"></v-avatar>
-          </template>
-          <template v-slot:append>
-            <v-btn class="px-0" size=small variant=plain stacked prepend-icon="mdi-thumb-up" title="点赞">{{ c.likeCount }}</v-btn>
-          </template>
-        </v-list-item>
-      </template>
-    </v-list>
-    <v-card-text class="my-2 py-0 px-2">
-      <v-btn @click="$emit('login')" variant=text style="width: 100%" v-if="!login">点击登录，发表评论</v-btn>
-      <v-row v-else>
-        <v-col cols=9>
-          <v-text-field v-model="content" density="compact" single-line hide-details placeholder="爱书之人，维持良好的社区氛围"></v-text-field>
-        </v-col>
-        <v-col cols=3>
-          <v-btn @click="$emit('add_review', this.content)">发表</v-btn>
-        </v-col>
-      </v-row>
-    </v-card-text>
-  </v-card>
-</template>
-
-<script>
-export default {
-  name: 'BookComments',
-  computed: {
-  },
-  mounted: function () {
-  },
-  methods: {
-  },
-  props: ["login", "comments"],
-  data: () => ({
-    content: "",
-  })
-}
-
-</script>
-
-<style>
-#book-comments .v-list-item__append,
-#book-comments .v-list-item__prepend {
-  align-self: flex-start
-}
-</style>
diff --git a/src/components/BookReview.vue b/src/components/BookReview.vue
deleted file mode 100644
index 3fd1f40..0000000
--- a/src/components/BookReview.vue
+++ /dev/null
@@ -1,162 +0,0 @@
-<template>
-  <v-card class="book-review-card">
-    <!-- 标题栏 -->
-    <v-row no-gutters class="br-fixed align-center">
-      <v-col offset="2" cols="8" class="text-center">
-        <h4 class="mt-3">本书评论</h4>
-      </v-col>
-      <v-col cols="2" class="text-right">
-        <v-btn variant="plain" icon="mdi-close" @click="$emit('close')" title="关闭评论面板"></v-btn>
-      </v-col>
-    </v-row>
-
-    <!-- 用户态：仅登录后显示昵称 + 设置入口（未登录时登录入口在面板底部） -->
-    <template v-if="user">
-      <v-list-item class="br-fixed" :title="user.nickName || user.nickname" :subtitle="user.email"
-        @click="$emit('open-settings')">
-        <template #prepend>
-          <v-avatar v-if="user.avatar" :image="user.avatar"></v-avatar>
-          <v-avatar v-else :color="avatar_color(user.id)">
-            <span class="text-white">{{ avatar_text(user.nickName || user.nickname) }}</span>
-          </v-avatar>
-        </template>
-        <template #append>
-          <v-icon title="用户设置">mdi-cog-outline</v-icon>
-        </template>
-      </v-list-item>
-      <v-divider class="br-fixed"></v-divider>
-    </template>
-
-    <!-- 最新 / 热门：排序由后端完成，切换时通知父组件重新拉取 -->
-    <v-tabs class="br-fixed" :model-value="sort" @update:model-value="$emit('update:sort', $event)" density="compact" grow>
-      <v-tab value="latest">最新</v-tab>
-      <v-tab value="hot">热门</v-tab>
-    </v-tabs>
-    <v-divider class="br-fixed"></v-divider>
-
-    <!-- 评论列表：面板内唯一滚动区 -->
-    <div class="br-list">
-      <v-list v-if="comments.length === 0" density="compact">
-        <v-list-item class="my-4">
-          <v-list-item-title class="text-center text-medium-emphasis">尚未有人发表评论</v-list-item-title>
-        </v-list-item>
-      </v-list>
-      <v-list v-else id="book-review-list" density="compact">
-        <template v-for="c in comments" :key="c.reviewId">
-          <v-list-item class="pr-0 align-self-start mb-4" :subtitle="c.nickName">
-            {{ c.content }}
-            <div v-if="c.referText" class="br-refer text-caption text-medium-emphasis"
-              :class="{ 'br-refer--link': c.cfi }" @click.stop="c.cfi && $emit('jump', c.cfi)">{{ c.referText }}</div>
-            <v-list-item-subtitle>{{ c.level }}楼 · {{ c.createTime }} · {{ c.geo }}</v-list-item-subtitle>
-            <template #prepend>
-              <v-avatar v-if="c.avatar" :image="c.avatar" size="30"></v-avatar>
-              <v-avatar v-else size="30" :color="avatar_color(c.userId)">
-                <span class="text-white text-caption">{{ avatar_text(c.nickName) }}</span>
-              </v-avatar>
-            </template>
-            <template #append>
-              <v-btn class="px-0" size="small" variant="plain" stacked prepend-icon="mdi-thumb-up" title="点赞">{{ c.likeCount }}</v-btn>
-            </template>
-          </v-list-item>
-        </template>
-      </v-list>
-    </div>
-
-    <!-- 底部：未登录显示登录按钮，登录后显示发表输入框 -->
-    <v-card-text class="br-fixed my-2 py-0 px-2">
-      <v-btn v-if="!login" @click="$emit('login')" variant="text" style="width: 100%">点击登录，发表评论</v-btn>
-      <v-row v-else no-gutters class="align-center">
-        <v-col cols="9">
-          <v-text-field v-model="content" density="compact" single-line hide-details placeholder="爱书之人，维持良好的社区氛围"></v-text-field>
-        </v-col>
-        <v-col cols="3" class="text-right">
-          <v-btn @click="submit">发表</v-btn>
-        </v-col>
-      </v-row>
-    </v-card-text>
-  </v-card>
-</template>
-
-<script>
-export default {
-  name: 'BookReview',
-  props: ['login', 'user', 'comments', 'sort'],
-  data: () => ({
-    content: '',
-  }),
-  methods: {
-    submit: function () {
-      const text = this.content.trim();
-      if (!text) return;
-      this.$emit('add', text);
-      this.content = '';
-    },
-    // 无头像时按 user_id 稳定哈希，从调色板里取一个默认彩色头像
-    avatar_color: function (id) {
-      const palette = ['#F2709C', '#FF9472', '#7B8FF7', '#42C2A8', '#FBC531', '#9B7EDE', '#4A9DEC', '#EE6C6C'];
-      const s = String(id || 0);
-      let h = 0;
-      for (let i = 0; i < s.length; i++) {
-        h = (h * 31 + s.charCodeAt(i)) >>> 0;
-      }
-      return palette[h % palette.length];
-    },
-    avatar_text: function (name) {
-      const n = (name || '').trim();
-      return n ? n[0] : '书';
-    },
-  },
-}
-</script>
-
-<style scoped>
-/* 卡片做成 flex 列：标题/用户行/Tab/输入固定，唯有评论列表滚动 */
-.book-review-card {
-  display: flex;
-  flex-direction: column;
-  overflow: hidden; /* 卡片本身不滚动，避免与列表双重滚动条 */
-}
-
-.br-fixed {
-  flex: 0 0 auto;
-}
-
-.br-list {
-  flex: 1 1 auto;
-  min-height: 0; /* 允许在 flex 中收缩，从而触发内部滚动 */
-  overflow-y: auto;
-}
-
-/* 列表内的 v-list 交给 .br-list 滚动，自身不再产生滚动条 */
-.br-list :deep(.v-list) {
-  overflow: visible;
-}
-
-/* 评论引用的书籍正文：一行小字，左边框引用样式，过长省略 */
-.br-refer {
-  margin: 4px 0;
-  padding: 2px 8px;
-  border-left: 3px solid rgba(128, 128, 128, 0.4);
-  background: rgba(128, 128, 128, 0.1);
-  border-radius: 2px;
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  line-height: 1.7;
-}
-
-/* 有 cfi 时可点击跳转到正文位置 */
-.br-refer--link {
-  cursor: pointer;
-}
-.br-refer--link:hover {
-  background: rgba(128, 128, 128, 0.18);
-}
-</style>
-
-<style>
-#book-review-list .v-list-item__append,
-#book-review-list .v-list-item__prepend {
-  align-self: flex-start;
-}
-</style>
diff --git a/src/components/BookToc.vue b/src/components/BookToc.vue
index 8efb245..531c1de 100644
--- a/src/components/BookToc.vue
+++ b/src/components/BookToc.vue
@@ -109,10 +109,12 @@ export default {
                 return href.split('#')[0];
             };
             
-            const currentHref = normalizeHref(this.currentChapter.href);
-            const itemHref = normalizeHref(item.href);
-            
-            return currentHref === itemHref;
+            // 一个正文文件里有多章时，目录项靠锚点区分：两边都带锚点就按完整地址比较，
+            // 否则同一文件里的每一章都会被当成当前章节。
+            const current = this.currentChapter.href || '';
+            const target = item.href || '';
+            if (current.includes('#') && target.includes('#')) return current === target;
+            return normalizeHref(current) === normalizeHref(target);
         },
         scrollToCurrentChapter: function() {
             // 滚动到当前章节
diff --git a/src/components/EpubReader.vue b/src/components/EpubReader.vue
index 455034c..a20f008 100644
--- a/src/components/EpubReader.vue
+++ b/src/components/EpubReader.vue
@@ -11,12 +11,13 @@
     </template>
       {{ is_debug_signal ? alert_msg : book_title }}
       <v-spacer></v-spacer>
-      <v-btn icon title="更多选项"> <v-icon>mdi-dots-vertical</v-icon> </v-btn>
+      <v-btn v-if="has_audiobook" min-height="44" @click="open_audiobook" title="听书"><v-icon>mdi-headphones</v-icon><span>听书</span></v-btn>
+      <v-btn ref="panelEntryAi" icon title="更多选项" @click="set_menu('ai')"> <v-icon>mdi-dots-vertical</v-icon> </v-btn>
     </v-app-bar>
 
     <!-- 底部菜单 -->
     <v-bottom-navigation v-model="menu.value" :active="menu.show_navbar" z-index="2599">
-      <v-btn value="toc" @click="set_menu('toc')">
+      <v-btn ref="panelEntryToc" value="toc" @click="set_menu('toc')">
         <v-icon>mdi-book-open-variant-outline</v-icon>
         <span>目录</span>
       </v-btn>
@@ -26,86 +27,129 @@
         <span>{{ switch_theme_text }}</span>
       </v-btn>
 
-      <v-btn v-if="has_audiobook" @click="open_audiobook">
-        <v-icon>mdi-headphones</v-icon>
-        <span>听书</span>
+      <v-btn ref="panelEntryAnnotations" value="annotations" @click="on_open_annotations">
+        <v-icon>mdi-comment-text-outline</v-icon>
+        <span>评论</span>
       </v-btn>
 
-      <v-btn value="settings" @click="set_menu('settings')">
+      <v-btn ref="panelEntrySettings" value="settings" @click="set_menu('settings')">
         <v-icon>mdi-cog</v-icon>
         <span>设置</span>
       </v-btn>
 
-      <v-btn value="more" @click="on_open_comments">
-        <v-badge color="error" :content="unread_count" v-if="unread_count">
-          <v-icon>mdi-comment-text-multiple-outline</v-icon>
-        </v-badge>
-        <v-icon v-else>mdi-comment-text-multiple-outline</v-icon>
-        <span>评论</span>
-      </v-btn>
-
-      <v-btn value="ai" @click="set_menu('ai')">
-        <v-icon>mdi-face-man-shimmer</v-icon>
-        <span>AI</span>
-      </v-btn>
-
     </v-bottom-navigation>
 
     <audiobook-player
       v-if="has_audiobook"
       ref="audiobookPlayer"
       :visible="audiobook_open"
-      :edition-id="audiobook_edition_id"
-      :manifest-url="audiobook_manifest_url"
+      :repository="audiobook_repository"
+      :storage-id="initial_book_id || book_url"
       :rendition="rendition"
-      :request="audiobook_request"
       @close="audiobook_open = false"
     ></audiobook-player>
 
-    <v-bottom-sheet class="fixed mb-14" max-height="90%" v-model="menu.panels.settings" contained persistent z-index="234">
+    <v-bottom-sheet class="fixed mb-14 settings-bottom-sheet reader-side-right" :retain-focus="!is_wide_screen" max-height="90%" v-model="menu.panels.settings" @update:model-value="on_panel_model_update('settings', $event)" @after-leave="on_panel_after_leave('settings')" contained z-index="234">
       <settings :settings="settings" @update="update_settings" @open-themes="open_theme_dialog"></settings>
     </v-bottom-sheet>
 
-    <v-bottom-sheet class="fixed mb-14" max-height="90%" v-model="menu.panels.toc" contained close-on-content-click  z-index="234">
+    <v-bottom-sheet class="fixed mb-14 reader-side-left" :retain-focus="!is_wide_screen" max-height="90%" v-model="menu.panels.toc" @update:model-value="on_panel_model_update('toc', $event)" @after-leave="on_panel_after_leave('toc')" contained close-on-content-click  z-index="234">
       <book-toc ref="bookTocComponent" :meta="book_meta" :toc_items="toc_items" :current-chapter="current_toc" @click:select="on_click_toc"></book-toc>
     </v-bottom-sheet>
 
-    <v-bottom-sheet class="fixed mb-14" max-height="90%" v-model="menu.panels.more" contained z-index="234">
-      <book-review :user="user" :login="is_login" :comments="book_reviews" :sort="book_review_sort"
-        @close="set_menu('hide')" @login="show_login = true" @update:sort="on_change_book_review_sort"
-        @open-settings="show_user_center = true" @add="on_add_book_review" @jump="on_jump_review"></book-review>
-    </v-bottom-sheet>
-
-    <!-- 游客点「点击登录」时弹出，复用 Guest -->
-    <v-dialog v-model="show_login" max-width="500" z-index="2999">
-      <guest @login="on_book_login"></guest>
-    </v-dialog>
-
-    <!-- 已登录点 ⚙️ 时弹出用户设置/互动消息，复用 UserCenter -->
-    <v-bottom-sheet class="fixed mb-14" max-height="90%" v-model="show_user_center" contained z-index="234">
-      <user-center :messages="comments" :user="user" @update="on_login_user" @logout="on_book_logout"></user-center>
+    <!-- 评论抽屉（移动端 90% 高的底部抽屉，桌面端右侧侧边栏）。eager：选区和段尾气泡需要在首次打开前就能调用它。 -->
+    <v-bottom-sheet class="fixed mb-14 annotation-bottom-sheet reader-side-right" :retain-focus="!is_wide_screen" v-model="menu.panels.annotations" @update:model-value="on_panel_model_update('annotations', $event)" @after-leave="on_panel_after_leave('annotations')" contained eager z-index="234"
+      aria-label="评论">
+      <div class="annotation-sheet-body">
+        <reader-comments ref="comments" :repository="annotation_repository" :user="user" :chapter="comment_chapter" :active="menu.panels.annotations"
+          @write="on_write_comment" @edit="on_edit_comment" @login="request_login" @changed="on_comments_changed"
+          @feedback="show_annotation_feedback" @close="set_menu('hide')"></reader-comments>
+      </div>
     </v-bottom-sheet>
 
-    <v-bottom-sheet class="fixed mb-14" max-height="90%" v-model="menu.panels.comments" contained  z-index="234">
-      <book-comments :login="is_login" :comments="comments" @close="set_menu('hide')"
-        @login="set_menu('more')" @add_review="on_add_review"></book-comments>
-    </v-bottom-sheet>
+    <!-- 宽屏侧边栏（目录、评论、设置）的宽度调整条。放在面板浮层外面：浮层内容区会裁掉越过边框的部分。 -->
+    <panel-resizer v-if="side_panel" :key="side_panel.name" :side="side_panel.side" :label="`调整${side_panel.label}宽度`"
+      :width="panel_width(side_panel.name)" :min="PANEL_MIN_WIDTH" :max="panel_max_width"
+      @update:width="set_panel_width(side_panel.name, $event)" @commit="save_panel_widths" @reset="reset_panel_width(side_panel.name)"></panel-resizer>
 
-    <v-bottom-sheet class="fixed mb-14" max-height="90%" v-model="menu.panels.ai" contained z-index="234">
+    <v-bottom-sheet class="fixed mb-14" max-height="90%" v-model="menu.panels.ai" @update:model-value="on_panel_model_update('ai', $event)" @after-leave="on_panel_after_leave('ai')" contained z-index="234">
       <v-card title="开发中"></v-card>
     </v-bottom-sheet>
 
-    <!-- 浮动工具栏 -->
-    <div id="comments-toolbar" :style="`left: ${toolbar_left}px; top: ${toolbar_top}px;`">
-      <v-toolbar density="compact" border dense floating elevation="10" rounded>
-        <v-btn @click="on_click_toolbar_comments">发段评</v-btn>
-        <v-divider vertical></v-divider>
-        <v-btn @click="on_click_toolbar_listen">从这里听</v-btn>
-        <v-divider vertical></v-divider>
-        <v-btn>复制</v-btn>
-        <v-divider vertical></v-divider>
-        <v-btn>反馈</v-btn>
-      </v-toolbar>
+    <v-dialog v-model="annotation_editor_open" class="annotation-editor-dialog rc-above-standalone" max-width="560" :persistent="annotation_saving"
+      aria-labelledby="annotation-editor-title" @after-leave="on_annotation_editor_closed">
+      <v-card class="annotation-editor-card" color="surface">
+        <header class="annotation-editor-header">
+          <h2 id="annotation-editor-title">{{ annotation_editor_title }}</h2>
+          <v-btn icon="mdi-close" variant="text" size="small" aria-label="关闭评论编辑框"
+            min-width="44" min-height="44" :disabled="annotation_saving" @click="annotation_editor_open = false"></v-btn>
+        </header>
+        <v-card-text class="annotation-editor-body">
+          <section v-if="annotation_editor_quote" class="annotation-editor-reference" aria-labelledby="annotation-reference-title">
+            <div class="annotation-reference-heading">
+              <span id="annotation-reference-title">引用原文</span>
+              <span class="annotation-reference-chapter">{{ annotation_editor_location?.toc?.label || annotation_editor_record?.chapter || current_toc_title }}</span>
+            </div>
+            <blockquote class="annotation-editor-quote" tabindex="0" aria-label="引用原文">{{ annotation_editor_quote }}</blockquote>
+            <p class="annotation-editor-hint">{{ annotation_editor_location?.multi_paragraph ? '跨段选区 · 评论归属最后一段。' : '评论关联整个段落。' }}</p>
+          </section>
+          <p v-else class="annotation-editor-hint annotation-editor-book-hint">针对整本《{{ book_title }}》写下你的感受，发布后在「全书评论」中展示。</p>
+          <v-textarea ref="annotationEditorContent" v-model="annotation_editor_content" class="annotation-editor-input" label="评论内容"
+            variant="outlined" density="comfortable" rows="5" autofocus persistent-placeholder placeholder="写下你的想法…"
+            :readonly="annotation_saving" :error-messages="annotation_editor_error" @update:model-value="annotation_editor_error = ''"></v-textarea>
+        </v-card-text>
+        <footer class="annotation-editor-footer">
+          <div class="annotation-visibility-row">
+            <v-switch id="annotation-public-switch" class="annotation-visibility" :model-value="!annotation_editor_private"
+              :disabled="annotation_saving" role="switch" color="primary" density="comfortable" inset hide-details
+              aria-labelledby="annotation-public-label" aria-describedby="annotation-visibility-hint"
+              @update:model-value="annotation_editor_private = !$event"></v-switch>
+            <label id="annotation-public-label" for="annotation-public-switch" class="annotation-visibility-label"
+              :class="{ 'annotation-visibility-label-disabled': annotation_saving }">公开这条评论</label>
+          </div>
+          <p id="annotation-visibility-hint" class="annotation-editor-hint annotation-visibility-hint" aria-live="polite">
+            {{ annotation_repository?.source === 'localStorage'
+              ? '仅保存在当前浏览器，公开范围暂不生效。'
+              : annotation_editor_private ? '只有你能看到这条评论。' : '其他读者可以在对应评论范围看到这条评论。' }}
+          </p>
+          <v-card-actions class="annotation-editor-actions">
+            <v-spacer></v-spacer>
+            <v-btn variant="text" :disabled="annotation_saving" @click="annotation_editor_open = false">取消</v-btn>
+            <v-btn variant="flat" color="primary" :loading="annotation_saving" @click="save_note">保存</v-btn>
+          </v-card-actions>
+        </footer>
+      </v-card>
+    </v-dialog>
+
+    <v-snackbar v-model="annotation_feedback_visible" class="annotation-feedback" :color="annotation_feedback_error ? 'error' : 'primary'"
+      :timeout="annotation_feedback_error ? -1 : 5000">
+      {{ annotation_feedback_message }}
+      <template v-slot:actions><v-btn variant="text" @click="annotation_feedback_visible = false">关闭</v-btn></template>
+    </v-snackbar>
+
+    <!-- 选区预览只表示当前选择，保存成功后才绘制永久标记。 -->
+    <div v-for="(rect, index) in selection_preview_rects" :key="index" class="selection-preview" :style="rect" aria-hidden="true"></div>
+
+    <!-- 文字选择工具栏：划线与评论 UI 完全由阅读器负责，宿主只注入数据回调。 -->
+    <div v-show="is_toolbar_visible()" id="comments-toolbar" ref="selectionToolbar" role="group"
+      aria-label="选中文字操作" :style="`left: ${toolbar_left}px; top: ${toolbar_top}px;`">
+      <div class="selection-toolbar-actions">
+        <v-btn class="selection-toolbar-action" variant="text" @click="copy_selection">
+          <v-icon size="18" aria-hidden="true">mdi-content-copy</v-icon><span>复制</span>
+        </v-btn>
+        <v-btn class="selection-toolbar-action" variant="text" :loading="annotation_saving" @click="save_highlight">
+          <v-icon size="18" aria-hidden="true">mdi-format-underline</v-icon><span>划线</span>
+        </v-btn>
+        <v-btn class="selection-toolbar-action" variant="text" :disabled="annotation_saving || !selected_location.paragraph_cfi" @click="open_note_editor">
+          <v-icon size="18" aria-hidden="true">mdi-square-edit-outline</v-icon><span>写评论</span>
+        </v-btn>
+        <v-btn class="selection-toolbar-action" variant="text" :disabled="annotation_saving || !selected_location.paragraph_cfi" @click="on_view_selection_notes">
+          <v-icon size="18" aria-hidden="true">mdi-comment-text-outline</v-icon><span>看本段评论</span>
+        </v-btn>
+        <v-btn v-if="has_audiobook" class="selection-toolbar-action" variant="text" @click="on_click_toolbar_listen">
+          <v-icon size="18" aria-hidden="true">mdi-headphones</v-icon><span>从这里听</span>
+        </v-btn>
+      </div>
     </div>
 
     <!-- 阅读界面 -->
@@ -114,16 +158,16 @@
         <v-progress-circular indeterminate size="64" color="primary"></v-progress-circular>
       </v-overlay>
 
-      <!-- 加载超时提示框 -->
-      <v-dialog v-model="showTimeoutDialog" max-width="500px">
+      <!-- 加载较慢 / 加载失败提示框：加载慢时不中断，加载完成后自动关闭 -->
+      <v-dialog v-model="showTimeoutDialog" max-width="500px" aria-labelledby="load-dialog-title">
         <v-card>
-          <v-card-title class="text-h5 text-center">加载超时</v-card-title>
+          <v-card-title id="load-dialog-title" class="text-h5 text-center">{{ load_failed ? '加载失败' : '加载较慢' }}</v-card-title>
           <v-card-text class="text-center">
-            电子书加载超时，可能是网络问题或文件格式不支持。
+            {{ load_failed ? '电子书加载失败，可能是网络问题或文件格式不支持。' : '电子书还在加载，可能是网络较慢。加载完成后此提示会自动关闭。' }}
           </v-card-text>
           <v-card-actions class="justify-center">
             <v-btn color="primary" variant="text" @click="showTimeoutDialog = false">
-              关闭
+              {{ load_failed ? '关闭' : '继续等待' }}
             </v-btn>
             <v-btn color="primary" variant="flat" @click="retryLoad">
               重试
@@ -181,24 +225,37 @@
 </template>
 
 <script>
+/* global ePub */
+import { markRaw } from 'vue'
+import { normalizeNoteSettings } from '@/note-settings'
 import Settings from './Settings.vue'
 import BookToc from './BookToc.vue'
-import Guest from './Guest.vue'
-import UserCenter from './UserCenter.vue'
-import BookComments from './BookComments.vue'
-import BookReview from './BookReview.vue'
+import ReaderComments from './comments/ReaderComments.vue'
 import AudiobookPlayer from './AudiobookPlayer.vue'
+import PanelResizer from './PanelResizer.vue'
+import { createAnnotationCallbacks, createClientId } from '@/annotations'
+import { createAudiobookRepository } from '@/audiobook'
 import { THEMES, getTheme } from '@/themes'
 
+const PUBLIC_PREFERENCE_KEY = 'candle-reader:comment-public'
+const PANEL_WIDTHS_KEY = 'candle-reader:panel-widths'
+const PANEL_MIN_WIDTH = 260
+// 宽屏下以侧边栏显示的面板：所在一侧、默认宽度和界面上的称呼。
+const SIDE_PANELS = {
+  toc: { side: 'left', width: 300, label: '目录' },
+  annotations: { side: 'right', width: 420, label: '评论' },
+  settings: { side: 'right', width: 380, label: '设置' },
+}
+// 网速慢时（如 3Mbps 下首次打开要下载十几 MB）正文可能要半分钟以上才出来，超过这个时间才提示「加载较慢」。
+const LOAD_TIMEOUT_MS = 60000
+
 export default {
   name: 'EpubReader',
   components: {
+    PanelResizer,
     Settings,
     BookToc,
-    Guest,
-    UserCenter,
-    BookComments,
-    BookReview,
+    ReaderComments,
     AudiobookPlayer
   },
   props: {
@@ -207,12 +264,33 @@ export default {
     debug: { type: Boolean, default: false },
     themes_css: { type: String, default: 'theme.css' },
     initial_book_id: { type: [Number, String], default: null },
-    audiobook_edition_id: { type: [Number, String], default: null },
-    audiobook_manifest_url: { type: String, default: '' },
+    annotation_callbacks: { type: Object, default: null },
+    audiobook_callbacks: { type: Object, default: null },
   },
   computed: {
+    // 「显示全部划线和评论」：正文里的划线标记与段尾评论气泡。
+    comments_enabled: function () { return this.settings.show_comments; },
+    // 宽屏下正在显示的侧边栏；手机上的底部抽屉没有宽度可调。
+    side_panel: function () {
+      const panel = SIDE_PANELS[this.menu.current_panel];
+      return this.is_wide_screen && panel && this.menu.panels[this.menu.current_panel] ? { name: this.menu.current_panel, ...panel } : null;
+    },
+    // 侧边栏最宽不超过 720px，并给正文至少留出 360px。
+    panel_max_width: function () {
+      return Math.max(PANEL_MIN_WIDTH, Math.min(720, this.window_width - 360));
+    },
+    comment_chapter: function () { return String(this.current_toc?.label || this.current_toc_title || '').trim(); },
+    annotation_editor_title: function () {
+      if (this.annotation_editor_record) return '编辑评论';
+      return this.annotation_editor_type === 'book_comment' ? '写整书评论' : '写评论';
+    },
+    annotation_editor_quote: function () {
+      const location = this.annotation_editor_location;
+      if (location) return location.multi_paragraph ? location.quote_text : location.paragraph_quote_text;
+      return this.annotation_editor_record?.quote_text || '';
+    },
     has_audiobook: function () {
-      return Boolean(this.audiobook_edition_id || this.audiobook_manifest_url);
+      return Boolean(this.audiobook_repository);
     },
     switch_theme_icon: function () {
       // 当前是白天主题则显示「切换到夜晚」的图标，反之亦然
@@ -294,16 +372,6 @@ export default {
     },
   },
   methods: {
-    audiobook_request: async function (url, options = {}) {
-      const response = await fetch(url, {
-        mode: 'cors',
-        credentials: 'include',
-        ...options,
-      });
-      const payload = await response.json();
-      if (!response.ok && !payload?.err) throw new Error(`有声书接口请求失败（${response.status}）`);
-      return payload;
-    },
     open_audiobook: function () {
       this.set_menu('hide');
       this.audiobook_open = true;
@@ -318,6 +386,270 @@ export default {
       this.audiobook_open = true;
       this.$nextTick(() => this.$refs.audiobookPlayer?.playFromSelection(selection));
     },
+    initialize_annotations: function () {
+      try {
+        this.annotation_repository = createAnnotationCallbacks({
+          callbacks: this.annotation_callbacks,
+          bookId: this.initial_book_id,
+          bookUrl: this.book_url,
+        });
+      } catch (error) {
+        console.error('Candle Reader annotations could not be initialized:', error);
+      }
+      try {
+        this.audiobook_repository = createAudiobookRepository({
+          callbacks: this.audiobook_callbacks,
+          bookId: this.initial_book_id,
+          bookUrl: this.book_url,
+        });
+      } catch (error) {
+        console.error('Candle Reader audiobook could not be initialized:', error);
+      }
+    },
+    annotation_color: function (annotation) {
+      const colors = { blue: '#4f8fb8', green: '#54a675', pink: '#d97a9d', yellow: '#e6b91e' };
+      return colors[annotation?.color] || annotation?.color || (annotation?.annotation_type === 'note' ? '#4f8fb8' : '#e6b91e');
+    },
+    render_annotation: function (annotation) {
+      if (!this.comments_enabled || !this.rendition || !annotation?.cfi) return;
+      // 正文底色只画划线；有评论的段落由段尾气泡表示，不再给整段铺底色。
+      if (annotation.annotation_type !== 'highlight') return;
+      // epub.js indexes highlights by CFI, so multiple records at one range
+      // must share one mark or remove(cfi) can leave an orphaned SVG behind.
+      const identity = String(annotation.cfi);
+      if (identity && this.rendered_annotation_ids.has(identity)) return;
+      try {
+        this.rendition.annotations.highlight(
+          annotation.cfi,
+          { annotationId: annotation.id || annotation.client_id },
+          () => this.open_annotation_paragraph(annotation),
+          'candle-reader-annotation',
+          { fill: this.annotation_color(annotation), 'fill-opacity': '0.38', 'mix-blend-mode': 'multiply' },
+        );
+        if (identity) this.rendered_annotation_ids.add(identity);
+        this.rendered_annotations.push(annotation);
+      } catch (error) {
+        console.warn('Candle Reader annotation could not be rendered:', identity, error);
+      }
+    },
+    clear_annotation_marks: function () {
+      if (this.rendition?.annotations) {
+        this.rendered_annotations.forEach(annotation => {
+          try {
+            this.rendition.annotations.remove(annotation.cfi, 'highlight');
+          } catch (error) {
+            console.warn('Candle Reader annotation could not be removed:', error);
+          }
+        });
+      }
+      this.rendered_annotations = [];
+      this.rendered_annotation_ids.clear();
+    },
+    load_user: async function () {
+      try {
+        this.user = await this.annotation_repository?.user() || null;
+      } catch (error) {
+        console.warn('Candle Reader current user could not be loaded:', error);
+      }
+    },
+    // 游客触发写评论、划线、赞踩、回复时引导登录；登录流程由宿主负责。
+    request_login: async function () {
+      this.show_annotation_feedback('请先登录后再操作');
+      try {
+        await this.annotation_repository?.login();
+        await this.load_user();
+      } catch (error) {
+        console.warn('Candle Reader login callback failed:', error);
+      }
+    },
+    // 读取这些章节里自己的划线与评论，用于在正文绘制标记。一页可能横跨两章，所以按章节列表读取。
+    load_chapter_annotations: async function (chapters) {
+      chapters = [].concat(chapters).filter(Boolean);
+      if (!chapters.length || !this.annotation_repository || !this.comments_enabled) return;
+      const request = ++this.annotation_chapter_request;
+      try {
+        const loaded = await Promise.all(chapters.map(chapter => this.annotation_repository.load({ chapter })));
+        if (request !== this.annotation_chapter_request) return;
+        loaded.flat().forEach(this.render_annotation);
+      } catch (error) {
+        console.warn('Candle Reader chapter annotations could not be loaded:', error);
+      }
+    },
+    open_comments: function (scope, paragraph = null) {
+      this.comment_paragraph = paragraph;
+      this.hide_toolbar();
+      if (this.menu.current_panel !== 'annotations') this.set_menu('annotations');
+      // 本段评论按段落自己所在的章节查询：一页横跨两章时，段落不一定属于页首那一章。
+      this.$refs.comments?.show(scope, paragraph?.paragraph_cfi || '', String(paragraph?.toc?.label || '').trim());
+    },
+    // 点正文里的划线：打开划线所在段落的评论，而不是整章评论。
+    open_annotation_paragraph: function (annotation) {
+      const cfi = String(annotation?.cfi || '');
+      const contents = this.rendition?.getContents().find(item => cfi.includes(item.cfiBase));
+      let range = null;
+      try { range = contents?.range(cfi); } catch (error) { range = null; }
+      if (!range) return this.open_comments('chapter');
+      const chapter = String(annotation.chapter || '').trim();
+      const toc = this.visible_tocs.find(item => item.contents === contents && String(item.toc?.label || '').trim() === chapter)?.toc ||
+        this.visible_tocs.find(item => item.contents === contents)?.toc || this.current_toc;
+      const paragraph = this.paragraph_of(range.endContainer, contents);
+      this.open_comments('paragraph', { toc, contents, ...this.paragraph_location(paragraph, contents) });
+    },
+    on_open_annotations: function () {
+      if (this.menu.current_panel === 'annotations') return this.set_menu('hide');
+      this.open_comments('chapter');
+    },
+    on_view_selection_notes: function () {
+      if (!this.selected_location?.paragraph_cfi) return;
+      this.open_comments('paragraph', this.selected_location);
+    },
+    show_annotation_feedback: function (message, error = false) {
+      this.annotation_feedback_message = message;
+      this.annotation_feedback_error = error;
+      this.annotation_feedback_visible = true;
+    },
+    // 评论增删或公开范围变化后，同步正文中的标记与段尾气泡。
+    on_comments_changed: function () {
+      this.clear_annotation_marks();
+      this.load_chapter_annotations(this.visible_chapters());
+      this.refresh_comment_icons();
+    },
+    read_public_preference: function () {
+      try { return localStorage.getItem(PUBLIC_PREFERENCE_KEY) !== 'false'; } catch (error) { return true; }
+    },
+    save_annotation: async function (annotationType, content, isPrivate) {
+      if (!this.user) { this.request_login(); return null; }
+      const passage = annotationType === 'highlight' ? this.selected_location : this.annotation_editor_location;
+      const isNote = annotationType === 'note';
+      const cfi = isNote ? passage?.paragraph_cfi : passage?.cfi;
+      const quote = isNote && !passage?.multi_paragraph ? passage?.paragraph_quote_text : passage?.quote_text;
+      if (!cfi || !quote || !this.annotation_repository || this.annotation_saving) return null;
+      this.annotation_saving = true;
+      try {
+        const annotation = await this.annotation_repository.save({
+          client_id: passage.client_id || createClientId(),
+          annotation_type: annotationType,
+          is_private: annotationType === 'highlight' ? true : isPrivate,
+          chapter: String(passage.toc?.label || this.current_toc_title || '').trim(),
+          // 评论归属段落（跨段时为最后一段）与真实选区分开保存。
+          cfi: String(cfi),
+          range_cfi: String(passage.cfi || cfi),
+          quote_text: quote,
+          content,
+          color: isNote ? 'blue' : 'yellow',
+        });
+        this.render_annotation(annotation);
+        this.hide_toolbar();
+        try { passage.contents?.window?.getSelection()?.removeAllRanges(); } catch (error) { /* noop */ }
+        if (this.selected_location === passage) this.selected_location = {};
+        return annotation;
+      } catch (error) {
+        this.show_annotation_feedback(`保存失败：${error.message || '请稍后重试'}`, true);
+        return null;
+      } finally {
+        this.annotation_saving = false;
+      }
+    },
+    save_highlight: function () {
+      return this.save_annotation('highlight', '', true);
+    },
+    open_editor: function ({ location = null, record = null, type = 'note' }) {
+      this.annotation_editor_location = location;
+      this.annotation_editor_record = record;
+      this.annotation_editor_type = record?.annotation_type || type;
+      this.annotation_editor_content = record?.content || '';
+      this.annotation_editor_error = '';
+      // 新建沿用最近一次公开范围选择；编辑显示该记录自己的公开范围。
+      this.annotation_editor_private = record ? record.is_private !== false : !this.read_public_preference();
+      this.annotation_editor_open = true;
+    },
+    open_note_editor: function () {
+      if (!this.selected_location?.paragraph_cfi) return;
+      if (!this.user) return this.request_login();
+      this.hide_toolbar(true);
+      this.open_editor({ location: this.selected_location });
+    },
+    // 抽屉与完整评论页底部的「写评论」：本段范围写段落评论，其余范围写整书评论。
+    on_write_comment: function ({ scope }) {
+      if (scope === 'paragraph' && this.comment_paragraph?.paragraph_cfi) {
+        this.open_editor({ location: { ...this.comment_paragraph, client_id: createClientId() } });
+      } else {
+        this.open_editor({ type: 'book_comment' });
+      }
+    },
+    on_edit_comment: function (record) {
+      this.open_editor({ record });
+    },
+    save_note: async function () {
+      const content = this.annotation_editor_content.trim();
+      if (!content) {
+        this.annotation_editor_error = '请填写评论内容';
+        this.$nextTick(() => this.$refs.annotationEditorContent?.focus());
+        return;
+      }
+      const isPrivate = this.annotation_editor_private;
+      const record = this.annotation_editor_record;
+      let saved = null;
+      if (record || this.annotation_editor_type === 'book_comment') {
+        if (this.annotation_saving) return;
+        this.annotation_saving = true;
+        try {
+          saved = await this.annotation_repository.save(record
+            ? { id: record.id, client_id: record.client_id, annotation_type: record.annotation_type, content, is_private: isPrivate }
+            : {
+              client_id: createClientId(),
+              annotation_type: 'book_comment',
+              is_private: isPrivate,
+              chapter: '',
+              // 整书评论关联到全书最开头。
+              cfi: `epubcfi(${this.book.spine.first().cfiBase}!/4)`,
+              quote_text: '',
+              content,
+            });
+        } catch (error) {
+          this.show_annotation_feedback(`保存失败：${error.message || '请稍后重试'}`, true);
+        } finally {
+          this.annotation_saving = false;
+        }
+      } else {
+        saved = await this.save_annotation('note', content, isPrivate);
+      }
+      if (!saved) return;
+      if (!record) {
+        try { localStorage.setItem(PUBLIC_PREFERENCE_KEY, String(!isPrivate)); } catch (error) { /* noop */ }
+      }
+      this.annotation_editor_open = false;
+      this.$refs.comments?.apply_saved(saved);
+      this.on_comments_changed();
+      const where = saved.annotation_type === 'book_comment' ? '全书评论' : '';
+      this.show_annotation_feedback(isPrivate ? '已保存为私密，可在「查看更多评论 › 我的」中查看'
+        : where ? `评论已保存，可在「${where}」中查看` : '评论已保存');
+    },
+    on_annotation_editor_closed: function () {
+      const closingLocation = this.annotation_editor_location;
+      this.annotation_editor_location = null;
+      this.annotation_editor_record = null;
+      if (closingLocation && this.selected_location === closingLocation) {
+        this.clear_selection_preview();
+        try { closingLocation?.contents?.window?.getSelection()?.removeAllRanges(); } catch (error) { /* noop */ }
+        this.selected_location = {};
+      }
+      if (!this.selected_location?.cfi) this.restore_reader_focus();
+    },
+    restore_reader_focus: function () {
+      document.querySelector('#reader iframe')?.focus();
+    },
+    copy_selection: async function () {
+      const text = this.selected_location?.quote_text;
+      if (!text) return;
+      try {
+        await navigator.clipboard.writeText(text);
+        this.hide_toolbar();
+        this.show_annotation_feedback('已复制选中文字');
+      } catch (error) {
+        this.show_annotation_feedback('复制失败，请使用系统复制功能', true);
+      }
+    },
     switch_theme: function () {
       // 在「最近用过的白天主题」与「最近用过的夜晚主题」之间切换
       const isDayTheme = getTheme(this.settings.theme).mode === 'day';
@@ -415,6 +747,8 @@ export default {
         'line-height': `${this.settings.line_height} !important`,
         'letter-spacing': `${this.settings.letter_spacing}px !important`,
       };
+      // 开启选中工具栏时，尽量关掉 iOS 系统的文字菜单（拷贝/查询…），避免和我们的工具栏同时出现；关闭工具栏时保留系统菜单用于复制。
+      if (this.settings.show_selection_toolbar) decl['-webkit-touch-callout'] = 'none !important';
       const rules = { 'body, body *': decl };
       if (t.type === 'image') {
         // 图片皮肤：html 和 body 都设透明，iframe 才能真正透出 #reader 上的背景图
@@ -431,6 +765,21 @@ export default {
       }
       this.rendition.themes.default(rules);
     },
+    on_panel_model_update: function (panel, open) {
+      // Escape/outside clicks update v-model without going through set_menu.
+      if (!open && this.menu.current_panel === panel) this.set_menu('hide');
+    },
+    on_panel_after_leave: function (panel) {
+      // An outgoing sibling must not steal focus from the incoming sheet.
+      if (panel !== this.panel_closing || Object.values(this.menu.panels).some(Boolean)) return;
+      if (this.show_theme_dialog || this.annotation_editor_open) return;
+      const usable = el => el?.isConnected && !el.disabled && !el.closest('[inert], .v-overlay') && el.getClientRects().length;
+      const fallback = this.$refs[this.panel_entry_ref]?.$el || this.$refs.panelEntryAnnotations?.$el;
+      const target = usable(this.panel_trigger) ? this.panel_trigger : fallback;
+      if (usable(target)) target.focus({ preventScroll: true });
+      this.panel_closing = null;
+      this.panel_trigger = null;
+    },
     set_menu: function (target_menu_panel) {
       var target = target_menu_panel;
       if (this.menu.current_panel == target) {
@@ -439,6 +788,20 @@ export default {
         }
       }
 
+      if (target !== 'annotations') this.$refs.comments?.close_pages();
+      if (target === 'hide') {
+        if (this.menu.current_panel !== 'hide') this.panel_closing = this.menu.current_panel;
+      } else {
+        const active = document.activeElement;
+        const external = active?.matches('button, a[href], [tabindex]') && !active.closest('.v-overlay');
+        if (external || !this.panel_trigger) {
+          const refs = { settings: 'panelEntrySettings', toc: 'panelEntryToc', ai: 'panelEntryAi' };
+          this.panel_entry_ref = refs[target] || 'panelEntryAnnotations';
+          this.panel_trigger = external ? active : this.$refs[this.panel_entry_ref]?.$el;
+        }
+        this.panel_closing = null;
+      }
+
       this.menu.value = (target == 'hide') ? undefined : target;
       console.log("set menu = ", target, ", current menu.value=", this.menu.value);
       this.menu.current_panel = target;
@@ -460,6 +823,7 @@ export default {
       localStorage.setItem('readerSettings', JSON.stringify(this.settings));
     },
     update_settings: function (opt) {
+      const commentsWereEnabled = this.comments_enabled;
       if (opt.flow != this.settings.flow) {
         // FIXME 切换后，翻页到下一章时css会丢失
         this.rendition.flow(opt.flow)
@@ -471,6 +835,16 @@ export default {
       // 应用主题（含外层背景图、iframe 透明/文字色、行距字距）
       this.apply_theme(this.settings.theme);
 
+      // 「显示全部划线和评论」切换时，同步正文里的划线标记与段尾气泡；评论数据本身不受影响。
+      if (commentsWereEnabled && !this.comments_enabled) {
+        this.annotation_chapter_request++;
+        this.clear_annotation_marks();
+      } else if (!commentsWereEnabled && this.comments_enabled) {
+        this.load_chapter_annotations(this.visible_chapters());
+      }
+      if (commentsWereEnabled !== this.comments_enabled) this.refresh_comment_icons();
+      if (!this.settings.show_selection_toolbar) this.hide_toolbar();
+
       // 应用亮度设置（作用于 #main，整屏含背景图与状态栏一起调光）
       if (opt.brightness !== undefined) {
         const brightness = opt.brightness / 100;
@@ -481,6 +855,8 @@ export default {
       if (opt.font_size !== undefined) {
         this.rendition.themes.fontSize(opt.font_size + 'px');
       }
+      // 字号、行距、字距会让正文重新排版，气泡按最后一个字重新定位。
+      requestAnimationFrame(() => this.refit_comment_icons());
 
       this.save_settings();
     },
@@ -490,18 +866,32 @@ export default {
       this.suspend_audiobook_follow();
       this.rendition.display(item.id);
     },
-    on_mousedown: function (mouse_event) {
+    on_mousedown: function (event) {
       this.mouse_down_time = new Date();
+      this.mouse_down_point = event ? { x: event.clientX, y: event.clientY } : null;
     },
-    on_mouseup: function (mouse_event) {
+    on_mouseup: function (event) {
       const t = new Date() - this.mouse_down_time;
-      if (t > 600) {
-        this.check_if_selected_content = true;
-      } else {
-        this.check_if_selected_content = false;
-      }
+      // 按住拖动选字时，松开后浏览器同样会发 click：拖动距离明显或按得久都按选字处理。
+      const point = this.mouse_down_point;
+      const dragged = Boolean(point && event) && Math.hypot(event.clientX - point.x, event.clientY - point.y) > 8;
+      this.check_if_selected_content = t > 600 || dragged;
     },
     on_click_content: function (event) {
+      // 快速拖选时 click 早于 epub.js 的 selected 事件（约 250ms 后才发）：此时正文里已有选区，不能当作点击翻页。
+      // 双击选词同理（event.detail 为连击次数）。
+      if (event?.type === 'click' && event.view?.getSelection?.()?.isCollapsed === false && (event.detail >= 2
+        || (this.mouse_down_point && Math.hypot(event.clientX - this.mouse_down_point.x, event.clientY - this.mouse_down_point.y) > 8))) {
+        this.is_handlering_selected_content = false;
+        return;
+      }
+      // 已有选中文字时点别处：只取消选中、收起工具栏，这一下不翻页。
+      // iOS 上轻点时选区在 click 之前就被系统清掉了，读不到选区，所以以 epub.js 报过的选中状态为准。
+      if (this.selection_active || this.clear_text_selection()) {
+        this.clear_text_selection();
+        this.hide_toolbar();
+        return;
+      }
       if (!this.check_if_selected_content) {
         return this.smart_click(event)
       }
@@ -516,6 +906,18 @@ export default {
         }
       }, 300);
     },
+    clear_text_selection: function () {
+      let cleared = false;
+      for (const contents of this.rendition?.getContents() || []) {
+        const selection = contents.window?.getSelection();
+        if (selection && !selection.isCollapsed) {
+          selection.removeAllRanges();
+          cleared = true;
+        }
+      }
+      if (cleared) this.clear_selection_preview();
+      return cleared;
+    },
     smart_click: function (event) {
       const rect = event.view.frameElement.getBoundingClientRect();
       const viewer = document.getElementById('reader');
@@ -616,6 +1018,27 @@ export default {
       }
       return;
     },
+    find_toc_in_same_file: function (cfi, contents, href) {
+      const chapters = [];
+      const collect = items => items.forEach(item => {
+        if (String(item.href || '').split('#')[0] === href) chapters.push(item);
+        if (item.subitems?.length) collect(item.subitems);
+      });
+      collect(this.toc_items);
+      let found;
+      for (const chapter of chapters) {
+        // 正文重新渲染后旧元素已失效，需要重新定位。
+        if (chapter.elem?.ownerDocument !== contents.document) {
+          const elem = contents.document.getElementById(chapter.href.split('#')[1] || '');
+          if (!elem) continue;
+          chapter.elem = elem;
+          chapter.cfi = new ePub.CFI(new ePub.CFI(elem, contents.cfiBase).toString());
+        }
+        if (found && this.book.locations.epubcfi.compare(cfi, chapter.cfi) < 0) break;
+        found = chapter;
+      }
+      return found;
+    },
     find_toc: function (search_cfi, contents) {
       const cfi = new ePub.CFI(search_cfi.toString()); // 强制转成标准格式
       const section = this.book.spine.get(contents.sectionIndex);
@@ -624,7 +1047,24 @@ export default {
       const toc = this.find_same_href_in_toc_tree(this.toc_items, section.href);
       console.log("got spine href in toc:", toc)
       if (toc === undefined) {
-        return;
+        // 目录项都带锚点（一个正文文件里有多章）时，按位置取光标之前最近的那一章。
+        const chapter = this.find_toc_in_same_file(cfi, contents, section.href);
+        if (chapter) return chapter;
+        // NCX/navigation can omit a readable spine item. Keep a stable chapter
+        // context for both selection saves and reload/re-enable annotation loads.
+        // Do not insert this synthetic entry into the book's actual TOC.
+        if (contents.annotationFallbackToc) return contents.annotationFallbackToc;
+        const body = contents.document.body;
+        const heading = body.querySelector('h1, h2, h3, h4, h5, h6');
+        contents.annotationFallbackToc = {
+          href: section.href,
+          label: heading?.textContent.trim() || `正文 ${section.index + 1}`,
+          elem: body,
+          cfi: new ePub.CFI(body, contents.cfiBase),
+          subitems: [],
+          is_fallback: true,
+        };
+        return contents.annotationFallbackToc;
       }
 
       // 填充 cfi 定位信息
@@ -656,9 +1096,15 @@ export default {
     count_distinct_between: function (start_elem, end_elem) {
       // 获取父节点
       var end = end_elem;
-      while (end.parentElement != start_elem.parentNode) {
+      while (end && end.parentElement != start_elem.parentNode) {
         end = end.parentElement;
       }
+      if (!end) {
+        // 章节锚点与段落不在同一层级（一个文件里有多章时常见），按文档顺序数两者之间的段落。
+        const blocks = Array.from(start_elem.ownerDocument.querySelectorAll('p, h1, h2, h3, h4, h5, h6'));
+        const first = blocks.findIndex(block => block === start_elem || block.contains(start_elem) || (start_elem.compareDocumentPosition(block) & Node.DOCUMENT_POSITION_FOLLOWING));
+        return Math.max(0, blocks.indexOf(end_elem) - first);
+      }
 
       // 初始化计数器
       let segment_id = 0;
@@ -689,37 +1135,90 @@ export default {
 
       return segment_id;
     },
-    hide_toolbar: function () {
+    clear_selection_preview: function () {
+      this.selection_preview_rects = [];
+    },
+    update_selection_preview: function (range, iframeRect) {
+      this.selection_preview_rects = Array.from(range.getClientRects())
+        .filter(rect => rect.width > 0 && rect.height > 0)
+        .map(rect => ({
+          left: `${iframeRect.left + rect.left}px`,
+          top: `${iframeRect.top + rect.top}px`,
+          width: `${rect.width}px`,
+          height: `${rect.height}px`,
+        }));
+    },
+    hide_toolbar: function (preserveSelection = false) {
+      if (!preserveSelection) this.selection_active = false;
       this.toolbar_left = -999;
+      if (!preserveSelection) this.clear_selection_preview();
     },
     show_toolbar: function (rect, iframe_rect) {
+      if (!this.settings.show_selection_toolbar) return;
       console.log("show toolbar at rect", rect, " from iframe rect", iframe_rect)
-      const toolbar = document.getElementById('comments-toolbar');
-      this.toolbar_left = rect.left + iframe_rect.x;
-
+      const preferredLeft = rect.left + iframe_rect.x;
       const top = rect.top + iframe_rect.y;
       const bottom = rect.bottom + iframe_rect.y;
-      if (top >= (toolbar.offsetHeight + 64)) {
-        this.toolbar_top = (top - toolbar.offsetHeight - 12);
-      } else {
-        this.toolbar_top = (bottom + 12);
-      }
+      this.toolbar_left = 8;
+      this.toolbar_top = bottom + 12;
+      this.$nextTick(() => {
+        const toolbar = this.$refs.selectionToolbar;
+        if (!toolbar || !this.settings.show_selection_toolbar) return;
+        const { width, height } = toolbar.getBoundingClientRect();
+        const maxLeft = Math.max(8, window.innerWidth - width - 8);
+        this.toolbar_left = Math.max(8, Math.min(maxLeft, preferredLeft));
+        const bottomClearance = this.menu.show_navbar ? 64 : 8;
+        const fitsAbove = top >= (height + 12 + 8);
+        const fitsBelow = bottom + 12 + height <= window.innerHeight - bottomClearance;
+        // 触屏设备（如 iOS Safari）的系统文字菜单固定出现在选区上方且无法关闭，工具栏改为优先放在下方，避免两者重叠。
+        const preferBelow = window.matchMedia?.('(pointer: coarse)').matches && fitsBelow;
+        this.toolbar_top = fitsAbove && !preferBelow
+          ? top - height - 12
+          : Math.min(window.innerHeight - height - bottomClearance, bottom + 12);
+      });
     },
     is_toolbar_visible: function () {
-      return (this.toolbar_left > 0);
+      return this.settings.show_selection_toolbar && this.toolbar_left > 0;
+    },
+    paragraph_of: function (node, contents) {
+      const element = node.nodeType === Node.TEXT_NODE ? node.parentElement : node;
+      return element.closest('p, h1, h2, h3, h4, h5, h6, li, blockquote, div') || contents.document.body;
+    },
+    // 整段的 CFI 与原文。按文字边界取范围，段尾评论气泡不会进入引用，也不会改变段落 CFI。
+    paragraph_location: function (paragraph, contents) {
+      const walker = contents.document.createTreeWalker(paragraph, NodeFilter.SHOW_TEXT, {
+        acceptNode: node => node.parentElement.closest('.comment-icon, script, style')
+          ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT,
+      });
+      const nodes = [];
+      while (walker.nextNode()) nodes.push(walker.currentNode);
+      if (!nodes.length) return {};
+      const paragraphRange = contents.document.createRange();
+      paragraphRange.setStart(nodes[0], 0);
+      paragraphRange.setEnd(nodes[nodes.length - 1], nodes[nodes.length - 1].length);
+      return {
+        paragraph_cfi: contents.cfiFromRange(paragraphRange),
+        paragraph_quote_text: nodes.map(node => node.textContent).join('').trim(),
+      };
+    },
+    paragraph_for_range: function (range, contents) {
+      // 跨段选区的评论归属最后一个段落；真实选区仍由 cfi / quote_text 保留。
+      const paragraph = this.paragraph_of(range.endContainer, contents);
+      return {
+        ...this.paragraph_location(paragraph, contents),
+        multi_paragraph: paragraph !== this.paragraph_of(range.startContainer, contents),
+      };
     },
     on_select_content: function (cfiRange, contents) {
       console.log("on selectd", cfiRange, contents)
       this.is_handlering_selected_content = true;
 
       // 找到选中的元素，并上溯到 P 或者 Hx 对象
-      const range = this.rendition.getRange(cfiRange);
-      var p = range.startContainer.nodeType === Node.TEXT_NODE
+      const range = this.rendition.getRange(cfiRange) || contents.range(cfiRange);
+      const start = range.startContainer.nodeType === Node.TEXT_NODE
         ? range.startContainer.parentElement
         : range.startContainer;
-      while (p.nodeName.toUpperCase() != "P" && p.nodeName.toUpperCase()[0] != "H") {
-        p = p.parentElement;
-      }
+      const p = start.closest('p, h1, h2, h3, h4, h5, h6') || start;
       console.log("selected elem =", p);
 
       // 遍历toc，查找最近的章节名称
@@ -728,29 +1227,41 @@ export default {
       const toc = this.find_toc(cfi, contents);
       console.log("cfi = ", cfi, "toc =", toc);
 
-      // 基于cfi的数字快速计算
-      // const segment_id = cfi.path.steps[1].index - toc.cfi.path.steps[1].index;
-      const segment_id = this.count_distinct_between(toc.elem, p);
-      console.log("selected segment_id = ", segment_id);
+      // 段落序号只给听书「从这里听」兜底匹配用；算不出来也不能挡住工具栏。
+      let segment_id = 0;
+      try {
+        segment_id = toc.is_fallback
+          ? Math.max(0, Array.from(toc.elem.querySelectorAll('p, h1, h2, h3, h4, h5, h6')).indexOf(p))
+          : this.count_distinct_between(toc.elem, p);
+      } catch (error) {
+        console.warn('Candle Reader paragraph index could not be computed:', error);
+      }
 
       this.selected_location = {
+        client_id: createClientId(),
         toc: toc,
-        cfi: cfi,
+        cfi: String(cfiRange),
+        ...this.paragraph_for_range(range, contents),
+        quote_text: range.toString().trim(),
         contents: contents,
         segment_id: segment_id
       }
 
-      // 把 toolbar 移动到段落附近
+      this.selection_active = true;
+      // 把 toolbar 移动到实际选区附近。
       const view = this.rendition.views()._views.filter( view => { return view.index == contents.sectionIndex})[0]
-      this.show_toolbar(p.getBoundingClientRect(), view.iframe.getBoundingClientRect());
-    },
-    on_click_toolbar_comments: function () {
-      console.log("点击发表评论按钮", this.selected_location)
-      const s = this.selected_location;
-      this.hide_toolbar();
-      this.show_selected_comments(s.toc, s.segment_id, s.cfi);
+      // 蓝色选区底色只配合我们的工具栏使用（工具栏和编辑框打开时保持选区可见）；工具栏关闭时只留系统原生选区。
+      if (this.settings.show_selection_toolbar) this.update_selection_preview(range, view.iframe.getBoundingClientRect());
+      this.show_toolbar(range.getBoundingClientRect(), view.iframe.getBoundingClientRect());
     },
     on_keyup: function (e) {
+      if (e.key === 'Escape' && this.is_toolbar_visible()) {
+        this.hide_toolbar();
+        this.restore_reader_focus();
+        return;
+      }
+      const target = e.target;
+      if (target?.matches?.('input, textarea, select') || target?.isContentEditable) return;
       const c = e.keyCode || e.which;
       // Left & Up
       if (c == 37 || c == 38) {
@@ -770,7 +1281,6 @@ export default {
       if (this.settings.flow !== 'paginated') return;
       if (!this.rendition) return;
       if (this.menu.current_panel !== 'hide') return;
-      if (this.show_login || this.show_user_center) return;
       if (e.ctrlKey || e.metaKey || e.altKey) return;
       const t = e.target;
       if (t && t.closest && (
@@ -809,7 +1319,6 @@ export default {
     },
     debug_signals: function () {
       if (!this.is_debug_signal) return;
-      var signals = ['click', 'selected', 'touchstart', 'touchend', 'touchmove'];
       var signals = ["added", "attach", "attached", "axis", "changed", "detach", "displayed", "displayerror", "expand", "hidden", "layout", "linkClicked", "loaderror", "locationChanged", "markClicked", "openFailed", "orientationchange", "relocated", "removed", "rendered", "resize", "resized", "scroll", "scrolled", "selected", "selectedRange", "shown", "started", "updated", "writingMode", "mouseup", "mousedown", "mousemove", "click", "touchend", "touchstart", "touchmove"]
       signals.forEach(sig => {
         this.rendition.on(sig, (e) => {
@@ -820,6 +1329,7 @@ export default {
     },
     init_listeners: function () {
       document.addEventListener('keyup', this.on_keyup);
+      document.addEventListener('touchmove', this.block_page_drag, { passive: false });
       this.rendition.on('keyup', this.on_keyup);
       this.rendition.on('click', this.on_click_content);
       this.rendition.on('selected', this.on_select_content);
@@ -847,6 +1357,14 @@ export default {
         doc.addEventListener('wheel', this.on_wheel, { passive: false });
       });
     },
+    // iOS Safari 上纵向拖动会带着整页回弹并收起/展开地址栏，可视高度一变正文就重新排版，看起来像在滚动加载。
+    // 左右翻页模式下拦掉阅读区域外框（顶栏、底栏、正文四周）的原生拖动。正文 iframe 里不拦：
+    // iOS 拖动选区两端的手柄靠的就是原生拖动；整页不动由 html/body 固定定位保证。
+    block_page_drag: function (event) {
+      if (this.settings.flow !== 'paginated' || event.touches?.length > 1) return;
+      if (!event.target?.closest?.('#main, .v-app-bar, .v-bottom-navigation')) return;
+      if (event.cancelable) event.preventDefault();
+    },
 
     init_themes: function () {
       console.log("load themes from:", this.themes_css)
@@ -859,6 +1377,7 @@ export default {
       console.log('Reader resized');
       // 横竖屏/窗口尺寸变化时，图片皮肤切换竖版/横版大图
       this.apply_skin_background();
+      requestAnimationFrame(() => this.refit_comment_icons());
       // 强制重新渲染当前页面，解决缩放后卡住问题
       try {
         if (this.rendition && this.book) {
@@ -899,112 +1418,6 @@ export default {
         console.error('Error during fullscreen re-render:', error);
       }
     },
-    on_add_review: function (content) {
-      const loc = this.comments_location
-      const review = {
-        book_id: this.book_id,
-        chapter_name: loc.toc.label.trim(),
-        chapter_id: loc.toc.chapter_id,
-        segment_id: loc.segment_id,
-        cfi: loc.cfi.toString(),
-        content: content,
-        type: 1,
-      }
-      console.log("add review = ", review)
-
-      this.$backend('/api/review/add', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(review),
-      }).then(rsp => {
-        if (rsp.err == 'ok') {
-          this.comments.push(rsp.data);
-          alert("评论成功")
-        }
-        console.log("add review rsp = ", rsp)
-      });
-    },
-    on_jump_review: function (cfi) {
-      // 跳转到评论对应的 epub 位置（cfi 可为真实 epubcfi 或章节 href），并收起面板
-      if (!cfi || !this.rendition) return;
-      this.rendition.display(cfi);
-      this.set_menu('hide');
-    },
-    on_open_comments: function () {
-      this.set_menu('more');
-      this.load_book_reviews();
-    },
-    on_change_book_review_sort: function (sort) {
-      this.book_review_sort = sort;
-      this.load_book_reviews();
-    },
-    load_book_reviews: function () {
-      if (!this.book_id) return; // book_id 尚未就绪（依赖 metadata 解析）
-      const url = `/api/review/book/list?book_id=${this.book_id}&sort=${this.book_review_sort}`;
-      this.$backend(url).then(rsp => {
-        if (rsp.err == 'ok') {
-          this.book_reviews = rsp.data.list || [];
-        }
-      });
-    },
-    on_book_login: function (user_data) {
-      this.on_login_user(user_data);
-      this.show_login = false;
-    },
-    on_book_logout: function () {
-      this.user = null;
-      this.is_login = false;
-      this.show_user_center = false;
-    },
-    on_add_book_review: function (content) {
-      // 「本书评论」锚定到当前章开始：chapter_id 由 summary 回填，cfi 取本章首元素。
-      const toc = this.current_toc;
-      if (!toc) {
-        alert("请先打开任意章节再发表评论");
-        return;
-      }
-      const review = {
-        book_id: this.book_id,
-        chapter_name: toc.label.trim(),
-        chapter_id: toc.chapter_id,
-        segment_id: 0, // 0 表示整章级（非段评）
-        cfi: toc.cfi ? toc.cfi.toString() : "",
-        content: content,
-        type: 1,
-      }
-      console.log("add book review = ", review)
-
-      this.$backend('/api/review/add', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify(review),
-      }).then(rsp => {
-        if (rsp.err == 'ok') {
-          this.book_reviews.push(rsp.data);
-          alert("评论成功")
-        }
-        console.log("add book review rsp = ", rsp)
-      });
-    },
-    on_location_changed_old: function (loc) {
-      // if (this.review_bid <= 0) return;
-
-      const contents_list = this.rendition.getContents();
-      [loc.start, loc.end].forEach(cfi => {
-        console.log("handle location ", cfi)
-        const spine = this.book.spine.get(cfi);
-        const contents = contents_list.filter(c => { return c.cfiBase == spine.cfiBase })[0];
-
-        const target_cfi = new ePub.CFI(cfi)
-        const toc = this.find_toc(target_cfi, contents, spine.href);
-
-        this.load_comments_summary(contents, toc);
-      })
-    },
     on_location_changed: function (loc) {
       // 处理当前显示的章节，确保章节标题正确更新
       try {
@@ -1025,24 +1438,33 @@ export default {
           this.current_toc_title = toc.label;
           this.current_toc = toc;
 
-          // 只有当章节标题实际变化时，才重新加载评论，避免不必要的 API 请求
-          if (this.last_toc_label !== toc.label) {
-            this.load_comments_summary(contents, toc);
-            this.last_toc_label = toc.label;
+          // 一屏可能跨好几章（短章、宽屏、连续滚动）：从页首到页尾之间出现的每一章，段尾气泡和划线都要显示。
+          const endContents = loc.end && contents_list.find(c => String(loc.end).includes(c.cfiBase));
+          const endToc = endContents && this.find_toc(new ePub.CFI(loc.end), endContents);
+          this.visible_tocs = markRaw(this.tocs_between({ contents, toc }, endToc && { contents: endContents, toc: endToc }, contents_list));
+
+          // 只有当可见章节实际变化时，才重新加载评论，避免不必要的 API 请求
+          const visible = this.visible_tocs;
+          const labels = visible.map(item => item.toc.label).join('\n');
+          if (this.last_toc_label !== labels) {
+            visible.forEach(item => this.load_comments_summary(item.contents, item.toc));
+            this.load_chapter_annotations(this.visible_chapters());
+            this.last_toc_label = labels;
           }
         }
       } catch (error) {
         console.error('Error in on_location_changed:', error);
       }
     },
+    // 段尾气泡：显示归属本段的公开评论数量，点击进入本段评论。
     load_comments_summary: function (contents, toc) {
-      console.log("load_comments_summary at ", contents, toc)
+      if (!this.comments_enabled || !this.annotation_repository) return;
+      const request = this.comments_request;
       if (toc === undefined) {
-        console.log("!! 加载章评错误，章节信息为空")
+        console.log("!! 加载评论数量错误，章节信息为空")
         return
       }
 
-      // TODO 应当增加一个刷新机制
       if (toc.load_time !== undefined) {
         const ms = new Date() - toc.load_time;
         if (ms < this.comments_refresh_time) {
@@ -1051,125 +1473,168 @@ export default {
       }
 
       toc.load_time = new Date();
-
-      // 查询该章节的评论总数，并保存到toc对象中，然后展示图标
-      const chapter_name = toc.label.trim();
-      var url = `/api/review/summary?book_id=${this.book_id}&chapter_name=${chapter_name}`;
-      this.$backend(url).then(rsp => {
-        toc.load_time = new Date();
-        toc.summary = {}
-        toc.chapter_id = rsp.data.chapter_id;
-        rsp.data.list.forEach(item => {
-          toc.summary[item.segmentId] = item;
-          toc.icons_rendered = false;
-        })
-      }).catch(function (error) {
-        console.error('请求过程中出现错误：', error);
-      }).finally(() => {
+      return this.annotation_repository.summary({ chapter: toc.label.trim() }).then(items => {
+        if (!this.comments_enabled || request !== this.comments_request) return;
+        toc.summary = items;
         this.add_comment_icons(contents, toc);
-      });;
+      }).catch(function (error) {
+        console.error('加载评论数量出现错误：', error);
+      });
     },
     add_comment_icons: function (contents, toc) {
-      console.log("添加评论图标和计数器：", toc.label.trim())
-
-      // 如果章评功能关闭，不添加图标
-      if (!this.settings.show_comments) {
-        return;
-      }
-
-      // 确定 segment_id 的最大值
-      var max_segment_id = 0;
-      for (var idx in toc.summary) {
-        if (idx > max_segment_id) {
-          max_segment_id = idx
+      if (!this.comments_enabled || !contents) return;
+      (toc.summary || []).forEach(item => {
+        const cfi = String(item.paragraph_cfi || '');
+        // 只处理属于这个正文文档的段落。
+        if (!item.count || !cfi.includes(contents.cfiBase)) return;
+        try {
+          const range = contents.range(cfi);
+          if (range) this.add_icon_into_paragraph(contents, this.paragraph_of(range.endContainer, contents), item, toc);
+        } catch (error) {
+          console.warn('Candle Reader comment bubble could not be placed:', cfi, error);
         }
-      }
-
-      // 深度优先遍历
-      var segment_id = 0;
-      var currentNode = toc.elem;
-
-      // 从起始节点开始遍历到结束节点
-      while (segment_id <= max_segment_id && currentNode) {
-        const node_name = currentNode.nodeName.toUpperCase();
-          if (node_name === "P" || node_name[0] === "H") {
-            this.add_icon_into_paragraph(contents, currentNode, segment_id, toc)
-            segment_id ++;
-          }
-          // 如果当前节点有子节点，则进入子节点
-          if (currentNode.firstChild) {
-              currentNode = currentNode.firstChild;
-          // 否则尝试下一个兄弟节点
-          } else if (currentNode.nextSibling) {
-              currentNode = currentNode.nextSibling;
-          // 如果没有子节点和兄弟节点，则回溯到父节点的下一个兄弟节点
-          } else {
-              while (!currentNode.nextSibling && currentNode.parentNode) {
-                  currentNode = currentNode.parentNode;
-              }
-              currentNode = currentNode.nextSibling;
-          }
-      }
-
-      // 标记已渲染图标
-      toc.icons_rendered = true;
+      });
     },
-
-    add_icon_into_paragraph: function (contents, elem, segment_id, toc) {
-      const state = toc.summary[segment_id];
-      if (state === undefined) {
-        return;
-      }
-      console.log("添加评论图标：", segment_id, elem, state)
-
+    add_icon_into_paragraph: function (contents, elem, item, toc) {
       // 检查是否已经添加了评论图标，避免重复添加
       if (elem.querySelector('.comment-icon')) {
         return;
       }
 
-      const cfi = new ePub.CFI(elem, contents.cfiBase).toString();
-      const count = state.reviewNum;
-      const is_hot = state.is_hot ? "hot-comment" : "";
-
       // 创建评论气泡：气泡即容器，评论数作为内容天然居中
       const doc = contents.document;
       const commentContainer = doc.createElement("div");
-      commentContainer.className = `comment-icon ${is_hot}`;
-      commentContainer.innerHTML = `<span class="comment-count">${count}</span>`;
-
-      // 将评论组件添加到段落末尾（内联跟随文字）
-      elem.appendChild(commentContainer);
+      commentContainer.className = 'comment-icon';
+      const commentCount = doc.createElement("span");
+      commentCount.className = 'comment-count';
+      commentCount.textContent = String(item.count);
+      commentContainer.appendChild(commentCount);
+
+      // 气泡挂在段落末尾的零宽锚点上、绝对定位显示，不参与正文排版：
+      // 插入或移除气泡都不会让文字折行、后文下移，已经画好的划线标记（按绘制时的文字位置定位）也就不会错位。
+      const anchor = doc.createElement("span");
+      anchor.className = 'comment-anchor';
+      anchor.appendChild(commentContainer);
+      elem.appendChild(anchor);
+      this.fit_comment_icon(commentContainer, anchor, elem);
 
       commentContainer.addEventListener('click', (event) => {
         event.stopPropagation();
-        console.log("点击评论按钮", toc.chapter_id, segment_id, cfi)
-        this.show_selected_comments(toc, segment_id, cfi);
+        this.open_comments('paragraph', { toc, contents, ...this.paragraph_location(elem, contents), paragraph_cfi: String(item.paragraph_cfi) });
       });
     },
-    show_selected_comments: function (toc, segment_id, cfi) {
-      // 重置状态
-      this.comments = [];
-      this.comments_location = {
-        toc: toc,
-        cfi: cfi,
-        segment_id: segment_id,
+    // 段落最后一个可见字的位置。段尾常有 <br> 或换行空白，锚点会落到下一行，气泡要以最后一个字为准。
+    last_char_rect: function (paragraph) {
+      const doc = paragraph.ownerDocument;
+      const walker = doc.createTreeWalker(paragraph, NodeFilter.SHOW_TEXT, {
+        acceptNode: node => node.parentElement.closest('.comment-anchor, script, style')
+          ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_ACCEPT,
+      });
+      let last = null;
+      while (walker.nextNode()) {
+        if (/\S/.test(walker.currentNode.textContent)) last = walker.currentNode;
       }
-
-      // ID 不存在的话，说明压根就没评论，不用查询了
-      if (toc.chapter_id === undefined) {
-        this.set_menu("comments")
-        return;
+      if (!last) return null;
+      const end = last.textContent.search(/\s*$/);
+      const range = doc.createRange();
+      range.setStart(last, end - 1);
+      range.setEnd(last, end);
+      const rects = Array.from(range.getClientRects()).filter(rect => rect.width || rect.height);
+      return rects[rects.length - 1] || null;
+    },
+    // 气泡紧跟段落最后一个字，与末行垂直居中，不另起一行。
+    // 末行写满时允许伸进页边距（body 的右内边距），再多就会被翻页窗口裁掉，此时把气泡向左收回页内。
+    fit_comment_icon: function (icon, anchor, paragraph) {
+      icon.style.left = '';
+      icon.style.top = '';
+      const doc = paragraph.ownerDocument;
+      const spot = anchor.getBoundingClientRect();
+      const char = this.last_char_rect(paragraph);
+      if (char) {
+        icon.style.left = `${char.right - spot.left}px`;
+        icon.style.top = `${char.top + char.height / 2 - spot.top}px`;
+      }
+      const box = icon.getBoundingClientRect();
+      const mid = box.top + box.height / 2;
+      // 分栏（翻页）模式下段落可能跨栏，取气泡所在的那一栏片段
+      const fragment = Array.from(paragraph.getClientRects()).find(r => box.left >= r.left - 1 && box.left <= r.right + 1 && mid >= r.top - 1 && mid <= r.bottom + 1) || paragraph.getBoundingClientRect();
+      const margin = parseFloat(doc.defaultView.getComputedStyle(doc.body).paddingRight) || 0;
+      const overflow = box.right - (fragment.right + Math.max(margin - 2, 0));
+      if (overflow > 0) icon.style.left = `${(parseFloat(icon.style.left) || 0) - overflow}px`;
+    },
+    refit_comment_icons: function () {
+      for (const contents of this.rendition?.getContents() || []) {
+        contents.document.querySelectorAll('.comment-anchor').forEach(anchor => {
+          const icon = anchor.querySelector('.comment-icon');
+          if (icon && anchor.parentElement) this.fit_comment_icon(icon, anchor, anchor.parentElement);
+        });
+      }
+    },
+    // 目录中从页首章节到页尾章节（含两端）的每一章，配上它所在的正文文档；没有渲染出来的跳过。
+    tocs_between: function (start, end, contents_list) {
+      const visible = [start];
+      if (!end || end.toc === start.toc) return visible;
+      const flat = [];
+      const collect = items => items.forEach(item => { flat.push(item); if (item.subitems?.length) collect(item.subitems); });
+      collect(this.toc_items || []);
+      const from = flat.indexOf(start.toc);
+      const to = flat.indexOf(end.toc);
+      if (from >= 0 && to > from) {
+        for (const toc of flat.slice(from + 1, to)) {
+          const href = String(toc.href || '').split('#')[0];
+          const contents = contents_list.find(c => this.book.spine.get(c.sectionIndex)?.href === href);
+          if (contents) visible.push({ contents, toc });
+        }
       }
-      const url = `/api/review/list?book_id=${this.book_id}&chapter_id=${toc.chapter_id}&segment_id=${segment_id}&cfi=${cfi}`;
-      this.$backend(url).then(rsp => {
-        this.comments = rsp.data.list;
-        this.set_menu("comments")
-        // this.set_menu("comments");
-      })
+      visible.push(end);
+      return visible;
+    },
+    panel_width: function (name) {
+      return Math.min(this.panel_max_width, Math.max(PANEL_MIN_WIDTH, this.panel_widths[name] || SIDE_PANELS[name].width));
+    },
+    set_panel_width: function (name, width) {
+      this.panel_widths = { ...this.panel_widths, [name]: width };
+    },
+    reset_panel_width: function (name) {
+      this.set_panel_width(name, SIDE_PANELS[name].width);
+      this.save_panel_widths();
+    },
+    save_panel_widths: function () {
+      try { localStorage.setItem(PANEL_WIDTHS_KEY, JSON.stringify(this.panel_widths)); } catch (error) { /* noop */ }
+    },
+    // 侧边栏宽度以 CSS 变量交给样式表（面板浮层不在本组件的 DOM 树里）。
+    apply_panel_widths: function () {
+      for (const name of Object.keys(SIDE_PANELS)) {
+        document.documentElement.style.setProperty(`--candle-panel-${name}-width`, `${this.panel_width(name)}px`);
+      }
+    },
+    on_window_resize: function () {
+      this.window_width = window.innerWidth;
+      this.is_wide_screen = window.innerWidth >= 850;
+    },
+    // 当前页上出现的章节。
+    visible_chapters: function () {
+      const tocs = this.visible_tocs.length ? this.visible_tocs.map(item => item.toc) : [this.current_toc];
+      const chapters = tocs.map(toc => String(toc?.label || '').trim()).filter(Boolean);
+      return chapters.length ? [...new Set(chapters)] : [this.comment_chapter];
     },
-    on_login_user: function(user_data) {
-      this.user = user_data;
-      this.is_login = true;
+    refresh_comment_icons: function () {
+      this.comments_request++;
+      if (!this.rendition) return;
+      for (const contents of this.rendition.getContents()) {
+        contents.document.querySelectorAll('.comment-anchor, .comment-icon').forEach(icon => icon.remove());
+      }
+      if (!this.comments_enabled) return;
+      const visible = this.visible_tocs.length ? this.visible_tocs : [{ toc: this.current_toc }];
+      const rendered = this.rendition.getContents();
+      for (const item of visible) {
+        const toc = item.toc;
+        if (!toc) continue;
+        delete toc.load_time;
+        const contents = rendered.includes(item.contents) ? item.contents
+          : toc.elem && rendered.find(c => c.document === toc.elem.ownerDocument);
+        if (contents) this.load_comments_summary(contents, toc);
+      }
     },
     retryLoad: function() {
       // 重置状态并重新加载电子书
@@ -1182,8 +1647,8 @@ export default {
           this.loading = true;
         }, 50);
 
-        // 清除可能存在的旧定时器
-        clearTimeout(this.loadingTimeout);
+        // 停掉还在进行的上一次加载，避免两份正文叠在一起
+        try { this.rendition?.destroy(); this.book?.destroy(); } catch (error) { /* noop */ }
 
         // 重新初始化并加载电子书
         this.book = ePub(this.book_url);
@@ -1198,14 +1663,7 @@ export default {
         this.init_listeners();
         this.init_themes();
 
-        // 重新设置超时定时器
-        this.loadingTimeout = setTimeout(() => {
-          if (this.loading) {
-            console.warn('电子书加载超时，显示提示框');
-            this.loading = false;
-            this.showTimeoutDialog = true;
-          }
-        }, 10000);
+        this.start_load_timer();
 
         // 使用 book_url 作为唯一标识，为每个书籍存储独立的阅读位置
         const positionKey = `lastReadPosition_${this.book_url}`;
@@ -1215,33 +1673,53 @@ export default {
           const target = savedPosition || this.display_url;
           return target ? this.rendition.display(target) : this.rendition.display();
         })
-        .then(() => {
-          clearTimeout(this.loadingTimeout);
-          // 确保覆盖层隐藏
-          this.loading = false;
-        })
-        .catch(error => {
-          clearTimeout(this.loadingTimeout);
-          console.error('加载电子书失败:', error);
-          // 确保覆盖层隐藏并显示错误对话框
-          this.loading = false;
-          this.showTimeoutDialog = true;
-        });
+        .then(this.on_book_loaded)
+        .catch(this.on_book_load_failed);
 
         // 监听 relocated 事件，保存当前阅读位置，使用 book_url 作为唯一标识
         this.rendition.on('relocated', (location) => {
           localStorage.setItem(positionKey, location.start.cfi);
         });
       } catch (error) {
-        console.error('重试加载过程中出现错误:', error);
-        // 确保覆盖层隐藏并显示错误对话框
-        this.loading = false;
-        this.showTimeoutDialog = true;
+        this.on_book_load_failed(error);
       }
     },
+    // 超过 LOAD_TIMEOUT_MS 仍未显示正文时提示「加载较慢」，但不中断加载；加载完成后自动关闭提示。
+    start_load_timer: function () {
+      clearTimeout(this.loadingTimeout);
+      this.load_failed = false;
+      this.loadingTimeout = setTimeout(() => {
+        if (this.loading) {
+          console.warn('电子书加载较慢，显示提示框');
+          this.showTimeoutDialog = true;
+        }
+      }, LOAD_TIMEOUT_MS);
+    },
+    on_book_loaded: function () {
+      clearTimeout(this.loadingTimeout);
+      this.loading = false;
+      this.showTimeoutDialog = false;
+    },
+    on_book_load_failed: function (error) {
+      clearTimeout(this.loadingTimeout);
+      console.error('加载电子书失败:', error);
+      this.loading = false;
+      this.load_failed = true;
+      this.showTimeoutDialog = true;
+    },
+  },
+  watch: {
+    panel_widths: function () { this.apply_panel_widths(); },
+    panel_max_width: function () { this.apply_panel_widths(); },
+  },
+  beforeUnmount: function () {
+    window.removeEventListener('resize', this.on_window_resize);
   },
   mounted: function () {
-    if (this.initial_book_id) this.book_id = Number(this.initial_book_id);
+    try { this.panel_widths = JSON.parse(localStorage.getItem(PANEL_WIDTHS_KEY) || '{}') || {}; } catch (error) { this.panel_widths = {}; }
+    this.apply_panel_widths();
+    window.addEventListener('resize', this.on_window_resize);
+
     const link = document.createElement('link');
     link.rel = 'stylesheet';
     link.type = 'text/css';
@@ -1258,51 +1736,18 @@ export default {
       for (const k in saved) {
         if (saved[k] !== undefined) this.settings[k] = saved[k];
       }
-      console.log("加载设置：", savedSettings);
+      Object.assign(this.settings, normalizeNoteSettings(saved));
+      // 旧的总开关只在迁移时读一次，之后不再保存，否则重新打开子开关后又会被它压回去。
+      delete this.settings.notes_enabled;
+      delete this.settings.show_annotations;
     }
+    this.initialize_annotations();
+    this.load_user();
     this.is_debug_signal = this.debug;
     this.is_debug_click = this.debug;
 
-    // 添加加载超时机制，10秒后显示提示框
-    this.loadingTimeout = setTimeout(() => {
-      if (this.loading) {
-        console.warn('电子书加载超时，显示提示框');
-        this.loading = false;
-        this.showTimeoutDialog = true;
-      }
-    }, 10000);
-
+    this.start_load_timer();
     this.loading = true;
-    const url = `/api/review/me?count=true`;
-    this.$backend(url).then(rsp => {
-      if (rsp.err == "user.need_login") {
-        this.is_login = false;
-      } else if (rsp.err == "ok") {
-        this.unread_count = rsp.data.count;
-      } else if (rsp.err === "network_error") {
-        // 处理网络错误，不改变用户登录状态
-        console.log('网络错误，无法获取未读消息数，保持当前登录状态');
-      }
-    })
-    .catch(error => {
-      console.error('获取未读消息数失败:', error);
-    })
-
-    this.$backend(`/api/user/info`).then(rsp => {
-      if (rsp.err == "ok") {
-        this.user = rsp.data;
-      } else if (rsp.err === "network_error") {
-        // 处理网络错误，不设置用户信息，保持当前状态
-        console.log('网络错误，无法获取用户信息，保持当前状态');
-      } else {
-        // 其他错误，如用户不存在，设置为未登录
-        this.user = null;
-      }
-    })
-    .catch(error => {
-      console.error('获取用户信息失败:', error);
-    })
-
 
     this.book = ePub(this.book_url);
 
@@ -1318,15 +1763,6 @@ export default {
       console.log(metadata);
       this.book_meta = metadata;
       this.book_title = metadata.title;
-      const url = `/api/review/book?title=${this.book_title}`;
-      this.$backend(url).then(rsp => {
-        if (rsp.err == "ok") {
-          this.book_id = rsp.data.id;
-        }
-      })
-      .catch(error => {
-        console.error('获取书籍ID失败:', error);
-      })
     })
     .catch(error => {
       console.error('加载书籍元数据失败:', error);
@@ -1356,8 +1792,7 @@ export default {
       return target ? this.rendition.display(target) : this.rendition.display();
     })
     .then(() => {
-      clearTimeout(this.loadingTimeout);
-      this.loading = false;
+      this.on_book_loaded();
 
       // 初始化亮度、字体大小，并在正文渲染后再应用一次主题（确保背景图/透明/文字色就位）
       const brightness = this.settings.brightness / 100;
@@ -1365,12 +1800,7 @@ export default {
       this.rendition.themes.fontSize(this.settings.font_size + 'px');
       this.apply_theme(this.settings.theme);
     })
-    .catch(error => {
-      clearTimeout(this.loadingTimeout);
-      console.error('加载电子书失败:', error);
-      this.loading = false;
-      this.showTimeoutDialog = true;
-    })
+    .catch(this.on_book_load_failed)
   },
   data: () => ({
     loading: true,
@@ -1387,6 +1817,8 @@ export default {
       theme_day: "white",
       theme_night: "grey",
       show_comments: true,
+      show_selection_toolbar: true,
+      notes_settings_version: 2,
       paging_control: "mouse_and_keyboard",
       wheel_paging: true,
     },
@@ -1394,11 +1826,9 @@ export default {
     wide_screen: 1000, // 宽屏尺寸
     comments_refresh_time: 10 * 60 * 100, // 10min
 
-    user: null,
-    is_login: true,
+    user: null, // 当前读者，由宿主回调提供；游客为 null
     book_title: "",
     book_meta: null,
-    book_id: 0,
     alert_msg: "秉烛夜读",
     rendition: null,
     auto_close: false,
@@ -1408,38 +1838,60 @@ export default {
       value: "",
       panels: {
         toc: false,
-        more: false,
         settings: false,
-        comments: false,
+        annotations: false,
         ai: false,
       }
     },
     theme_mode: "day",
     toc_items: [],
-    comments: [],
-    book_reviews: [], // 本书评论 feed（来自 /api/review/book/list）
-    book_review_sort: 'latest', // 本书评论排序：latest | hot
-    show_login: false, // 登录对话框（评论面板「点击登录」）
-    show_user_center: false, // 用户设置弹层（评论面板 ⚙️）
-    comments_location: {}, // 评论内容的位置
+    panel_trigger: null,
+    panel_closing: null,
+    panel_entry_ref: 'panelEntryAnnotations',
+    comments_request: 0,
+    annotation_repository: null,
+    annotation_chapter_request: 0,
+    annotation_saving: false,
+    annotation_editor_open: false,
+    annotation_editor_location: null,
+    annotation_editor_record: null, // 正在编辑的已有评论
+    annotation_editor_type: 'note', // note | book_comment
+    annotation_editor_content: "",
+    annotation_editor_error: "",
+    annotation_editor_private: false,
+    comment_paragraph: null, // 「本段评论」当前所指的段落
+    selection_preview_rects: [],
+    annotation_feedback_visible: false,
+    annotation_feedback_message: "",
+    annotation_feedback_error: false,
+    rendered_annotations: [],
+    rendered_annotation_ids: new Set(),
     selected_location: {}, // 选中内容的位置
 
     current_toc_title: "",
     current_toc: null, // 当前阅读的章节对象
     current_toc_progress: "",
-    last_toc_label: "", // 上一次的章节标题，用于检测章节变化
+    last_toc_label: "", // 上一次的可见章节标题，用于检测章节变化
+    visible_tocs: [], // 当前屏上出现的章节及其正文文档
+    panel_widths: {}, // 宽屏侧边栏的宽度（读者拖动调整，按面板记住）
+    window_width: typeof window === 'undefined' ? 1024 : window.innerWidth,
+    is_wide_screen: typeof window !== 'undefined' && window.innerWidth >= 850,
+    PANEL_MIN_WIDTH,
 
     toolbar_left: -999,
     toolbar_top: 0,
 
     is_debug_signal: false,
     is_debug_click: false,
-    unread_count: 0,
     is_handlering_selected_content: false,
+    mouse_down_point: null,
+    selection_active: false, // epub.js 报告选中文字后为 true，取消选中或收起工具栏后复位
     check_if_selected_content: false,
     showTimeoutDialog: false,
+    load_failed: false, // 区分「加载较慢」与「加载失败」
     show_theme_dialog: false,
     audiobook_open: false,
+    audiobook_repository: null,
   })
 }
 </script>
@@ -1481,10 +1933,141 @@ export default {
 }
 
 #comments-toolbar {
-  position: absolute;
+  position: fixed;
   left: 0;
   top: 0;
   z-index: 999;
+  width: max-content;
+  max-width: calc(100vw - 16px);
+  border: 1px solid rgba(var(--v-theme-on-surface), 0.3);
+  border-radius: 12px;
+  background: rgb(var(--v-theme-surface));
+  color: rgba(var(--v-theme-on-surface), var(--v-high-emphasis-opacity));
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.18), 0 3px 8px rgba(0, 0, 0, 0.1),
+    inset 0 1px 0 rgba(255, 255, 255, 0.12);
+}
+
+.selection-toolbar-actions {
+  display: flex;
+  gap: 2px;
+  padding: 4px;
+  border-radius: inherit;
+  overflow-x: auto;
+  scrollbar-width: thin;
+}
+
+#comments-toolbar .selection-toolbar-action {
+  flex: 0 0 auto;
+  min-width: 0;
+  width: auto;
+  height: 36px;
+  padding: 0 8px;
+  border-radius: 8px;
+  font-size: 12px;
+  font-weight: 500;
+  letter-spacing: 0;
+  color: inherit;
+  transition: background-color 140ms ease;
+}
+
+#comments-toolbar .v-btn__content {
+  display: flex;
+  flex-direction: row;
+  gap: 4px;
+}
+
+#comments-toolbar .selection-toolbar-action span {
+  white-space: nowrap;
+  line-height: 1.3;
+}
+
+#comments-toolbar .selection-toolbar-action:focus-visible {
+  outline: 2px solid rgb(var(--v-theme-primary));
+  outline-offset: -2px;
+  background: rgba(var(--v-theme-primary), 0.08);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  #comments-toolbar .selection-toolbar-action { transition: none; }
+}
+
+.selection-preview {
+  position: fixed;
+  z-index: 998;
+  pointer-events: none;
+  background: rgba(56, 121, 219, 0.34);
+  border-radius: 2px;
+}
+
+.annotation-editor-dialog.v-dialog > .v-overlay__content {
+  margin: 16px;
+  width: calc(100% - 32px);
+}
+
+.annotation-editor-dialog .v-overlay__content > .annotation-editor-card.v-card {
+  max-height: calc(100vh - 32px);
+  max-height: calc(100dvh - 32px);
+  border: 1px solid rgba(var(--v-theme-on-surface), 0.1);
+  border-radius: 16px;
+  box-shadow: 0 24px 64px rgba(0, 0, 0, 0.24);
+}
+
+.annotation-editor-header {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 18px 20px 12px 24px;
+}
+
+.annotation-editor-header h2 { font-size: 20px; font-weight: 600; line-height: 1.5; }
+.annotation-editor-dialog .annotation-editor-card.v-card > .annotation-editor-body.v-card-text { padding: 4px 24px 0; overflow-y: auto; }
+.annotation-reference-heading { display: flex; gap: 16px; align-items: baseline; margin-bottom: 8px; font-size: 12px; line-height: 1.5; }
+.annotation-reference-heading > :first-child { flex: 0 0 auto; font-weight: 500; }
+.annotation-reference-chapter { min-width: 0; margin-left: auto; overflow: hidden; white-space: nowrap; text-overflow: ellipsis; color: rgba(var(--v-theme-on-surface), 0.7); }
+
+.annotation-editor-quote {
+  max-height: 112px;
+  margin: 0;
+  overflow-y: auto;
+  padding: 12px 14px;
+  background: rgba(var(--v-theme-on-surface), 0.035);
+  color: rgb(var(--v-theme-on-surface));
+  border-left: 2px solid rgba(var(--v-theme-on-surface), 0.28);
+  border-radius: 0 8px 8px 0;
+  font-family: "Songti SC", "Noto Serif CJK SC", serif;
+  font-size: 14px;
+  line-height: 1.8;
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+}
+
+.annotation-editor-hint { margin: 8px 0 0; font-size: 12px; line-height: 1.6; color: rgba(var(--v-theme-on-surface), 0.7); }
+.annotation-editor-input { margin-top: 22px; }
+.annotation-editor-input .v-field { border-radius: 10px; background: rgb(var(--v-theme-background)); }
+.annotation-editor-input textarea { font-size: 15px; line-height: 1.7; }
+.annotation-editor-footer { flex: 0 0 auto; padding: 16px 24px; border-top: 1px solid rgba(var(--v-theme-on-surface), 0.1); }
+.annotation-visibility-row { display: flex; align-items: center; gap: 8px; }
+.annotation-visibility-label { min-width: 0; font-size: 13px; line-height: 1.5; cursor: pointer; }
+.annotation-visibility-label-disabled { opacity: 0.6; cursor: default; }
+.annotation-visibility { flex: 0 0 auto; --v-input-control-height: 36px; }
+.annotation-editor-card .annotation-editor-actions { gap: 8px; padding: 14px 0 0; min-height: 0; }
+.annotation-editor-actions .v-btn { min-width: 80px; height: 40px; border-radius: 8px; letter-spacing: 0; }
+.annotation-editor-card .v-btn:focus-visible, .annotation-editor-quote:focus-visible { outline: 2px solid rgb(var(--v-theme-primary)); outline-offset: 2px; }
+
+@media (max-width: 360px) {
+  .annotation-editor-header { padding-inline: 16px 12px; }
+  .annotation-editor-dialog .annotation-editor-card.v-card > .annotation-editor-body.v-card-text,
+  .annotation-editor-footer { padding-inline: 16px; }
+}
+
+/* 阅读器占满整个页面：页面本身固定不滚动，iOS 上拖动正文时整页不会回弹，地址栏也不会收起导致正文重新排版。 */
+html, body {
+  position: fixed;
+  inset: 0;
+  overflow: hidden;
+  overscroll-behavior: none;
 }
 
 #main {
@@ -1546,6 +2129,46 @@ export default {
   position: fixed !important;
 }
 
+/* 评论抽屉占底部菜单上方可用区域的 90%，顶部 10% 留给阅读上下文与点击收起。 */
+.v-bottom-sheet.annotation-bottom-sheet > .v-bottom-sheet__content.v-overlay__content { height: 90%; max-height: 90%; }
+.annotation-sheet-body { height: 100%; min-height: 0; }
+.annotation-editor-book-hint { margin: 0 0 4px; }
+
+/* 桌面端改为覆盖式侧边栏：目录在左，评论和设置在右；不压缩正文宽度，避开顶部栏，底部菜单保持可用。 */
+@media (min-width: 850px) {
+  .v-bottom-sheet.reader-side-left > .v-bottom-sheet__content.v-overlay__content,
+  .v-bottom-sheet.reader-side-right > .v-bottom-sheet__content.v-overlay__content {
+    align-self: flex-end;
+    height: calc(100% - 48px) !important;
+    max-height: none !important;
+    margin: 0;
+    overflow-y: auto;
+    border-radius: 0;
+    background: rgb(var(--v-theme-surface));
+    /* Vuetify 给面板内容加了 0.2s 的 transition: all，拖动分隔条时宽度会追着指针慢半拍；只保留滑入滑出的动画。 */
+    transition-property: transform, opacity;
+  }
+  .v-bottom-sheet.reader-side-right > .v-bottom-sheet__content.v-overlay__content { left: auto; right: 0; width: var(--candle-panel-annotations-width, 420px); }
+  .v-bottom-sheet.reader-side-left > .v-bottom-sheet__content.v-overlay__content { left: 0; right: auto; width: var(--candle-panel-toc-width, 300px); }
+  .v-bottom-sheet.settings-bottom-sheet.reader-side-right > .v-bottom-sheet__content.v-overlay__content { width: var(--candle-panel-settings-width, 380px); }
+}
+
+/* 小屏会同时显示目录、主题、评论等入口；覆盖 Vuetify 的按钮最小宽度，避免两端入口被裁掉。 */
+.v-bottom-navigation .v-bottom-navigation__content > .v-btn {
+  min-width: 0 !important;
+  flex: 1 1 0;
+  padding-inline: 3px !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .annotation-bottom-sheet .v-overlay__content,
+  .annotation-editor-dialog .v-overlay__content,
+  .annotation-feedback .v-snackbar__wrapper {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+
 /* 底部安全区填充条：仅占 home indicator 那条（无安全区设备高度为 0，不可见）。
    纯色 background（iOS 安全区只认 background-color）。z-index 低于底部导航(1004)，
    导航显示时被其覆盖、隐藏(display:none)时露出 foot 色，与底图下沿衔接。 */
diff --git a/src/components/Guest.vue b/src/components/Guest.vue
deleted file mode 100644
index 0b58766..0000000
--- a/src/components/Guest.vue
+++ /dev/null
@@ -1,132 +0,0 @@
-<template>
-    <!-- 未登录的游客状态  -->
-    <v-card title="登录到书评系统">
-        <v-divider></v-divider>
-        <v-card-item>
-            <!-- 登录 -->
-            <v-form v-if="mode == 'login'" @submit.prevent="do_login">
-                <v-text-field prepend-icon="mdi-email" v-model="email" label="邮箱" type="text" autocomplete="old-email"></v-text-field>
-                <v-text-field prepend-icon="mdi-lock" v-model="password" label="密码" type="password"></v-text-field>
-                <v-btn type="submit" color="primary">登录</v-btn>
-            </v-form>
-
-            <!-- 重置 -->
-            <v-form v-else-if="mode == 'forget'" @submit.prevent="do_reset">
-                <v-text-field prepend-icon="mdi-email" v-model="email" label="邮箱" type="text" autocomplete="old-email"></v-text-field>
-                <v-btn type="submit" color="red">重置密码</v-btn>
-            </v-form>
-
-            <!-- 注册 -->
-            <v-form ref="form" v-else-if="mode == 'signup'" @submit.prevent="do_signup">
-                <v-text-field required prepend-icon="mdi-email" v-model="email" label="邮箱" type="text"
-                    autocomplete="new-email" :rules="[rules.email]"></v-text-field>
-                <v-text-field required prepend-icon="mdi-guy-fawkes-mask" v-model="nickname" label="昵称" type="text"
-                    autocomplete="new-nickname" :rules="[rules.nick]"></v-text-field>
-                <v-btn type="submit" color="green">注册</v-btn>
-                <p class="text-small"> * 账号密码将随机生成，并发往邮箱</p>
-            </v-form>
-
-        </v-card-item>
-
-        <v-alert v-if="alert.msg" :type="alert.type">{{ alert.msg }}</v-alert>
-
-        <v-divider></v-divider>
-
-        <v-card-actions>
-            <v-btn v-if="mode == 'login'" @click="mode = 'forget'" text="忘记密码?"></v-btn>
-            <v-btn v-if="mode != 'login'" @click="mode = 'login'" text="登录账号"></v-btn>
-            <v-spacer></v-spacer>
-            <v-btn @click="mode = 'signup'" text="快速注册"></v-btn>
-        </v-card-actions>
-
-
-    </v-card>
-</template>
-
-<script>
-export default {
-    data: () => ({
-        mode: 'login',
-
-        email: "",
-        password: "",
-        password2: "",
-        nickname: "",
-        failmsg: "",
-        validmsg: "",
-        rules: {
-            nick: v => v.length >= 2 || '昵称需至少包含两个字符',
-            email: function (email) {
-                var re = /^(([^<>()[\]\\.,;:\s@"]+(\.[^<>()[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
-                return re.test(email) || "无效的邮箱地址";
-            },
-        },
-
-        alert: {
-            type: "error",
-            msg: "",
-        },
-    }),
-    head: () => ({
-        title: "登录"
-    }),
-    computed: {
-    },
-    methods: {
-        do_login: function () {
-            var data = new URLSearchParams();
-            data.append("email", this.email);
-            data.append("password", this.password);
-            this.$backend("/api/user/sign_in", {
-                method: "POST",
-                body: data,
-            }).then((rsp) => {
-                if (rsp.err != "ok") {
-                    this.alert.type = "error";
-                    this.alert.msg = rsp.msg;
-                } else {
-                    this.$emit("login", rsp.data)
-                }
-            });
-        },
-        do_reset: function () {
-            var data = new URLSearchParams();
-            data.append("email", this.email);
-            this.$backend("/api/user/reset", {
-                method: "POST",
-                body: data,
-            }).then((rsp) => {
-                if (rsp.err == "ok") {
-                    this.alert.type = "success";
-                    this.alert.msg = "重置成功！请查阅密码通知邮件。";
-                } else {
-                    this.alert.type = "error";
-                    this.alert.msg = rsp.msg;
-                }
-            });
-        },
-        do_signup: function () {
-            if (!this.$refs.form.validate()) {
-                return false;
-            }
-
-            var data = new URLSearchParams();
-            data.append('email', this.email);
-            data.append('nickname', this.nickname);
-            this.$backend('/api/user/sign_up', {
-                method: 'POST',
-                body: data,
-            }).then(rsp => {
-                if (rsp.err != 'ok') {
-                    this.failmsg = rsp.msg;
-                } else {
-                    this.alert.type = "success";
-                    this.alert.msg = "注册成功！请查阅密码通知邮件。";
-                    this.mode = 'login';
-                }
-            });
-        }
-    },
-}
-
-</script>
diff --git a/src/components/PanelResizer.vue b/src/components/PanelResizer.vue
new file mode 100644
index 0000000..e04e90b
--- /dev/null
+++ b/src/components/PanelResizer.vue
@@ -0,0 +1,154 @@
+<template>
+  <div class="panel-resizer" :class="{ dragging }" :style="edge_style"
+    role="separator" aria-orientation="vertical" :aria-label="label" :aria-valuenow="Math.round(width)" :aria-valuemin="min" :aria-valuemax="max"
+    tabindex="0" @pointerdown="start" @keydown="on_key" @dblclick="$emit('reset')">
+    <span class="panel-resizer-knob" aria-hidden="true"></span>
+  </div>
+</template>
+
+<script>
+// 宽屏侧边栏的宽度调整条：9px 热区覆盖在面板真实边界上（不占布局），1px 分隔线与边界重合，中间是 8×24 的胶囊。
+// 模板根节点前不能放注释：开发模式下注释会让根节点变成片段，$el 就不再是热区本身。
+const KEY_STEP = 16
+
+export default {
+  name: 'PanelResizer',
+  props: {
+    side: { type: String, default: 'right' }, // 面板所在的一侧：left 为目录，right 为评论和设置
+    width: { type: Number, required: true },
+    min: { type: Number, default: 260 },
+    max: { type: Number, default: 720 },
+    label: { type: String, default: '调整面板宽度' },
+  },
+  emits: ['update:width', 'commit', 'reset'],
+  data: () => ({ dragging: false, start_x: 0, start_width: 0 }),
+  computed: {
+    // 热区以面板边界为中心：左侧面板的边界在 width 处，右侧面板的边界在 100% - width 处；分隔线画在热区内 4px。
+    edge_style: function () {
+      return { left: this.side === 'left' ? `calc(${this.width}px - 4px)` : `calc(100% - ${this.width}px - 4px)` }
+    },
+  },
+  beforeUnmount: function () {
+    this.stop()
+  },
+  methods: {
+    clamp: function (value) {
+      return Math.min(this.max, Math.max(this.min, Math.round(value)))
+    },
+    start: function (event) {
+      if (event.button !== 0) return
+      event.preventDefault()
+      this.dragging = true
+      this.start_x = event.clientX
+      this.start_width = this.width
+      // 指针捕获：拖过正文 iframe、离开热区时也能持续收到移动事件。
+      try { event.currentTarget.setPointerCapture(event.pointerId) } catch (error) { /* noop */ }
+      this.$el.addEventListener('pointermove', this.move)
+      this.$el.addEventListener('pointerup', this.end)
+      this.$el.addEventListener('pointercancel', this.end)
+      document.body.classList.add('resizing-pane')
+    },
+    move: function (event) {
+      if (!this.dragging) return
+      // 左侧面板向右拖变宽（+1），右侧面板向左拖变宽（-1）。
+      const direction = this.side === 'left' ? 1 : -1
+      this.$emit('update:width', this.clamp(this.start_width + direction * (event.clientX - this.start_x)))
+    },
+    end: function () {
+      if (!this.dragging) return
+      this.stop()
+      this.$emit('commit')
+    },
+    stop: function () {
+      this.dragging = false
+      this.$el?.removeEventListener?.('pointermove', this.move)
+      this.$el?.removeEventListener?.('pointerup', this.end)
+      this.$el?.removeEventListener?.('pointercancel', this.end)
+      document.body.classList.remove('resizing-pane')
+    },
+    on_key: function (event) {
+      // ArrowLeft / ArrowRight 每次移动边界 16px；Home 恢复默认宽度。
+      let next = null
+      if (event.key === 'ArrowLeft') next = this.width - KEY_STEP * (this.side === 'left' ? 1 : -1)
+      else if (event.key === 'ArrowRight') next = this.width + KEY_STEP * (this.side === 'left' ? 1 : -1)
+      else if (event.key !== 'Home') return
+      // 阅读器在页面上监听方向键翻页，这里处理过的按键不再往外传。
+      event.preventDefault()
+      event.stopPropagation()
+      if (next === null) return this.$emit('reset')
+      this.$emit('update:width', this.clamp(next))
+      this.$emit('commit')
+    },
+  },
+}
+</script>
+
+<style scoped>
+/* 覆盖在面板边界上的 9px 热区，不占布局。侧边栏的层级从 234 起，连续切换面板时 Vuetify 会逐层叠加；
+   这里取 900，在面板与遮罩之上，仍低于底部导航、各类对话框与全屏评论页。 */
+.panel-resizer {
+  --split-line: rgba(var(--v-border-color), var(--v-border-opacity));
+  position: fixed;
+  top: 48px;
+  bottom: 56px;
+  z-index: 900;
+  width: 9px;
+  padding: 0;
+  cursor: col-resize;
+  touch-action: none;
+  user-select: none;
+  outline: none;
+}
+.panel-resizer::before {
+  content: "";
+  position: absolute;
+  inset: 0 auto 0 4px;
+  width: 1px;
+  background: var(--split-line);
+}
+.panel-resizer-knob {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  box-sizing: border-box;
+  width: 8px;
+  height: 24px;
+  transform: translate(-50%, -50%);
+  border: 1px solid var(--split-line);
+  border-radius: 4px;
+  background: rgb(var(--v-theme-surface));
+  color: rgba(var(--v-theme-on-surface), 0.45);
+  pointer-events: none;
+}
+/* 两道握持刻度 */
+.panel-resizer-knob::before {
+  content: "";
+  position: absolute;
+  top: 7px;
+  left: 1px;
+  width: 4px;
+  height: 1px;
+  background: currentColor;
+  box-shadow: 0 4px 0 currentColor;
+}
+.panel-resizer:hover::before,
+.panel-resizer:focus-visible::before,
+.panel-resizer.dragging::before {
+  background: #2563eb;
+}
+.panel-resizer:hover .panel-resizer-knob,
+.panel-resizer:focus-visible .panel-resizer-knob,
+.panel-resizer.dragging .panel-resizer-knob {
+  color: #ffffff;
+  background: #2563eb;
+  border-color: #2563eb;
+}
+@media (prefers-reduced-motion: no-preference) {
+  .panel-resizer::before, .panel-resizer-knob { transition: background-color 0.12s, border-color 0.12s, color 0.12s; }
+}
+</style>
+
+<style>
+/* 拖动期间不选中文字，整页保持调整宽度的光标。 */
+body.resizing-pane, body.resizing-pane * { cursor: col-resize !important; user-select: none !important; }
+</style>
diff --git a/src/components/Settings.vue b/src/components/Settings.vue
index 043f2aa..a3afda4 100644
--- a/src/components/Settings.vue
+++ b/src/components/Settings.vue
@@ -1,6 +1,6 @@
 <template>
     <!-- 设置: 分别列出亮度、字体、背景、翻页、其他 五行设置项  -->
-    <v-list density="compact">
+    <v-list class="reader-settings" density="compact">
         <v-list-item class="my-2">
             <v-row class="align-center">
                 <v-col cols="2">
@@ -101,33 +101,15 @@
             </v-row>
         </v-list-item>
 
-        <v-list-item class="my-2">
-            <v-row class="align-center">
-                <v-col cols="2">
-                    <span density="compact">滚轮翻页</span>
-                </v-col>
-                <v-col cols="10">
-                    <v-btn-group variant="outlined" divided density="compact">
-                        <v-btn :active="opt.wheel_paging == true" @click='set_and_emit("wheel_paging", true)'>开启</v-btn>
-                        <v-btn :active="opt.wheel_paging == false" @click='set_and_emit("wheel_paging", false)'>关闭</v-btn>
-                    </v-btn-group>
-                </v-col>
-            </v-row>
-        </v-list-item>
-
-
-        <v-list-item class="my-2">
-            <v-row class="align-center">
-                <v-col cols="2">
-                    <span density="compact">章评*</span>
-                </v-col>
-                <v-col cols="10">
-                    <v-btn-group variant="outlined" divided density="compact">
-                        <v-btn :active="opt.show_comments == true" @click="set_and_emit('show_comments', true)">开启</v-btn>
-                        <v-btn :active="opt.show_comments == false" @click="set_and_emit('show_comments', false)">关闭</v-btn>
-                    </v-btn-group>
-                </v-col>
-            </v-row>
+        <v-list-item v-for="item in switch_options" :key="item.key" class="my-2" :data-setting="item.key">
+            <div class="setting-switch-row">
+                <label class="setting-switch-label"
+                    :id="`setting-${item.key}`" :for="`switch-${item.key}`">{{ item.label }}</label>
+                <v-switch :id="`switch-${item.key}`" class="setting-switch" :model-value="opt[item.key]"
+                    :aria-labelledby="`setting-${item.key}`"
+                    role="switch" color="primary" density="comfortable" inset hide-details
+                    @update:model-value="set_and_emit(item.key, $event)"></v-switch>
+            </div>
         </v-list-item>
 
         <v-list-item class="my-2">
@@ -153,7 +135,7 @@
 import { THEMES } from '@/themes'
 
 export default {
-    name: 'Settings',
+    name: 'ReaderSettings',
     emits: ['update', 'open-themes'],
     computed: {
         // 设置面板里的 4 个快捷图标（纯色主题）
@@ -171,6 +153,7 @@ export default {
             letter_spacing: this.settings?.letter_spacing || this.opt.letter_spacing,
             brightness: this.settings?.brightness || this.opt.brightness,
             show_comments: this.settings?.show_comments ?? this.opt.show_comments,
+            show_selection_toolbar: this.settings?.show_selection_toolbar ?? this.opt.show_selection_toolbar,
             paging_control: this.settings?.paging_control || this.opt.paging_control,
             wheel_paging: this.settings?.wheel_paging ?? this.opt.wheel_paging,
         };
@@ -213,11 +196,25 @@ export default {
             line_height: 1.5,
             letter_spacing: 0,
             brightness: 100,
+            show_comments: true,
+            show_selection_toolbar: true,
             paging_control: "mouse_and_keyboard",
             wheel_paging: true,
         },
+        switch_options: [
+            { key: 'wheel_paging', label: '使用鼠标滚轮翻页' },
+            { key: 'show_comments', label: '显示全部划线和评论' },
+            { key: 'show_selection_toolbar', label: '选中文字后显示工具栏' },
+        ],
         themes: THEMES,
     })
 }
 
 </script>
+
+<style scoped>
+.reader-settings { padding-inline: max(0px, calc((100% - 560px) / 2)); }
+.setting-switch-row { display: flex; align-items: center; gap: 16px; }
+.setting-switch-label { flex: 1; min-width: 0; line-height: 1.5; cursor: pointer; }
+.setting-switch { flex: 0 0 auto; --v-input-control-height: 36px; }
+</style>
diff --git a/src/components/UserCenter.vue b/src/components/UserCenter.vue
deleted file mode 100644
index 1ea0f25..0000000
--- a/src/components/UserCenter.vue
+++ /dev/null
@@ -1,285 +0,0 @@
-<template>
-  <v-card>
-    <v-card-title class="text-center"> 消息 </v-card-title>
-
-    <!-- 用户信息部分 -->
-    <div class="px-4 py-2">
-      <!-- 昵称 -->
-      <v-card class="mb-3 elevation-4 rounded-lg" subtitle="用户信息">
-        <v-list>
-          <v-list-item class="text-right" @click="alert_avatar">
-            <template #prepend>
-              <span>头像</span>
-            </template>
-            <template #append>
-              <v-avatar :image="user.avatar"></v-avatar>
-            </template>
-          </v-list-item>
-
-          <v-list-item class="text-right" :title="user.email">
-            <template #prepend>
-              <span>邮箱</span>
-            </template>
-          </v-list-item>
-
-          <v-list-item class="text-right" @click="editNickname = true" :title="user.nickname">
-            <template #prepend>
-              <span>昵称</span>
-            </template>
-            <template #append>
-              <v-icon>mdi-chevron-right</v-icon>
-            </template>
-          </v-list-item>
-
-          <v-list-item class="text-right" @click="editPassword = true" title="(点击更改)" append-icon="mdi-chevron-right">
-            <template #prepend>
-              <span>密码</span>
-            </template>
-          </v-list-item>
-
-          <v-list-item class="text-right" @click="checkLogout = true" append-icon="mdi-chevron-right">
-            <template #prepend>
-              <span>退出登录</span>
-            </template>
-          </v-list-item>
-
-        </v-list>
-
-      </v-card>
-    </div>
-
-    <!-- 用户信息部分 -->
-    <div class="px-4 py-2">
-      <!-- 昵称 -->
-      <v-card class="mb-3 elevation-4 rounded-lg" subtitle="章评互动信息">
-
-    <!-- 互动消息部分 -->
-    <v-list v-if="messages.length === 0" density="compact" class="mr-4">
-      <v-list-item class="my-4">
-        <v-list-item-title class="text-center">无新的互动消息</v-list-item-title>
-      </v-list-item>
-    </v-list>
-    <v-list id="book-comments" density="compact" class="mr-4">
-      <template v-for="c in messages" :key="c.id">
-        <v-list-item class="pr-0 align-self-start mb-4" :prepend-avatar="c.avatar" :subtitle="c.nickName + ' @《宿命之环》'">
-          <div class="my-2">{{ thumb_or_content(c) }}</div>
-          <v-card variant="tonal" color="surface-variant" :subtitle="'这一段写得真厉害哦'"></v-card>
-        </v-list-item>
-      </template>
-    </v-list>
-
-    </v-card>
-    </div>
-    <!-- 修改昵称对话框 -->
-    <v-dialog v-model="editAvatar" persistent>
-      <template #default>
-        <v-alert></v-alert>
-      </template>
-    </v-dialog>
-
-
-    <!-- 修改昵称对话框 -->
-    <v-dialog v-model="editNickname" persistent>
-      <template #default>
-        <v-card>
-          <v-card-title class="text-center">修改昵称</v-card-title>
-          <v-card-text>
-            <v-text-field v-model="newNickname" label="新昵称"></v-text-field>
-            <v-alert v-if="alert.msg" :type="alert.type" dismissible>{{ alert.msg }}</v-alert>
-          </v-card-text>
-          <v-card-actions>
-            <v-btn text @click="editNickname = false">取消</v-btn>
-            <v-btn text @click="saveNickname">保存</v-btn>
-          </v-card-actions>
-        </v-card>
-      </template>
-    </v-dialog>
-
-    <!-- 修改密码对话框 -->
-    <v-dialog v-model="editPassword" persistent z-index="2999">
-      <template #default>
-        <v-card>
-          <v-card-title class="text-center">修改密码</v-card-title>
-          <v-card-text>
-            <v-text-field v-model="oldPassword" label="当前密码"></v-text-field>
-            <v-text-field v-model="newPassword" label="新密码" :rules="[rules.pass]"></v-text-field>
-            <v-text-field v-model="examPassword" label="确认密码" :rules="[double_check_password]"></v-text-field>
-            <v-alert v-if="alert.msg" :type="alert.type" dismissible>{{ alert.msg }}</v-alert>
-          </v-card-text>
-          <v-card-actions>
-            <v-btn text @click="editPassword = false">取消</v-btn>
-            <v-btn text @click="savePassword">保存</v-btn>
-          </v-card-actions>
-        </v-card>
-      </template>
-    </v-dialog>
-
-
-    <!-- 修改昵称对话框 -->
-    <v-dialog v-model="checkLogout" persistent>
-      <template #default>
-        <v-card>
-          <v-card-title class="text-center">请确认</v-card-title>
-          <v-card-text>
-            是否要退出登录？
-            <v-alert v-if="alert.msg" :type="alert.type" dismissible>{{ alert.msg }}</v-alert>
-          </v-card-text>
-          <v-card-actions>
-            <v-btn text @click="checkLogout = false">取消</v-btn>
-            <v-btn text @click="do_logout">确认</v-btn>
-          </v-card-actions>
-        </v-card>
-      </template>
-    </v-dialog>
-
-
-</v-card>
-</template>
-
-<script>
-export default {
-  name: 'UserCenter',
-  props: ['messages', 'user'],
-  data: () => ({
-    editAvatar: false,
-    editNickname: false,
-    editPassword: false,
-    checkLogout: false,
-    alert: {
-      msg: '',
-      type: ''
-    },
-
-    newNickname: '',
-    oldPassword: '',
-    newPassword: '',
-    examPassword: '',
-    rules: {
-      pass: v => (20 >= v.length && v.length >= 8) || '8 ~ 20 characters',
-      nick: v => v.length >= 2 || 'Min 2 characters',
-      email: function (email) {
-        var re = /^(([^<>()[\.,;:@"]+([^<>()[\.,;:@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/;
-        return re.test(email) || "Invalid email format";
-      },
-    },
-  }),
-  watch: {
-    // 监听修改昵称弹窗关闭事件，清空输入框内容
-    editNickname(newVal) {
-      if (!newVal) {
-        this.newNickname = '';
-        this.alert.msg = '';
-      }
-    },
-    // 监听修改密码弹窗关闭事件，清空输入框内容
-    editPassword(newVal) {
-      if (!newVal) {
-        this.oldPassword = '';
-        this.newPassword = '';
-        this.examPassword = '';
-        this.alert.msg = '';
-      }
-    },
-    // 监听退出登录弹窗关闭事件，清空错误信息
-    checkLogout(newVal) {
-      if (!newVal) {
-        this.alert.msg = '';
-      }
-    },
-  },
-  methods: {
-    thumb_or_content: function (c) {
-      if (Math.random() > 0.5) {
-        return c.content;
-      } else {
-        return "赞了你的评论";
-      }
-    },
-    double_check_password: function (v) {
-      if (v.length < 8) {
-        return 'Min 8 characters';
-      }
-      return v == this.newPassword || "Password are not same."
-    },
-    alert_avatar: function () {
-      alert('请前往 https://cavatar.cn 更改')
-    },
-
-    saveNickname: function () {
-      // 清除之前的错误信息
-      this.alert.msg = "";
-      this.update_user({
-        nickname: this.newNickname,
-      }).then(() => {
-        this.editNickname = false;
-      }).catch(() => {
-        // 捕获错误，不关闭弹窗
-        console.log("修改昵称失败");
-      })
-    },
-    savePassword() {
-      if (this.examPassword != this.newPassword) {
-        this.alert.msg = "两次输入的密码不一致";
-        this.alert.type = "error";
-        return;
-      }
-      // 清除之前的错误信息
-      this.alert.msg = "";
-      this.update_user({
-        password0: this.oldPassword,
-        password1: this.newPassword,
-      }).then(() => {
-        // 只有当update_user成功时才会执行这里
-        this.editPassword = false;
-      }).catch(() => {
-        // 捕获错误，不关闭弹窗
-        console.log("修改密码失败");
-      })
-    },
-    update_user: function (new_info) {
-      this.user.nickName = this.newNickname;
-      return this.$backend(`/api/user/update`, {
-        method: 'POST',
-        body: JSON.stringify(new_info),
-      }).then((rsp) => {
-        if (rsp.err != 'ok') {
-          this.alert.msg = rsp.msg;
-          this.alert.type = "error";
-          throw new Error(rsp.msg);
-        }
-        this.$emit('update', rsp.data);
-      });
-    },
-    do_logout: function () {
-      // 清除之前的错误信息
-      this.alert.msg = "";
-      return this.$backend(`/api/user/sign_out`).then((rsp) => {
-        if (rsp.err != 'ok') {
-          this.alert.msg = rsp.msg;
-          this.alert.type = "error";
-          throw new Error(rsp.msg);
-        }
-        this.$emit('logout');
-        this.checkLogout = false;
-      }).catch(() => {
-        // 捕获错误，不关闭弹窗
-        console.log("退出登录失败");
-      });
-    },
-  },
-};
-</script>
-
-<style scoped>
-.v-card {
-  transition: box-shadow 0.3s ease;
-}
-
-.v-card:hover {
-  box-shadow: 0 8px 16px rgba(0, 0, 0, 0.2);
-}
-
-.v-btn {
-  text-transform: none;
-}
-</style>
diff --git a/src/components/comments/CommentItem.vue b/src/components/comments/CommentItem.vue
new file mode 100644
index 0000000..1661bba
--- /dev/null
+++ b/src/components/comments/CommentItem.vue
@@ -0,0 +1,98 @@
+<template>
+  <article class="comment-item" :class="{ 'comment-item--link': clickable }" :data-comment="record.id"
+    :data-mine="String(Boolean(record.is_mine))" @click="on_click">
+    <div class="comment-meta">
+      <span class="comment-author">{{ record.author_name || '书友' }}</span>
+      <span v-if="tags && record.annotation_type === 'highlight'" class="comment-tag">划线</span>
+      <span v-if="tags && record.annotation_type === 'book_comment'" class="comment-tag">整书评论</span>
+      <time class="comment-time">{{ time_text }}</time>
+    </div>
+    <p class="comment-content">
+      <span v-if="record.reply_to_name" class="comment-reply-to">回复 {{ record.reply_to_name }}：</span>{{ record.content || record.quote_text }}
+    </p>
+    <div v-if="interactive || private_replies || is_private || manageable" class="comment-footer">
+      <div v-if="interactive" class="comment-actions">
+        <button type="button" class="comment-vote" :aria-pressed="String(record.user_vote === 1)" :aria-label="`赞 ${record.like_count || 0}`"
+          @click.stop="$emit('vote', record, 1)">
+          <v-icon size="16" aria-hidden="true">{{ record.user_vote === 1 ? 'mdi-thumb-up' : 'mdi-thumb-up-outline' }}</v-icon>{{ record.like_count || 0 }}
+        </button>
+        <button type="button" class="comment-vote" :aria-pressed="String(record.user_vote === -1)" :aria-label="`踩 ${record.dislike_count || 0}`"
+          @click.stop="$emit('vote', record, -1)">
+          <v-icon size="16" aria-hidden="true">{{ record.user_vote === -1 ? 'mdi-thumb-down' : 'mdi-thumb-down-outline' }}</v-icon>{{ record.dislike_count || 0 }}
+        </button>
+        <button type="button" class="comment-reply" @click.stop="$emit('reply', record)">{{ reply_text }}</button>
+      </div>
+      <div v-else-if="private_replies" class="comment-actions">
+        <button type="button" class="comment-reply" @click.stop="$emit('reply', record)">{{ record.reply_count }} 条回复 · 仅你可见</button>
+      </div>
+      <!-- 右下角：私密标记（含划线，只有作者自己看得到），以及自己记录的修改、删除。 -->
+      <div v-if="is_private || manageable" class="comment-end">
+        <span v-if="is_private" class="comment-private">私密</span>
+        <template v-if="manageable">
+          <button v-if="record.annotation_type !== 'highlight'" type="button" class="comment-manage" @click.stop="$emit('edit', record)">修改</button>
+          <button type="button" class="comment-manage" @click.stop="$emit('remove', record)">删除</button>
+        </template>
+      </div>
+    </div>
+  </article>
+</template>
+
+<script>
+export default {
+  name: 'CommentItem',
+  emits: ['open', 'edit', 'remove', 'vote', 'reply'],
+  props: {
+    record: { type: Object, required: true },
+    // 列表中的主评论整条可点，进入评论详情页。
+    clickable: { type: Boolean, default: false },
+    // 「我的」与私密详情里显示类型标签（划线、整书评论）；私密标记不受此限，总在右下角显示。
+    tags: { type: Boolean, default: false },
+    // 主评论转为私密后，其下回复只读。
+    readonly: { type: Boolean, default: false },
+  },
+  computed: {
+    is_reply: function () { return Boolean(this.record.root_id) },
+    is_private: function () { return !this.is_reply && this.record.is_private !== false },
+    interactive: function () { return !this.readonly && !this.is_private },
+    manageable: function () { return Boolean(this.record.is_mine) && !this.readonly },
+    private_replies: function () { return this.clickable && this.is_private && this.record.reply_count > 0 },
+    reply_text: function () { return this.is_reply ? '回复' : `回复 ${this.record.reply_count || 0}` },
+    time_text: function () {
+      const value = this.record.created_at
+      const date = value ? new Date(value) : null
+      if (!date || Number.isNaN(date.getTime())) return value || ''
+      const minutes = Math.floor((Date.now() - date.getTime()) / 60000)
+      if (minutes < 1) return '刚刚'
+      if (minutes < 60) return `${minutes} 分钟前`
+      if (minutes < 60 * 24) return `${Math.floor(minutes / 60)} 小时前`
+      if (minutes < 60 * 24 * 30) return `${Math.floor(minutes / 60 / 24)} 天前`
+      return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`
+    },
+  },
+  methods: {
+    on_click: function () {
+      // 正在选中文字时不跳转。
+      if (this.clickable && !String(window.getSelection())) this.$emit('open', this.record)
+    },
+  },
+}
+</script>
+
+<style scoped>
+.comment-item { padding: 14px 0; }
+.comment-item--link { cursor: pointer; }
+.comment-meta { display: flex; align-items: center; gap: 8px; font-size: 12px; line-height: 1.5; color: rgba(var(--v-theme-on-surface), 0.7); }
+.comment-time { margin-left: auto; white-space: nowrap; }
+.comment-tag { padding: 0 6px; border-radius: 4px; font-size: 11px; color: rgb(var(--v-theme-primary)); background: rgba(var(--v-theme-primary), 0.12); }
+.comment-content { margin: 6px 0 0; font-size: 14px; line-height: 1.8; white-space: pre-wrap; overflow-wrap: anywhere; color: rgb(var(--v-theme-on-surface)); }
+.comment-reply-to { color: rgba(var(--v-theme-on-surface), 0.7); }
+.comment-manage { min-height: 32px; padding: 0 8px; border-radius: 6px; font-size: 13px; color: rgb(var(--v-theme-on-surface)); color: color-mix(in srgb, rgb(var(--v-theme-primary)) 60%, rgb(var(--v-theme-on-surface))); white-space: nowrap; }
+.comment-footer { display: flex; align-items: center; gap: 8px; margin-top: 4px; min-height: 24px; }
+.comment-end { display: flex; align-items: center; gap: 4px; margin: 0 -8px 0 auto; }
+.comment-private { padding: 0 6px; border-radius: 4px; font-size: 12px; line-height: 20px; white-space: nowrap; color: rgba(var(--v-theme-on-surface), 0.7); background: rgba(var(--v-theme-on-surface), 0.08); }
+.comment-actions { display: flex; align-items: center; gap: 4px; margin: 0 0 0 -8px; font-size: 13px; color: rgba(var(--v-theme-on-surface), 0.7); }
+.comment-actions button { display: inline-flex; align-items: center; gap: 4px; min-height: 32px; padding: 0 8px; border-radius: 6px; }
+.comment-actions button[aria-pressed=true] { color: rgb(var(--v-theme-on-surface)); color: color-mix(in srgb, rgb(var(--v-theme-primary)) 60%, rgb(var(--v-theme-on-surface))); font-weight: 600; }
+.comment-item button:focus-visible { outline: 2px solid rgb(var(--v-theme-primary)); outline-offset: 1px; }
+@media (hover: hover) { .comment-actions button:hover, .comment-manage:hover { background: rgba(var(--v-theme-on-surface), 0.08); } }
+</style>
diff --git a/src/components/comments/CommentList.vue b/src/components/comments/CommentList.vue
new file mode 100644
index 0000000..faf151e
--- /dev/null
+++ b/src/components/comments/CommentList.vue
@@ -0,0 +1,75 @@
+<template>
+  <div ref="scroller" class="comment-list" :aria-busy="String(state.loading)" @scroll.passive="maybe_load_more">
+    <div v-if="state.need_login && !state.items.length" class="comment-state">
+      <v-icon size="30">mdi-account-lock-outline</v-icon>
+      <p>登录后查看评论</p>
+      <v-btn variant="tonal" @click="$emit('login')">去登录</v-btn>
+    </div>
+    <div v-else-if="state.error && !state.items.length" class="comment-state" role="alert">
+      <v-icon size="30">mdi-alert-circle-outline</v-icon>
+      <p>评论暂时没能加载</p>
+      <p class="comment-state-hint">{{ state.error }}</p>
+      <v-btn variant="tonal" @click="$emit('retry')">重新加载</v-btn>
+    </div>
+    <div v-else-if="state.loading && !state.items.length" class="comment-state" role="status">
+      <v-progress-circular indeterminate size="28" color="primary"></v-progress-circular>
+      <p>正在加载评论…</p>
+    </div>
+    <div v-else-if="!state.items.length" class="comment-state">
+      <v-icon size="30">mdi-comment-text-outline</v-icon>
+      <p>{{ empty }}</p>
+      <slot name="empty"></slot>
+    </div>
+    <template v-else>
+      <comment-item v-for="record in state.items" :key="record.id" class="comment-list-item" :record="record" clickable :tags="tags"
+        @open="$emit('open', $event)" @reply="$emit('open', $event)" @edit="$emit('edit', $event)" @remove="$emit('remove', $event)"
+        @vote="(record, value) => $emit('vote', record, value)"></comment-item>
+      <div class="comment-load-status" role="status">
+        <template v-if="state.error">加载失败 <button type="button" class="comment-retry" @click="$emit('retry')">重试</button></template>
+        <template v-else-if="state.loading">正在加载更多评论…</template>
+        <template v-else-if="state.has_more">继续下滑，加载更多评论</template>
+        <template v-else>已显示全部评论</template>
+      </div>
+    </template>
+  </div>
+</template>
+
+<script>
+import CommentItem from './CommentItem.vue'
+
+export default {
+  name: 'CommentList',
+  components: { CommentItem },
+  emits: ['more', 'retry', 'login', 'open', 'edit', 'remove', 'vote'],
+  props: {
+    // { items, has_more, loading, error }
+    state: { type: Object, required: true },
+    empty: { type: String, default: '这里还没有公开评论' },
+    tags: { type: Boolean, default: false },
+  },
+  watch: {
+    // 首屏不足一页高度时没有滚动事件，加载完成后主动补一次检查。
+    'state.loading': function (loading) { if (!loading) this.$nextTick(this.maybe_load_more) },
+  },
+  methods: {
+    maybe_load_more: function () {
+      const el = this.$refs.scroller
+      if (!el || !el.clientHeight || this.state.loading || this.state.error || !this.state.has_more) return
+      if (el.scrollHeight - el.scrollTop - el.clientHeight <= 48) this.$emit('more')
+    },
+    scroll_to_top: function () {
+      if (this.$refs.scroller) this.$refs.scroller.scrollTop = 0
+    },
+  },
+}
+</script>
+
+<style scoped>
+.comment-list { flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain; padding: 0 20px; }
+.comment-list-item + .comment-list-item { border-top: 1px solid rgba(var(--v-border-color), var(--v-border-opacity)); }
+.comment-state { padding: 40px 12px; text-align: center; font-size: 14px; color: rgba(var(--v-theme-on-surface), 0.7); }
+.comment-state p { margin: 8px 0; }
+.comment-state-hint { font-size: 12px; }
+.comment-load-status { padding: 18px 0; text-align: center; font-size: 12px; color: rgba(var(--v-theme-on-surface), 0.7); }
+.comment-retry { color: rgb(var(--v-theme-on-surface)); color: color-mix(in srgb, rgb(var(--v-theme-primary)) 60%, rgb(var(--v-theme-on-surface))); padding: 4px 8px; }
+</style>
diff --git a/src/components/comments/ReaderComments.vue b/src/components/comments/ReaderComments.vue
new file mode 100644
index 0000000..c73fe7c
--- /dev/null
+++ b/src/components/comments/ReaderComments.vue
@@ -0,0 +1,443 @@
+<template>
+  <!-- 阅读中的评论抽屉：默认本章评论，也承载从选区或段尾气泡进入的本段评论。 -->
+  <section ref="drawer" class="reader-comments-drawer" aria-label="评论">
+    <div class="rc-grip" @pointerdown="on_drag_start" @pointermove="on_drag_move" @pointerup="on_drag_end" @pointercancel="on_drag_cancel">
+      <div class="rc-handle" aria-hidden="true"></div>
+      <header class="rc-head">
+        <strong>{{ drawer.scope === 'paragraph' ? '本段评论' : '本章评论' }}</strong>
+        <button ref="moreEntry" type="button" class="rc-more" @click="open_page">查看更多评论 <v-icon size="20" aria-hidden="true">mdi-chevron-right</v-icon></button>
+      </header>
+    </div>
+    <comment-list ref="drawerList" :state="drawer" @more="load(drawer)" @retry="retry(drawer)" @login="$emit('login')" @open="open_detail"
+      @edit="$emit('edit', $event)" @remove="ask_remove" @vote="vote"></comment-list>
+    <footer class="rc-footer">
+      <v-btn block color="primary" variant="flat" prepend-icon="mdi-plus" @click="write(drawer)">写评论</v-btn>
+    </footer>
+  </section>
+
+  <!-- 完整评论页：独立页面，占满整个内容区域，不保留阅读菜单或正文。 -->
+  <v-dialog :model-value="page_open" class="rc-standalone" fullscreen :scrim="false" transition="slide-x-reverse-transition"
+    aria-label="完整评论页" @update:model-value="$event || back()">
+    <section class="rc-page">
+      <nav class="rc-tabs" aria-label="查看范围">
+        <button type="button" class="rc-back" aria-label="返回评论弹窗" @click="back"><v-icon aria-hidden="true">mdi-chevron-left</v-icon></button>
+        <button v-for="tab in tabs" :key="tab.scope" type="button" class="rc-tab" :class="{ 'rc-tab--active': page.scope === tab.scope }"
+          :aria-pressed="String(page.scope === tab.scope)" @click="set_page_scope(tab.scope)">{{ tab.label }}</button>
+      </nav>
+      <div class="rc-page-body">
+        <div v-if="page.scope === 'mine' && !user" class="rc-login">
+          <p>登录后查看你的划线和评论</p>
+          <v-btn variant="tonal" @click="$emit('login')">去登录</v-btn>
+        </div>
+        <comment-list v-else ref="pageList" :state="page" :tags="page.scope === 'mine'"
+          :empty="page.scope === 'mine' ? '这里还没有你的记录' : '这里还没有公开评论'" @more="load(page)" @retry="retry(page)" @login="$emit('login')"
+          @open="open_detail" @edit="$emit('edit', $event)" @remove="ask_remove" @vote="vote"></comment-list>
+      </div>
+      <footer class="rc-footer">
+        <v-btn block color="primary" variant="flat" prepend-icon="mdi-plus" @click="write(page)">写评论</v-btn>
+      </footer>
+    </section>
+  </v-dialog>
+
+  <!-- 评论详情页：主评论 + 回复。第一层回复不缩进，第二层及之后统一缩进一级。 -->
+  <v-dialog :model-value="detail_open" class="rc-standalone" fullscreen :scrim="false" transition="slide-x-reverse-transition"
+    aria-label="评论详情" @update:model-value="$event || back()">
+    <section v-if="detail.root" class="rc-page">
+      <nav class="rc-detail-nav">
+        <button type="button" class="rc-back" aria-label="返回评论列表" @click="back"><v-icon aria-hidden="true">mdi-chevron-left</v-icon></button>
+        <strong>评论详情</strong>
+      </nav>
+      <div ref="detailBody" class="rc-page-body rc-detail-body" @scroll.passive="maybe_load_replies">
+        <comment-item :record="detail.root" :tags="root_private" @edit="$emit('edit', $event)" @remove="ask_remove"
+          @vote="vote" @reply="reply_to(null)"></comment-item>
+        <div class="rc-replies-title">{{ detail.root.reply_count || 0 }} 条回复{{ root_private ? ' · 仅你可见' : '' }}</div>
+        <div v-if="replies.error && !replies.items.length" class="rc-replies-state" role="alert">
+          回复暂时没能加载 <button type="button" class="rc-text-button" @click="load_replies(true)">重试</button>
+        </div>
+        <div v-else-if="!replies.items.length && !replies.loading" class="rc-replies-state">还没有回复，来说点什么吧</div>
+        <div v-for="thread in threads" :key="thread.first.id" class="rc-thread">
+          <comment-item :record="thread.first" :readonly="root_private" @edit="edit_reply" @remove="ask_remove" @vote="vote" @reply="reply_to"></comment-item>
+          <div v-if="thread.children.length" class="rc-thread-children">
+            <comment-item v-for="reply in thread.children" :key="reply.id" :record="reply" :readonly="root_private"
+              @edit="edit_reply" @remove="ask_remove" @vote="vote" @reply="reply_to"></comment-item>
+          </div>
+        </div>
+        <div v-if="replies.items.length" class="rc-replies-state" role="status">
+          <template v-if="replies.error">加载失败 <button type="button" class="rc-text-button" @click="load_replies()">重试</button></template>
+          <template v-else-if="replies.loading">正在加载回复…</template>
+          <template v-else-if="!replies.has_more">已显示全部回复</template>
+        </div>
+      </div>
+      <footer v-if="!root_private" class="rc-footer">
+        <form class="rc-reply-box" @submit.prevent="send_reply">
+          <v-textarea ref="replyInput" v-model="detail.draft" class="rc-reply-input" aria-label="回复内容" :placeholder="reply_placeholder"
+            variant="outlined" density="compact" rows="1" max-rows="4" auto-grow hide-details :readonly="detail.sending"></v-textarea>
+          <v-btn v-if="detail.to || detail.edit" variant="text" :disabled="detail.sending" @click="reset_composer">取消</v-btn>
+          <v-btn type="submit" color="primary" variant="flat" :loading="detail.sending">{{ detail.edit ? '保存' : '发送' }}</v-btn>
+        </form>
+      </footer>
+    </section>
+  </v-dialog>
+
+  <v-dialog v-model="removing.open" class="rc-above-standalone" max-width="360" :persistent="removing.busy" aria-labelledby="rc-remove-title">
+    <v-card>
+      <v-card-title id="rc-remove-title" class="text-subtitle-1">删除后无法恢复</v-card-title>
+      <v-card-text>{{ remove_message }}</v-card-text>
+      <v-card-actions>
+        <v-spacer></v-spacer>
+        <v-btn variant="text" :disabled="removing.busy" @click="removing.open = false">取消</v-btn>
+        <v-btn color="error" variant="flat" :loading="removing.busy" @click="confirm_remove">删除</v-btn>
+      </v-card-actions>
+    </v-card>
+  </v-dialog>
+</template>
+
+<script>
+import { createClientId } from '@/annotations'
+import CommentItem from './CommentItem.vue'
+import CommentList from './CommentList.vue'
+
+const PAGE_SIZE = 20
+const list_state = scope => ({ scope, paragraph_cfi: '', paragraph_chapter: '', items: [], cursor: null, has_more: false, loading: false, error: '', need_login: false, request: 0 })
+
+export default {
+  name: 'ReaderComments',
+  components: { CommentItem, CommentList },
+  emits: ['write', 'edit', 'login', 'changed', 'feedback', 'close'],
+  props: {
+    repository: { type: Object, default: null },
+    user: { type: Object, default: null },
+    chapter: { type: String, default: '' },
+    // 抽屉是否展开；收起时不为章节切换发请求。
+    active: { type: Boolean, default: false },
+  },
+  data: () => ({
+    drawer: list_state('chapter'),
+    page: list_state('chapter'),
+    replies: list_state('replies'),
+    detail: { root: null, to: null, edit: null, draft: '', sending: false },
+    // 已进入的独立页面栈（'page' / 'detail'），与浏览器历史一一对应。
+    nav: [],
+    removing: { open: false, busy: false, record: null },
+    voting: new Set(),
+    drag: null,
+    tabs: [
+      { scope: 'chapter', label: '本章评论' },
+      { scope: 'book', label: '全书评论' },
+      { scope: 'mine', label: '我的' },
+    ],
+  }),
+  computed: {
+    page_open: function () { return this.nav.includes('page') },
+    detail_open: function () { return this.nav.includes('detail') && Boolean(this.detail.root) },
+    root_private: function () { return this.detail.root?.is_private !== false },
+    reply_placeholder: function () {
+      if (this.detail.edit) return '修改回复'
+      return `回复 ${(this.detail.to || this.detail.root)?.author_name || '书友'}`
+    },
+    threads: function () {
+      const items = this.replies.items
+      const firsts = items.filter(reply => !reply.thread_id || !items.some(item => item.id === reply.thread_id))
+      return firsts.map(first => ({ first, children: items.filter(reply => reply.thread_id === first.id) }))
+    },
+    remove_message: function () {
+      const record = this.removing.record
+      if (!record) return ''
+      const count = record.root_id ? this.replies.items.filter(reply => reply.thread_id === record.id).length : record.reply_count || 0
+      const target = record.root_id ? '回复' : '评论'
+      return count ? `这条${target}下的 ${count} 条回复也会一并删除。确定删除吗？` : `确定删除这条${target}吗？`
+    },
+  },
+  watch: {
+    chapter: function () {
+      if (this.active && this.drawer.scope === 'chapter') this.load(this.drawer, true)
+    },
+    user: function () {
+      // 登录后重新加载：之前因为需要登录而没有内容的列表，以及「我的」。
+      if (this.drawer.need_login) this.load(this.drawer, true)
+      if (this.page_open && (this.page.scope === 'mine' || this.page.need_login)) this.load(this.page, true)
+    },
+  },
+  mounted: function () {
+    window.addEventListener('popstate', this.on_popstate)
+  },
+  beforeUnmount: function () {
+    window.removeEventListener('popstate', this.on_popstate)
+  },
+  methods: {
+    // ---- 列表 ----
+    show: function (scope, paragraphCfi = '', paragraphChapter = '') {
+      this.drawer.scope = scope
+      this.drawer.paragraph_cfi = paragraphCfi
+      this.drawer.paragraph_chapter = paragraphChapter
+      this.$refs.drawerList?.scroll_to_top()
+      return this.load(this.drawer, true)
+    },
+    reload: function () {
+      this.load(this.drawer, true)
+      if (this.page_open) this.load(this.page, true)
+    },
+    retry: function (state) {
+      return this.load(state, !state.items.length)
+    },
+    load: async function (state, reset = false) {
+      if (!this.repository) return
+      if (reset) {
+        state.request++
+        Object.assign(state, { items: [], cursor: null, has_more: false, error: '', need_login: false })
+      } else if (state.loading || (!state.has_more && !state.error)) return
+      const request = state.request
+      state.loading = true
+      state.error = ''
+      try {
+        const query = state === this.replies
+          ? { root_id: this.detail.root.id, cursor: state.cursor, limit: PAGE_SIZE }
+          : { scope: state.scope, chapter: (state.scope === 'paragraph' && state.paragraph_chapter) || this.chapter, paragraph_cfi: state.paragraph_cfi, cursor: state.cursor, limit: PAGE_SIZE }
+        const result = await (state === this.replies ? this.repository.replies(query) : this.repository.list(query))
+        // 切换范围后迟到的响应不能混入新范围。
+        if (request !== state.request) return
+        const known = new Set(state.items.map(item => item.id))
+        state.items.push(...result.items.filter(item => !known.has(item.id)))
+        state.cursor = result.next_cursor
+        state.has_more = result.has_more
+      } catch (error) {
+        if (request !== state.request) return
+        // 宿主以 code 为 need_login 的错误拒绝时，表示需要登录才能查看，显示登录提示而不是错误。
+        state.need_login = error?.code === 'need_login'
+        state.error = error.message || '请稍后重试'
+      } finally {
+        if (request === state.request) state.loading = false
+      }
+    },
+    set_page_scope: function (scope) {
+      if (this.page.scope === scope) return
+      this.page.scope = scope
+      this.$refs.pageList?.scroll_to_top()
+      if (scope !== 'mine' || this.user) this.load(this.page, true)
+    },
+    write: function (state) {
+      if (!this.user) return this.$emit('login')
+      this.$emit('write', { scope: state.scope, paragraph_cfi: state.paragraph_cfi })
+    },
+    copies: function (id) {
+      const all = [...this.drawer.items, ...this.page.items, ...this.replies.items]
+      if (this.detail.root) all.push(this.detail.root)
+      return all.filter(item => item.id === id)
+    },
+    patch: function (id, fields) {
+      this.copies(id).forEach(item => Object.assign(item, fields))
+    },
+    // 编辑框保存成功后由阅读器调用：就地更新已有记录，新记录则刷新列表。
+    apply_saved: function (record) {
+      if (this.copies(record.id).length) this.patch(record.id, record)
+      this.reload()
+    },
+
+    // ---- 独立页面与浏览器返回 ----
+    push: function (name) {
+      this.nav.push(name)
+      history.pushState({ ...history.state, candle_comments: this.nav.length }, '')
+    },
+    back: function () {
+      if (this.nav.length) history.back()
+    },
+    on_popstate: function (event) {
+      const depth = event.state?.candle_comments || 0
+      while (this.nav.length > depth) this.leave(this.nav.pop())
+    },
+    leave: function (name) {
+      if (name === 'detail') {
+        this.replies.request++
+        this.reset_composer()
+        const id = this.detail.root?.id
+        this.detail.root = null
+        // 抽屉和完整评论页可能同时列着这条评论，焦点回到最上层那一个。
+        this.$nextTick(() => Array.from(document.querySelectorAll(`.v-overlay--active [data-comment="${CSS.escape(String(id))}"] .comment-reply`)).pop()?.focus())
+      } else {
+        this.$nextTick(() => this.$refs.moreEntry?.focus())
+      }
+    },
+    // 抽屉被收起时一并退出独立页面，历史记录同步回退。
+    close_pages: function () {
+      if (this.nav.length) history.go(-this.nav.length)
+    },
+    open_page: function () {
+      this.page.scope = 'chapter'
+      this.push('page')
+      this.load(this.page, true)
+    },
+    open_detail: function (record) {
+      this.detail.root = record
+      this.reset_composer()
+      this.push('detail')
+      this.load_replies(true)
+    },
+    load_replies: function (reset = false) {
+      return this.load(this.replies, reset)
+    },
+    maybe_load_replies: function () {
+      const el = this.$refs.detailBody
+      if (el && el.scrollHeight - el.scrollTop - el.clientHeight <= 48) this.load_replies()
+    },
+
+    // ---- 回复 ----
+    reset_composer: function () {
+      Object.assign(this.detail, { to: null, edit: null, draft: '' })
+    },
+    focus_composer: function () {
+      this.$nextTick(() => this.$refs.replyInput?.focus())
+    },
+    reply_to: function (reply) {
+      if (!this.user) return this.$emit('login')
+      Object.assign(this.detail, { to: reply, edit: null, draft: this.detail.edit ? '' : this.detail.draft })
+      this.focus_composer()
+    },
+    edit_reply: function (reply) {
+      Object.assign(this.detail, { to: null, edit: reply, draft: reply.content })
+      this.focus_composer()
+    },
+    send_reply: async function () {
+      if (!this.user) return this.$emit('login')
+      const content = this.detail.draft.trim()
+      const root = this.detail.root
+      if (!content || this.detail.sending) return this.focus_composer()
+      const editing = this.detail.edit
+      this.detail.sending = true
+      try {
+        const saved = await this.repository.save(editing
+          ? { id: editing.id, client_id: editing.client_id, root_id: root.id, content }
+          : { client_id: createClientId(), root_id: root.id, reply_to_id: this.detail.to?.id || null, content })
+        if (this.detail.root !== root) return
+        if (editing) Object.assign(editing, saved)
+        else {
+          this.replies.items.push(saved)
+          this.patch(root.id, { reply_count: (root.reply_count || 0) + 1 })
+        }
+        this.reset_composer()
+      } catch (error) {
+        this.$emit('feedback', `回复失败：${error.message || '请稍后重试'}`, true)
+      } finally {
+        this.detail.sending = false
+      }
+    },
+
+    // ---- 赞踩：互斥，再点一次取消；失败恢复到操作前 ----
+    vote: async function (record, value) {
+      if (!this.user) return this.$emit('login')
+      if (this.voting.has(record.id)) return
+      const before = { like_count: record.like_count || 0, dislike_count: record.dislike_count || 0, user_vote: record.user_vote || 0 }
+      const next = before.user_vote === value ? 0 : value
+      this.voting.add(record.id)
+      this.patch(record.id, {
+        user_vote: next,
+        like_count: before.like_count - (before.user_vote === 1) + (next === 1),
+        dislike_count: before.dislike_count - (before.user_vote === -1) + (next === -1),
+      })
+      try {
+        const result = await this.repository.vote({ id: record.id, value: next })
+        this.patch(record.id, { like_count: result.like_count, dislike_count: result.dislike_count, user_vote: result.user_vote })
+      } catch (error) {
+        this.patch(record.id, before)
+        this.$emit('feedback', `操作失败：${error.message || '请稍后重试'}`, true)
+      } finally {
+        this.voting.delete(record.id)
+      }
+    },
+
+    // ---- 删除：真删除，主评论连同全部回复，第一层回复连同其下回复 ----
+    ask_remove: function (record) {
+      Object.assign(this.removing, { open: true, busy: false, record })
+    },
+    confirm_remove: async function () {
+      const record = this.removing.record
+      this.removing.busy = true
+      try {
+        await this.repository.remove({ id: record.id })
+        if (record.root_id) {
+          const before = this.replies.items.length
+          this.replies.items = this.replies.items.filter(reply => reply.id !== record.id && reply.thread_id !== record.id)
+          const root = this.detail.root
+          if (root) this.patch(root.id, { reply_count: Math.max(0, (root.reply_count || 0) - (before - this.replies.items.length)) })
+          if (this.detail.to?.id === record.id || this.detail.edit?.id === record.id) this.reset_composer()
+        } else {
+          for (const state of [this.drawer, this.page]) state.items = state.items.filter(item => item.id !== record.id)
+          if (this.detail.root?.id === record.id) this.back()
+          this.$emit('changed', record)
+        }
+        this.removing.open = false
+        this.$emit('feedback', '已删除')
+      } catch (error) {
+        this.$emit('feedback', `删除失败：${error.message || '请稍后重试'}`, true)
+      } finally {
+        this.removing.busy = false
+      }
+    },
+
+    // ---- 移动端向下拖拽收起抽屉 ----
+    sheet: function () { return this.$refs.drawer?.closest('.v-overlay__content') },
+    on_drag_start: function (event) {
+      if (event.button !== 0 || event.target.closest('button') || window.innerWidth >= 850) return
+      this.drag = { y: event.clientY, id: event.pointerId }
+      event.currentTarget.setPointerCapture(event.pointerId)
+      this.sheet().style.transition = 'none'
+    },
+    on_drag_move: function (event) {
+      if (!this.drag || event.pointerId !== this.drag.id) return
+      this.sheet().style.transform = `translateY(${Math.max(0, event.clientY - this.drag.y)}px)`
+    },
+    on_drag_end: function (event) {
+      if (!this.drag || event.pointerId !== this.drag.id) return
+      const distance = event.clientY - this.drag.y
+      this.on_drag_cancel()
+      if (distance >= 72) this.$emit('close')
+    },
+    on_drag_cancel: function () {
+      this.drag = null
+      const sheet = this.sheet()
+      if (sheet) { sheet.style.transition = ''; sheet.style.transform = '' }
+    },
+  },
+}
+</script>
+
+<style scoped>
+.reader-comments-drawer { display: flex; flex-direction: column; height: 100%; min-height: 0; background: rgb(var(--v-theme-surface)); color: rgb(var(--v-theme-on-surface)); border-radius: 22px 22px 0 0; overflow: hidden; }
+.rc-grip { flex: 0 0 auto; touch-action: none; user-select: none; }
+.rc-handle { width: 36px; height: 4px; margin: 10px auto 0; border-radius: 4px; background: rgba(var(--v-theme-on-surface), 0.24); }
+.rc-head { display: flex; align-items: center; justify-content: space-between; margin: 4px 20px 0; padding: 8px 0; border-bottom: 1px solid rgba(var(--v-border-color), var(--v-border-opacity)); font-size: 14px; }
+.rc-head strong { font-weight: 500; }
+.rc-more { display: inline-flex; align-items: center; min-height: 36px; padding-left: 8px; border-radius: 6px; font-size: 13px; color: rgb(var(--v-theme-on-surface)); color: color-mix(in srgb, rgb(var(--v-theme-primary)) 60%, rgb(var(--v-theme-on-surface))); }
+.rc-footer { flex: 0 0 auto; padding: 12px 20px; padding-bottom: max(12px, env(safe-area-inset-bottom)); border-top: 1px solid rgba(var(--v-border-color), var(--v-border-opacity)); background: rgb(var(--v-theme-surface)); }
+.rc-page { display: flex; flex-direction: column; height: 100%; background: rgb(var(--v-theme-surface)); color: rgb(var(--v-theme-on-surface)); padding-top: env(safe-area-inset-top); }
+.rc-tabs, .rc-detail-nav { flex: 0 0 auto; display: flex; align-items: center; gap: 8px; padding: 0 12px; border-bottom: 1px solid rgba(var(--v-border-color), var(--v-border-opacity)); }
+.rc-detail-nav { min-height: 48px; font-size: 15px; }
+.rc-back { flex: 0 0 40px; display: grid; place-items: center; width: 40px; height: 44px; border-radius: 8px; }
+.rc-tab { flex: 1 1 0; min-height: 48px; border-bottom: 2px solid transparent; font-size: 14px; white-space: nowrap; color: rgba(var(--v-theme-on-surface), 0.7); }
+.rc-tab--active { color: rgb(var(--v-theme-on-surface)); color: color-mix(in srgb, rgb(var(--v-theme-primary)) 60%, rgb(var(--v-theme-on-surface))); border-color: rgb(var(--v-theme-primary)); font-weight: 600; }
+.rc-page-body { flex: 1 1 auto; min-height: 0; display: flex; flex-direction: column; width: 100%; max-width: 820px; margin: 0 auto; }
+.rc-detail-body { display: block; overflow-y: auto; overscroll-behavior: contain; padding: 0 20px; }
+.rc-login { padding: 48px 20px; text-align: center; font-size: 14px; color: rgba(var(--v-theme-on-surface), 0.7); }
+.rc-login p { margin-bottom: 16px; }
+.rc-replies-title { padding: 12px 0 0; border-top: 1px solid rgba(var(--v-border-color), var(--v-border-opacity)); font-size: 12px; color: rgba(var(--v-theme-on-surface), 0.7); }
+.rc-replies-state { padding: 18px 0; text-align: center; font-size: 12px; color: rgba(var(--v-theme-on-surface), 0.7); }
+.rc-thread + .rc-thread { border-top: 1px solid rgba(var(--v-border-color), var(--v-border-opacity)); }
+.rc-thread-children { margin: 0 0 8px 20px; padding-left: 12px; border-left: 2px solid rgba(var(--v-border-color), var(--v-border-opacity)); }
+.rc-thread-children .comment-item { padding: 10px 0; }
+.rc-thread-children .comment-item + .comment-item { border-top: 1px solid rgba(var(--v-border-color), var(--v-border-opacity)); }
+.rc-text-button { padding: 4px 8px; color: rgb(var(--v-theme-on-surface)); color: color-mix(in srgb, rgb(var(--v-theme-primary)) 60%, rgb(var(--v-theme-on-surface))); }
+.rc-reply-box { display: flex; align-items: flex-end; gap: 8px; width: 100%; max-width: 780px; margin: 0 auto; }
+.rc-reply-input { flex: 1 1 auto; min-width: 0; }
+.rc-more:focus-visible, .rc-back:focus-visible, .rc-tab:focus-visible, .rc-text-button:focus-visible { outline: 2px solid rgb(var(--v-theme-primary)); outline-offset: -2px; }
+@media (min-width: 850px) {
+  .reader-comments-drawer { border-radius: 0; }
+  .rc-handle { display: none; }
+  .rc-grip { touch-action: auto; }
+  .rc-head { margin-top: 10px; }
+}
+</style>
+
+<style>
+/* 独立页面要盖住顶部栏与底部菜单（Vuetify 给嵌套浮层的层级只比抽屉高一档，这里显式抬高）。 */
+.v-overlay.rc-standalone { z-index: 2600 !important; }
+.v-overlay.rc-above-standalone { z-index: 2700 !important; }
+</style>
diff --git a/src/main.js b/src/main.js
index e9b2ce3..394333e 100644
--- a/src/main.js
+++ b/src/main.js
@@ -10,11 +10,9 @@ import CandleReader from '@/CandleReader.vue'
 
 export class Reader {
     constructor(elem, args) {
-        var default_server = 'https://api.talebook.org';
+        // 阅读器不直接请求任何评论或账号服务；划线、评论与登录态都经由 annotation_callbacks 交给宿主。
         const app = createApp(CandleReader, args)
-        registerPlugins(app, {
-            server: args.server || default_server,
-        })
+        registerPlugins(app)
         app.mount(elem)
     }
 }
diff --git a/src/note-settings.js b/src/note-settings.js
new file mode 100644
index 0000000..deac09a
--- /dev/null
+++ b/src/note-settings.js
@@ -0,0 +1,12 @@
+// 迁移旧的划线/评论开关。早期版本有一个总开关 notes_enabled，现已去掉：
+// 曾经关闭总开关的读者，迁移后两个具体开关都按关闭处理，保持原来「什么都不显示」的效果。
+export function normalizeNoteSettings(saved = {}) {
+  const legacyComments = saved.show_comments ?? true
+  const legacyAnnotations = saved.show_annotations ?? true
+  const enabled = saved.notes_enabled ?? true
+  return {
+    notes_settings_version: 3,
+    show_comments: enabled && legacyComments,
+    show_selection_toolbar: enabled && (saved.show_selection_toolbar ?? legacyAnnotations),
+  }
+}
diff --git a/src/plugins/index.js b/src/plugins/index.js
index 317ab02..3a563e4 100644
--- a/src/plugins/index.js
+++ b/src/plugins/index.js
@@ -6,10 +6,8 @@
 
 // Plugins
 import vuetify from './vuetify'
-import serverPlugin from './server'
 
-export function registerPlugins (app, options) {
+export function registerPlugins (app) {
   app
   .use(vuetify)
-  .use(serverPlugin, options)
 }
diff --git a/src/plugins/server.js b/src/plugins/server.js
deleted file mode 100644
index c361027..0000000
--- a/src/plugins/server.js
+++ /dev/null
@@ -1,107 +0,0 @@
-const serverPlugin = {
-    install: (app, options) => {
-
-        const server = options.server;
-
-        app.config.globalProperties.$alert = function (alert_type, alert_msg, alert_to) {
-            app.$store.commit("alert", { type: alert_type, msg: alert_msg, to: alert_to });
-            if (alert_type === 'success') {
-                setTimeout(() => {
-                    app.$store.commit('close_alert')
-                }, 1300)
-            }
-        };
-
-        // 注入 backend 方法
-        app.config.globalProperties.$backend = async function (url, options) {
-            if (url === undefined) {
-                throw "url is undefined "
-            }
-            var args = {
-                mode: "cors", redirect: "follow", credentials: 'include',
-                timeout: 10000, // 添加超时设置
-            }
-
-            var full_url = server + url;
-
-            if (options !== undefined) {
-                Object.assign(args, options);
-            }
-            
-            // 添加请求超时处理
-            const controller = new AbortController();
-            const timeoutId = setTimeout(() => controller.abort(), args.timeout || 10000);
-            
-            return fetch(full_url, {
-                ...args,
-                signal: controller.signal
-            })
-                .then(rsp => {
-                    clearTimeout(timeoutId);
-                    var msg = "";
-                    if (rsp.status === 413) {
-                        msg = "服务器响应了413异常状态码。<br/>可能是上传的文件过大，超过了服务器设置的上传大小。";
-                        app.$alert("error", msg);
-                        throw msg;
-                    }
-
-                    else if (rsp.status === 502) {
-                        msg = "服务器正在启动中...";
-                        app.$alert("info", msg);
-                        throw msg;
-                    }
-
-                    // 尝试解析所有状态码的响应体，包括400
-                    try {
-                        return rsp.json().then(data => {
-                            // 如果状态码不是200，但响应体包含err和msg字段，则返回响应体
-                            if (rsp.status !== 200) {
-                                return data;
-                            }
-                            return data;
-                        });
-                    } catch (err) {
-                        // 如果解析失败，再处理状态码
-                        if (rsp.status !== 200) {
-                            msg = "服务器异常，状态码: " + rsp.status + "<br/>请查阅服务器日志:<br/>talebook.log";
-                            app.$alert("error", msg);
-                            throw msg;
-                        }
-                        msg = "服务器异常，响应非JSON<br/>请查阅服务器日志:<br/>talebook.log";
-                        app.$alert("error", msg);
-                        throw msg;
-                    }
-                })
-                .then(rsp => {
-                    if (rsp.err === 'exception') {
-                        // 检查 app.$store 是否存在，避免调用不存在的方法
-                        if (app.$store) {
-                            app.$store.commit("alert", { type: "error", msg: rsp.msg, to: null });
-                        } else {
-                            // 如果 store 不存在，使用 console.error 输出错误
-                            console.error('API 异常:', rsp.msg);
-                        }
-                    }
-                    return rsp;
-                })
-                .catch(err => {
-                    clearTimeout(timeoutId);
-                    var msg = "";
-                    if (err.name === 'AbortError') {
-                        msg = "请求超时，请检查网络连接或服务器状态";
-                    } else if (!navigator.onLine) {
-                        msg = "网络连接已断开，请检查网络设置";
-                    } else {
-                        msg = "请求失败: " + (err.message || "未知错误");
-                    }
-                    console.error('API请求失败:', err);
-                    // 不显示错误提示，避免影响用户体验
-                    // app.$alert("error", msg);
-                    // 返回默认值，让应用能够继续运行
-                    return { err: "network_error", msg: msg, data: {} };
-                })
-        };
-    },
-};
-
-export default serverPlugin;
diff --git a/src/themes.js b/src/themes.js
index dd647f4..c91ea4c 100644
--- a/src/themes.js
+++ b/src/themes.js
@@ -18,6 +18,11 @@
 //   mask    阅读时盖在大图上的半透明蒙版色，柔化背景、提升正文可读性（type=image）
 //   sample  卡片预览里的示例文字
 
+// 皮肤图片随打包产物放在 themes/skins/ 下。阅读器常部署在子路径（talebook 的 /static/candle-reader/、
+// GitHub Pages 的 /candle-reader/），所以按打包脚本自己的地址解析，不写死站点根目录；开发时由 vite 从 public/ 根目录提供。
+const SKIN_BASE = import.meta.env.DEV ? '/themes/skins/' : import.meta.url.slice(0, import.meta.url.lastIndexOf('/') + 1) + 'themes/skins/'
+const skin = file => SKIN_BASE + file
+
 export const THEMES = [
   // —— 纯色主题（沿用既有配色，作为设置面板的 4 个快捷图标）——
   { id: 'white',   name: '白色',   type: 'solid', mode: 'day',
@@ -33,30 +38,30 @@ export const THEMES = [
   { id: 'zhulin',    name: '竹林清风', type: 'image', mode: 'day',
     bg: '#eef5e4', surface: '#dbe9c6', text: '#33472f', mask: 'rgba(255,255,255,0.20)',
     bgTop: '#e9f2db', bgBottom: '#d9e8c3',
-    thumb: '/themes/skins/zhulin-thumb.svg',
-    portrait: '/themes/skins/zhulin-portrait.svg',
-    landscape: '/themes/skins/zhulin-landscape.svg',
+    thumb: skin('zhulin-thumb.svg'),
+    portrait: skin('zhulin-portrait.svg'),
+    landscape: skin('zhulin-landscape.svg'),
     sample: '看花饮美酒，听鸟临晴山' },
   { id: 'parchment', name: '故纸堆',   type: 'image', mode: 'day',
     bg: '#f7efd9', surface: '#ebdcb4', text: '#5a3b1a', mask: 'rgba(252,246,232,0.20)',
     bgTop: '#f8f0dc', bgBottom: '#edddb7',
-    thumb: '/themes/skins/parchment-thumb.svg',
-    portrait: '/themes/skins/parchment-portrait.svg',
-    landscape: '/themes/skins/parchment-landscape.svg',
+    thumb: skin('parchment-thumb.svg'),
+    portrait: skin('parchment-portrait.svg'),
+    landscape: skin('parchment-landscape.svg'),
     sample: '旧纸新墨，字里春秋' },
   { id: 'huitu',     name: '灰土',     type: 'image', mode: 'night',
     bg: '#211e1a', surface: '#36302a', text: '#cfcabf', mask: 'rgba(20,18,15,0.30)',
     bgTop: '#2e2922', bgBottom: '#13100c',
-    thumb: '/themes/skins/huitu-thumb.svg',
-    portrait: '/themes/skins/huitu-portrait.svg',
-    landscape: '/themes/skins/huitu-landscape.svg',
+    thumb: skin('huitu-thumb.svg'),
+    portrait: skin('huitu-portrait.svg'),
+    landscape: skin('huitu-landscape.svg'),
     sample: '荒土残阳，独行天地间' },
   { id: 'xingye',    name: '星夜',     type: 'image', mode: 'night',
     bg: '#101730', surface: '#1d2a52', text: '#cdd6e6', mask: 'rgba(12,16,32,0.28)',
     bgTop: '#161e37', bgBottom: '#080c1c',
-    thumb: '/themes/skins/xingye-thumb.svg',
-    portrait: '/themes/skins/xingye-portrait.svg',
-    landscape: '/themes/skins/xingye-landscape.svg',
+    thumb: skin('xingye-thumb.svg'),
+    portrait: skin('xingye-portrait.svg'),
+    landscape: skin('xingye-landscape.svg'),
     sample: '万族之上，星河为劫' },
 ]
 
diff --git a/tests/e2e/annotations.spec.js b/tests/e2e/annotations.spec.js
new file mode 100644
index 0000000..a2e50e1
--- /dev/null
+++ b/tests/e2e/annotations.spec.js
@@ -0,0 +1,682 @@
+const { test, expect } = require('@playwright/test')
+const fs = require('node:fs')
+const path = require('node:path')
+const { setupApiMock } = require('./helpers/mock-api')
+const { HARNESS_URL, HOST_URL, gotoReader, openPanel, readState, readerProxy, waitForReaderRendered } = require('./helpers/reader')
+test.use({ viewport: { width: 402, height: 874 }, deviceScaleFactor: 3 })
+
+async function captureEvidence(page, name) {
+  if (!process.env.TB199_EVIDENCE_DIR) return
+  const directory = path.resolve(process.env.TB199_EVIDENCE_DIR)
+  fs.mkdirSync(directory, { recursive: true })
+  await page.screenshot({ path: path.join(directory, name) })
+}
+
+function notesButton(page) {
+  return page.locator('.v-bottom-navigation').getByRole('button', { name: '评论' })
+}
+
+test.beforeEach(async ({ page }) => {
+  await setupApiMock(page)
+})
+
+test('选区工具栏优先放在上方，空间不足时放在下方并保持在屏幕内', async ({ page }) => {
+  await gotoReader(page)
+  const toolbar = page.locator('#comments-toolbar')
+  const proxy = await readerProxy(page)
+  for (const selection of [
+    { left: 340, top: 70, bottom: 94, placement: 'above' },
+    { left: 340, top: 20, bottom: 44, placement: 'below' },
+  ]) {
+    await proxy.evaluate((reader, rect) => {
+      reader.show_toolbar(rect, { x: 0, y: 0 })
+    }, selection)
+    await expect(toolbar).toBeVisible()
+    await expect(toolbar.getByRole('button', { name: '复制' })).not.toBeFocused()
+    const box = await toolbar.boundingBox()
+    if (selection.placement === 'above') {
+      expect(box.y + box.height).toBeLessThanOrEqual(selection.top)
+      expect(selection.top - box.y - box.height).toBeLessThanOrEqual(16)
+    } else {
+      expect(box.y).toBeGreaterThanOrEqual(selection.bottom)
+      expect(box.y - selection.bottom).toBeLessThanOrEqual(16)
+    }
+    expect(box.x).toBeGreaterThanOrEqual(8)
+    expect(box.x + box.width).toBeLessThanOrEqual(394)
+    expect(box.y).toBeGreaterThanOrEqual(8)
+    await proxy.evaluate(reader => reader.hide_toolbar())
+    await expect(toolbar).toBeHidden()
+  }
+})
+
+test.describe('触屏设备', () => {
+  test.use({ isMobile: true, hasTouch: true })
+  test('工具栏优先放在选区下方，避开系统文字菜单；下方放不下时放上方', async ({ page }) => {
+    await gotoReader(page)
+    const toolbar = page.locator('#comments-toolbar')
+    const proxy = await readerProxy(page)
+    for (const selection of [
+      { left: 40, top: 300, bottom: 324, placement: 'below' },
+      // 底部菜单上方只剩不到一个工具栏的高度。
+      { left: 40, top: 780, bottom: 804, placement: 'above' },
+    ]) {
+      await proxy.evaluate((reader, rect) => reader.show_toolbar(rect, { x: 0, y: 0 }), selection)
+      await expect(toolbar).toBeVisible()
+      const box = await toolbar.boundingBox()
+      if (selection.placement === 'below') expect(box.y).toBeGreaterThanOrEqual(selection.bottom)
+      else expect(box.y + box.height).toBeLessThanOrEqual(selection.top)
+      await proxy.evaluate(reader => reader.hide_toolbar())
+    }
+  })
+})
+
+test('工具栏跟随段落中的实际选区位置', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  const selectionTop = await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const paragraph = contents.document.getElementById('passage')
+    paragraph.style.width = '160px'
+    paragraph.style.marginTop = '160px'
+    const text = paragraph.firstChild
+    const range = contents.document.createRange()
+    range.setStart(text, text.length - 8)
+    range.setEnd(text, text.length)
+    const view = reader.rendition.views()._views.find(item => item.index === contents.sectionIndex)
+    const top = range.getBoundingClientRect().top + view.iframe.getBoundingClientRect().top
+    reader.on_select_content(contents.cfiFromRange(range), contents)
+    return top
+  })
+  const toolbar = page.locator('#comments-toolbar')
+  await expect(toolbar).toBeVisible()
+  await expect(toolbar.getByRole('button', { name: '复制' })).not.toBeFocused()
+  const box = await toolbar.boundingBox()
+  expect(box.y + box.height).toBeLessThanOrEqual(selectionTop)
+  expect(selectionTop - box.y - box.height).toBeLessThanOrEqual(16)
+})
+
+test('未注入回调时按书保存到 localStorage，并出现在「我的」', async ({ page }) => {
+  await gotoReader(page)
+  await expect(page.locator('#comments-toolbar')).toBeHidden()
+  await waitForReaderRendered(page)
+  const proxy = await readerProxy(page)
+  await proxy.evaluate(async (reader) => {
+    reader.selected_location = {
+      client_id: 'local-highlight-1',
+      toc: { label: '第一章' },
+      cfi: reader.rendition.currentLocation().start.cfi,
+      quote_text: '本地划线原文',
+      contents: null,
+      segment_id: 0,
+    }
+    await reader.save_highlight()
+  })
+
+  const saved = await page.evaluate(() => {
+    const key = Object.keys(localStorage).find(item => item.startsWith('candle-reader:annotations:v1:'))
+    return key ? JSON.parse(localStorage.getItem(key)) : []
+  })
+  expect(saved).toHaveLength(1)
+  expect(saved[0]).toMatchObject({ client_id: 'local-highlight-1', quote_text: '本地划线原文' })
+
+  await notesButton(page).click()
+  // 划线固定私密：不进入本章评论，只在「我的」里出现。
+  await expect(page.locator('.reader-comments-drawer').getByText('这里还没有公开评论')).toBeVisible()
+  await page.getByRole('button', { name: /查看更多评论/ }).click()
+  const fullPage = page.getByRole('dialog', { name: '完整评论页' })
+  await fullPage.getByRole('button', { name: '我的' }).click()
+  await expect(fullPage.getByText('本地划线原文')).toBeVisible()
+  await expect(fullPage.locator('.comment-tag')).toHaveText(['划线'])
+  await expect(fullPage.locator('.comment-private')).toHaveText('私密')
+})
+
+test('宿主回调负责读取和写入，且收到书籍上下文', async ({ page }) => {
+  await page.goto(HOST_URL)
+  await waitForReaderRendered(page)
+  const proxy = await readerProxy(page)
+  await proxy.evaluate((reader) => {
+    reader.selected_location = {
+      client_id: 'callback-note-1',
+      toc: { label: '第一章' },
+      cfi: reader.rendition.currentLocation().start.cfi,
+      quote_text: '回调写入原文',
+      paragraph_cfi: reader.rendition.currentLocation().start.cfi,
+      paragraph_quote_text: '回调写入整段原文',
+      contents: null,
+      segment_id: 0,
+    }
+    reader.show_toolbar({ left: 16, top: 96, bottom: 120 }, { x: 0, y: 0 })
+  })
+  await expect(page.locator('#comments-toolbar')).toBeVisible()
+  await expect(page.locator('#comments-toolbar').getByRole('button', { name: '复制' })).not.toBeFocused()
+  await page.locator('#comments-toolbar').getByRole('button', { name: '写评论' }).click()
+  await expect(page.getByRole('dialog', { name: '写评论' })).toBeVisible()
+  const publicSwitch = page.getByRole('switch', { name: '公开这条评论' })
+  await expect(publicSwitch).toBeChecked()
+  await expect(page.getByText('评论关联整个段落。')).toBeVisible()
+  await expect(page.getByText('其他读者可以在对应评论范围看到这条评论。')).toBeVisible()
+  await publicSwitch.uncheck()
+  await expect(page.getByText('只有你能看到这条评论。')).toBeVisible()
+  await publicSwitch.focus()
+  await page.keyboard.press('Space')
+  await expect(publicSwitch).toBeChecked()
+  await page.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(page.getByText('请填写评论内容')).toBeVisible()
+  await expect(page.getByLabel('评论内容')).toBeFocused()
+  await page.getByLabel('评论内容').fill('回调写入内容')
+  await page.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(page.getByText('评论已保存')).toBeVisible()
+
+  const calls = await page.evaluate(() => window.__host.calls)
+  expect(calls.some(call => call.operation === 'load' && call.query.book_id === 101 && call.query.book_url === '/demo/book1.epub')).toBe(true)
+  const save = calls.find(call => call.operation === 'save')
+  expect(save.query).toMatchObject({ client_id: 'callback-note-1', annotation_type: 'note', content: '回调写入内容', is_private: false, quote_text: '回调写入整段原文' })
+  expect(await page.evaluate(() => Object.keys(localStorage).some(key => key.startsWith('candle-reader:annotations:v1:')))).toBe(false)
+})
+
+test('真实选区在工具栏和编辑弹窗中可见，写入失败不产生永久标记', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+  })
+  const selectionInfo = await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const text = contents.document.getElementById('passage').firstChild
+    const range = contents.document.createRange()
+    range.setStart(text, 1)
+    range.setEnd(text, Math.min(14, text.textContent.length))
+    const selection = contents.document.getSelection()
+    selection.removeAllRanges()
+    selection.addRange(range)
+    return { cfi: contents.cfiFromRange(range), ...reader.paragraph_for_range(range, contents) }
+  })
+  const toolbar = page.locator('#comments-toolbar')
+  await expect(toolbar).toBeVisible()
+  await expect(page.locator('.selection-preview').first()).toBeVisible()
+  expect(await toolbar.getByRole('button').allTextContents()).toEqual(expect.arrayContaining(['复制', '划线', '写评论', '看本段评论']))
+  await captureEvidence(page, 'tb199-toolbar-402x874.png')
+  await toolbar.getByRole('button', { name: '写评论' }).click()
+  await expect(page.locator('.selection-preview').first()).toBeVisible()
+  await captureEvidence(page, 'tb199-editor-402x874.png')
+  expect(await page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.selected_location.cfi)).toBe(selectionInfo.cfi)
+  await expect(page.locator('.annotation-editor-quote')).toHaveText(selectionInfo.paragraph_quote_text)
+  await expect(page.getByText('仅保存在当前浏览器，公开范围暂不生效。')).toBeVisible()
+  await expect(page.getByText('其他读者可以在对应评论范围看到这条评论。')).toBeHidden()
+  await page.getByLabel('评论内容').fill('保存失败时保持选区')
+  await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    window.__originalAnnotationSave = reader.annotation_repository.save
+    reader.annotation_repository.save = async () => { throw new Error('模拟写入失败') }
+  })
+  await page.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(page.getByText('保存失败：模拟写入失败')).toBeVisible()
+  await expect(page.locator('.candle-reader-annotation')).toHaveCount(0)
+  await expect(page.locator('.selection-preview').first()).toBeVisible()
+  await captureEvidence(page, 'tb199-save-failed-402x874.png')
+  await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    reader.annotation_repository.save = window.__originalAnnotationSave
+  })
+  await page.getByRole('button', { name: '保存', exact: true }).click()
+  // 文字评论不在正文铺底色，由段尾气泡表示。
+  await expect.poll(() => page.evaluate(() => Array.from(document.querySelectorAll('#reader iframe')).filter(f => f.contentDocument.querySelector('#passage .comment-icon')).length)).toBe(1)
+  await expect(page.locator('.candle-reader-annotation')).toHaveCount(0)
+  await expect(page.locator('.selection-preview')).toHaveCount(0)
+  await expect.poll(() => readState(page, 'annotation_editor_location')).toBe(null)
+  await captureEvidence(page, 'tb199-saved-402x874.png')
+  const saved = await page.evaluate(() => JSON.parse(localStorage['candle-reader:annotations:v1:101']))
+  expect(saved[0]).toMatchObject({ cfi: selectionInfo.paragraph_cfi, quote_text: selectionInfo.paragraph_quote_text, annotation_type: 'note', is_private: false, range_cfi: selectionInfo.cfi, content: '保存失败时保持选区' })
+  await page.evaluate(savedCfi => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    reader.selected_location = { cfi: savedCfi, paragraph_cfi: savedCfi, quote_text: '再次查看同一段落' }
+    reader.show_toolbar({ left: 16, top: 100, bottom: 120 }, { x: 0, y: 0 })
+  }, selectionInfo.paragraph_cfi)
+  await toolbar.getByRole('button', { name: '看本段评论' }).click()
+  const drawer = page.locator('.reader-comments-drawer')
+  await expect(drawer.getByText('本段评论', { exact: true })).toBeVisible()
+  await expect(drawer.getByText('保存失败时保持选区')).toBeVisible()
+  // 段尾气泡显示本段公开评论数量，底部「评论」入口回到本章评论。
+  expect(await page.evaluate(() => Array.from(document.querySelectorAll('#reader iframe')).map(f => f.contentDocument.querySelector('#passage .comment-count')?.textContent).filter(Boolean))).toEqual(['1'])
+  await notesButton(page).click()
+  await notesButton(page).click()
+  await expect(drawer.getByText('本章评论', { exact: true })).toBeVisible()
+})
+
+test('划线等待写入成功才显示标记，成功后不弹保存提示', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const text = contents.document.getElementById('passage').firstChild
+    const range = contents.document.createRange()
+    range.setStart(text, 1)
+    range.setEnd(text, 12)
+    const selection = contents.document.getSelection()
+    selection.removeAllRanges()
+    selection.addRange(range)
+    const originalSave = reader.annotation_repository.save
+    reader.annotation_repository.save = annotation => new Promise(resolve => {
+      window.__finishHighlightSave = () => originalSave(annotation).then(resolve)
+    })
+  })
+  await page.locator('#comments-toolbar').getByRole('button', { name: '划线' }).click()
+  await expect(page.locator('.selection-preview').first()).toBeVisible()
+  await expect(page.locator('.candle-reader-annotation')).toHaveCount(0)
+  await page.evaluate(() => window.__finishHighlightSave())
+  await expect(page.locator('.candle-reader-annotation')).toHaveCount(1)
+  await expect(page.locator('.selection-preview')).toHaveCount(0)
+  await expect(page.getByText('划线已保存')).toHaveCount(0)
+
+  // 点划线打开的是划线所在段落的评论，不是整章评论。
+  const box = await page.locator('.candle-reader-annotation rect').first().boundingBox()
+  await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2)
+  const drawer = page.locator('.reader-comments-drawer')
+  await expect(drawer.getByText('本段评论', { exact: true })).toBeVisible()
+  const expected = await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => item.document.getElementById('passage'))
+    return reader.paragraph_location(contents.document.getElementById('passage'), contents).paragraph_cfi
+  })
+  await expect.poll(() => readState(page, 'comment_paragraph').then(paragraph => paragraph?.paragraph_cfi)).toBe(expected)
+})
+
+test('关闭「显示全部划线和评论」不影响评论入口', async ({ page }) => {
+  await gotoReader(page)
+  await openPanel(page, 'settings')
+  await expect(page.locator('[data-setting=notes_enabled]')).toHaveCount(0)
+  const row = page.locator('[data-setting=show_comments]')
+  await row.getByRole('switch').uncheck()
+  await expect.poll(() => readState(page, 'settings').then(settings => settings.show_comments)).toBe(false)
+  await notesButton(page).click()
+  await expect(page.locator('.reader-comments-drawer')).toBeVisible()
+  await openPanel(page, 'settings')
+  await row.getByRole('switch').check()
+  await expect.poll(() => readState(page, 'settings').then(settings => settings.show_comments)).toBe(true)
+})
+
+// 回归：气泡曾以 inline-block 跟在段尾，末行放不下时会折到新行、把后文往下推；
+// 划线标记按绘制时的文字位置画，切换开关后标记先画、气泡后到，标记就留在了原处。
+test('段尾气泡不参与正文排版，切换「显示全部划线和评论」后划线标记仍盖在原文上', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+  })
+  // 气泡与评论都按当前章节归属，等阅读器定位到本章
+  await page.waitForFunction(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.comment_chapter === '未收录的章节')
+  await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const doc = contents.document
+    const paragraph = doc.getElementById('passage')
+    // 让末行只剩不到一个字的空位：气泡若参与排版就必然折行
+    const base = paragraph.textContent
+    const lines = () => { const range = doc.createRange(); range.selectNodeContents(paragraph); return range.getClientRects().length }
+    const initial = lines()
+    let extra = ''
+    while (extra.length < 200) {
+      paragraph.textContent = base + extra + '字'
+      if (lines() > initial && extra) { paragraph.textContent = base + extra; break }
+      extra += '字'
+    }
+    const other = doc.createElement('p')
+    other.id = 'other-passage'
+    other.textContent = '后一段的正文，划线标记必须始终盖在这几个字上。'
+    paragraph.after(other)
+    const full = doc.createRange()
+    full.selectNodeContents(paragraph.firstChild)
+    const highlight = doc.createRange()
+    highlight.setStart(other.firstChild, 2)
+    highlight.setEnd(other.firstChild, 12)
+    window.__highlightCfi = contents.cfiFromRange(highlight)
+    const chapter = reader.comment_chapter
+    await reader.annotation_repository.save({ client_id: 'bubble-note', annotation_type: 'note', is_private: false, chapter, cfi: reader.paragraph_for_range(full, contents).paragraph_cfi, range_cfi: contents.cfiFromRange(full), quote_text: paragraph.textContent, content: '本段公开评论', color: 'blue' })
+    await reader.annotation_repository.save({ client_id: 'bubble-highlight', annotation_type: 'highlight', is_private: true, chapter, cfi: window.__highlightCfi, range_cfi: window.__highlightCfi, quote_text: highlight.toString(), content: '', color: 'yellow' })
+  })
+  // 划线原文的位置，以及页面上划线标记的位置（主页面坐标）
+  const geometry = () => page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const frame = contents.window.frameElement.getBoundingClientRect()
+    const text = contents.range(window.__highlightCfi).getClientRects()[0]
+    const paragraph = contents.document.getElementById('passage')
+    const words = contents.document.createRange()
+    words.selectNodeContents(paragraph.firstChild)
+    return {
+      bubble: !!paragraph.querySelector('.comment-icon'),
+      text: { x: Math.round(frame.left + text.left), y: Math.round(frame.top + text.top) },
+      marks: Array.from(document.querySelectorAll('.candle-reader-annotation rect')).map(rect => rect.getBoundingClientRect()).map(rect => ({ x: Math.round(rect.left), y: Math.round(rect.top) })),
+      lines: Array.from(words.getClientRects()).map(rect => [rect.left, rect.top, rect.right, rect.bottom].map(Math.round)),
+    }
+  })
+  const toggle = value => page.evaluate(value => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    reader.update_settings({ ...reader.settings, show_comments: value })
+  }, value)
+
+  await toggle(false)
+  await expect.poll(() => geometry().then(g => g.bubble)).toBe(false)
+  const withoutBubble = await geometry()
+  await toggle(true)
+  await expect.poll(() => geometry().then(g => g.bubble)).toBe(true)
+  await expect.poll(() => geometry().then(g => g.marks.length)).toBeGreaterThan(0)
+  // 标记与气泡都是异步到达，等两者都落定后再比较
+  await page.waitForTimeout(300)
+  const withBubble = await geometry()
+  await captureEvidence(page, 'tb199-bubble-highlight-402x874.png')
+  // 气泡插入前后，本段文字的行框完全不变，后一段也不移动
+  expect(withBubble.lines).toEqual(withoutBubble.lines)
+  expect(withBubble.text).toEqual(withoutBubble.text)
+  // 划线标记仍盖在划线原文上
+  const { text, marks } = withBubble
+  expect(marks.some(mark => Math.abs(mark.x - text.x) <= 1 && Math.abs(mark.y - text.y) <= 1), JSON.stringify(withBubble)).toBe(true)
+})
+
+// 段尾常有 <br> 或换行空白：气泡必须紧跟最后一个字、与末行同高，不能掉到下一行；
+// 末行写满时可以伸进右侧页边距。有评论的段落不铺底色，只用气泡表示。
+test('段尾气泡紧跟最后一个字不换行，评论段落不铺底色', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+  })
+  await page.waitForFunction(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.comment_chapter === '未收录的章节')
+  await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const doc = contents.document
+    const passage = doc.getElementById('passage')
+    // 段内换行、段尾还跟着 <br> 和换行空白（与《西游记》诗句段落相同的结构）
+    passage.innerHTML = '春采百花为饮食，夏寻诸果作生涯。<br/>秋收芋栗延时节，冬觅黄精度岁华。<br/>\n'
+    // 末行恰好写满的段落
+    const full = doc.createElement('p')
+    full.id = 'full-passage'
+    passage.after(full)
+    const lines = () => { const range = doc.createRange(); range.selectNodeContents(full); return range.getClientRects().length }
+    // 逐字加长，直到再加一个字就会换行：此时末行恰好写满
+    let text = ''
+    let previous = 0
+    for (let i = 0; i < 400; i++) {
+      full.textContent = text + '字'
+      const count = lines()
+      if (previous && count > previous) { full.textContent = text; break }
+      previous = count
+      text += '字'
+    }
+    const chapter = reader.comment_chapter
+    for (const element of [passage, full]) {
+      const range = doc.createRange()
+      range.selectNodeContents(element)
+      const location = reader.paragraph_for_range(range, contents)
+      await reader.annotation_repository.save({ client_id: 'bubble-' + element.id, annotation_type: 'note', is_private: false, chapter, cfi: location.paragraph_cfi, range_cfi: location.paragraph_cfi, quote_text: location.paragraph_quote_text, content: '本段评论', color: 'blue' })
+    }
+    reader.on_comments_changed()
+  })
+  const geometry = () => page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const doc = contents.document
+    const padding = parseFloat(contents.window.getComputedStyle(doc.body).paddingRight) || 0
+    return ['passage', 'full-passage'].map(id => {
+      const paragraph = doc.getElementById(id)
+      const icon = paragraph.querySelector('.comment-icon')
+      if (!icon) return null
+      // 最后一个可见字（跳过段尾 <br> 后的空白与气泡本身）
+      const walker = doc.createTreeWalker(paragraph, NodeFilter.SHOW_TEXT)
+      let last = null
+      while (walker.nextNode()) if (!walker.currentNode.parentElement.closest('.comment-icon') && /\S/.test(walker.currentNode.textContent)) last = walker.currentNode
+      const end = last.textContent.search(/\s*$/)
+      const range = doc.createRange()
+      range.setStart(last, end - 1)
+      range.setEnd(last, end)
+      const rects = range.getClientRects()
+      const char = rects[rects.length - 1]
+      const box = icon.getBoundingClientRect()
+      const fragment = Array.from(paragraph.getClientRects()).find(r => char.left >= r.left - 1 && char.left <= r.right + 1) || paragraph.getBoundingClientRect()
+      return { char: [char.left, char.top, char.right, char.bottom], box: [box.left, box.top, box.right, box.bottom], limit: fragment.right + padding }
+    })
+  })
+  await expect.poll(() => geometry().then(items => items.every(Boolean))).toBe(true)
+  await page.waitForTimeout(300)
+  const items = await geometry()
+  await captureEvidence(page, 'tb199-bubble-line-end-402x874.png')
+  for (const { char, box, limit } of items) {
+    const middle = (box[1] + box[3]) / 2
+    // 与最后一个字同一行，紧跟其后
+    expect(middle, JSON.stringify(items)).toBeGreaterThanOrEqual(char[1])
+    expect(middle, JSON.stringify(items)).toBeLessThanOrEqual(char[3])
+    expect(box[0], JSON.stringify(items)).toBeGreaterThanOrEqual(char[2] - 1)
+    expect(box[0] - char[2], JSON.stringify(items)).toBeLessThanOrEqual(4)
+    // 不超出页边距
+    expect(box[2], JSON.stringify(items)).toBeLessThanOrEqual(limit + 1)
+  }
+  // 写满一行的段落：气泡伸进右侧页边距，而不是压住文字
+  expect(items[1].box[0]).toBeGreaterThanOrEqual(items[1].char[2] - 1)
+  // 文字评论不在正文铺底色
+  expect(await page.locator('.candle-reader-annotation').count()).toBe(0)
+  // 调大字号后正文重排，气泡仍跟着最后一个字
+  await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    reader.update_settings({ ...reader.settings, font_size: reader.settings.font_size + 6 })
+  })
+  await page.waitForTimeout(500)
+  const resized = await geometry()
+  const { char, box } = resized[0]
+  expect((box[1] + box[3]) / 2, JSON.stringify(resized)).toBeGreaterThanOrEqual(char[1])
+  expect((box[1] + box[3]) / 2, JSON.stringify(resized)).toBeLessThanOrEqual(char[3])
+  expect(box[0], JSON.stringify(resized)).toBeGreaterThanOrEqual(char[2] - 1)
+})
+
+test('同段不同选区共享整段评论范围，跨段评论归属最后一段', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const paragraph = contents.document.getElementById('passage')
+    paragraph.innerHTML = '段落开头<strong>中间的重点</strong>以及段落结尾。'
+    const other = contents.document.createElement('p')
+    other.id = 'other-passage'
+    other.textContent = '另一个段落的文字。'
+    paragraph.after(other)
+  })
+  async function select(startOffset, endOffset, crossParagraph = false) {
+    return page.evaluate(({ startOffset, endOffset, crossParagraph }) => {
+      const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+      const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+      const paragraph = contents.document.getElementById('passage')
+      const other = contents.document.getElementById('other-passage')
+      const range = contents.document.createRange()
+      range.setStart(paragraph.firstChild, startOffset)
+      range.setEnd(crossParagraph ? other.firstChild : paragraph.querySelector('strong').firstChild, endOffset)
+      const selection = contents.document.getSelection()
+      selection.removeAllRanges()
+      selection.addRange(range)
+      const full = contents.document.createRange()
+      full.setStart(paragraph.firstChild, 0)
+      full.setEnd(paragraph.lastChild, paragraph.lastChild.length)
+      const last = contents.document.createRange()
+      last.setStart(other.firstChild, 0)
+      last.setEnd(other.firstChild, other.firstChild.length)
+      return { cfi: contents.cfiFromRange(range), quote: range.toString(), fullCfi: contents.cfiFromRange(full), fullQuote: paragraph.textContent, lastCfi: contents.cfiFromRange(last) }
+    }, { startOffset, endOffset, crossParagraph })
+  }
+  const first = await select(1, 3)
+  const toolbar = page.locator('#comments-toolbar')
+  const drawer = page.locator('.reader-comments-drawer')
+  await expect(toolbar).toBeVisible()
+  await toolbar.getByRole('button', { name: '写评论' }).click()
+  await expect(page.locator('.annotation-editor-quote')).toHaveText(first.fullQuote)
+  await page.getByLabel('评论内容').fill('这个段落的公开评论')
+  await page.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(page.getByRole('dialog', { name: '写评论' })).toBeHidden()
+  await expect.poll(() => readState(page, 'annotation_editor_location')).toBe(null)
+  const second = await select(2, 5)
+  expect(second.cfi).not.toBe(first.cfi)
+  await expect(toolbar).toBeVisible()
+  await toolbar.getByRole('button', { name: '看本段评论' }).click()
+  await expect(drawer.getByText('这个段落的公开评论')).toBeVisible()
+  await notesButton(page).click()
+  await expect(drawer).toBeHidden()
+
+  // 跨段选区可以写评论：归属最后一段，真实选区另存。
+  const cross = await select(1, 4, true)
+  await expect(toolbar).toBeVisible()
+  await toolbar.getByRole('button', { name: '写评论' }).click()
+  await expect(page.locator('.annotation-editor-quote')).toHaveText(cross.quote)
+  await expect(page.getByText('跨段选区 · 评论归属最后一段。')).toBeVisible()
+  await page.getByLabel('评论内容').fill('跨两段的评论')
+  await page.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(page.getByRole('dialog', { name: '写评论' })).toBeHidden()
+  await expect.poll(() => readState(page, 'annotation_editor_location')).toBe(null)
+
+  // 跨段划线保留精确选区，固定私密，且不改变公开范围偏好。
+  await select(1, 4, true)
+  await expect(toolbar).toBeVisible()
+  await toolbar.getByRole('button', { name: '划线', exact: true }).click()
+  await expect(toolbar).toBeHidden()
+  const saved = await page.evaluate(() => JSON.parse(localStorage['candle-reader:annotations:v1:101']))
+  expect(saved).toHaveLength(3)
+  expect(saved[0]).toMatchObject({ annotation_type: 'note', cfi: first.fullCfi, quote_text: first.fullQuote, is_private: false })
+  expect(saved[1]).toMatchObject({ annotation_type: 'note', cfi: cross.lastCfi, range_cfi: cross.cfi, quote_text: cross.quote, is_private: false })
+  expect(saved[2]).toMatchObject({ annotation_type: 'highlight', cfi: cross.cfi, quote_text: cross.quote, is_private: true, content: '' })
+  expect(await page.evaluate(() => localStorage.getItem('candle-reader:comment-public'))).toBe('true')
+  // 两条公开评论分别归属各自的段落，气泡各计一条。
+  await expect.poll(() => page.evaluate(() => Array.from(document.querySelectorAll('#reader iframe')).flatMap(f => ['passage', 'other-passage'].map(id => f.contentDocument.getElementById(id)?.querySelector('.comment-count')?.textContent)).filter(Boolean))).toEqual(['1', '1'])
+})
+
+test('快速拖选文字不会被当作点击翻页，工具栏照常出现', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  // 选区放在屏幕右侧三分之一（点击这里原本会翻到下一页）。
+  const target = await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const paragraph = contents.document.getElementById('passage')
+    paragraph.style.marginLeft = '220px'
+    const frame = contents.window.frameElement.getBoundingClientRect()
+    const range = contents.document.createRange()
+    range.setStart(paragraph.firstChild, 0)
+    range.setEnd(paragraph.firstChild, 6)
+    const rect = range.getBoundingClientRect()
+    return { x: frame.left + rect.left + 2, y: frame.top + rect.top + rect.height / 2, width: rect.width, location: reader.rendition.currentLocation().start.cfi }
+  })
+  // 等加载遮罩完全淡出，鼠标才落在正文上。
+  await expect(page.locator('.v-overlay__scrim')).toHaveCount(0)
+  await page.mouse.move(target.x, target.y)
+  await page.mouse.down()
+  await page.mouse.move(target.x + target.width - 4, target.y, { steps: 3 })
+  await page.mouse.up()
+  await expect(page.locator('#comments-toolbar')).toBeVisible()
+  expect(await page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.rendition.currentLocation().start.cfi)).toBe(target.location)
+})
+
+test('已有选中文字时点击别处只取消选中，不翻页', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  await expect(page.locator('.v-overlay__scrim')).toHaveCount(0)
+  const location = await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const text = contents.document.getElementById('passage').firstChild
+    const range = contents.document.createRange()
+    range.setStart(text, 1)
+    range.setEnd(text, 8)
+    contents.document.getSelection().addRange(range)
+    return reader.rendition.currentLocation().start.cfi
+  })
+  await expect(page.locator('#comments-toolbar')).toBeVisible()
+  // 模拟 iOS：轻点不会先让浏览器清掉选区，直接派发 click 到正文右侧（原本会翻到下一页）。
+  await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const frame = contents.window.frameElement.getBoundingClientRect()
+    contents.document.body.dispatchEvent(new contents.window.MouseEvent('click', { bubbles: true, clientX: 380 - frame.left, clientY: 300 - frame.top, detail: 1, view: contents.window }))
+  })
+  await expect(page.locator('#comments-toolbar')).toBeHidden()
+  expect(await page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.rendition.getContents().map(c => c.window.getSelection().toString()).join(''))).toBe('')
+  await page.waitForTimeout(400)
+  expect(await page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.rendition.currentLocation().start.cfi)).toBe(location)
+})
+
+test('iOS：轻点时选区已被系统清掉，仍只取消选中而不翻页', async ({ page }) => {
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  await expect(page.locator('.v-overlay__scrim')).toHaveCount(0)
+  const location = await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const text = contents.document.getElementById('passage').firstChild
+    const range = contents.document.createRange()
+    range.setStart(text, 1)
+    range.setEnd(text, 8)
+    contents.document.getSelection().addRange(range)
+    return reader.rendition.currentLocation().start.cfi
+  })
+  await expect(page.locator('#comments-toolbar')).toBeVisible()
+  await expect(page.locator('.selection-preview').first()).toBeVisible()
+  await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    // 模拟 iOS：click 到达之前系统已经清掉了选区。
+    contents.window.getSelection().removeAllRanges()
+    const frame = contents.window.frameElement.getBoundingClientRect()
+    contents.document.body.dispatchEvent(new contents.window.MouseEvent('click', { bubbles: true, clientX: 380 - frame.left, clientY: 300 - frame.top, detail: 1, view: contents.window }))
+  })
+  await expect(page.locator('#comments-toolbar')).toBeHidden()
+  await expect(page.locator('.selection-preview')).toHaveCount(0)
+  await page.waitForTimeout(400)
+  expect(await page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.rendition.currentLocation().start.cfi)).toBe(location)
+  // 再点一下才是正常翻页。
+  await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const frame = contents.window.frameElement.getBoundingClientRect()
+    contents.document.body.dispatchEvent(new contents.window.MouseEvent('click', { bubbles: true, clientX: 380 - frame.left, clientY: 300 - frame.top, detail: 1, view: contents.window }))
+  })
+  await expect.poll(() => page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.rendition.currentLocation().start.cfi)).not.toBe(location)
+})
+
+test('关闭选中工具栏时不画阅读器自己的选区底色，点别处只取消选中', async ({ page }) => {
+  await page.addInitScript(() => localStorage.setItem('readerSettings', JSON.stringify({ show_selection_toolbar: false })))
+  await page.goto(`${HARNESS_URL}?missing_toc=1`)
+  await waitForReaderRendered(page)
+  await expect(page.locator('.v-overlay__scrim')).toHaveCount(0)
+  const location = await page.evaluate(async () => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    await reader.rendition.display('chapter.xhtml')
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    const text = contents.document.getElementById('passage').firstChild
+    const range = contents.document.createRange()
+    range.setStart(text, 1)
+    range.setEnd(text, 8)
+    contents.document.getSelection().addRange(range)
+    return reader.rendition.currentLocation().start.cfi
+  })
+  await expect.poll(() => readState(page, 'selection_active')).toBe(true)
+  await expect(page.locator('#comments-toolbar')).toBeHidden()
+  await expect(page.locator('.selection-preview')).toHaveCount(0)
+  await page.evaluate(() => {
+    const reader = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const contents = reader.rendition.getContents().find(item => reader.book.spine.get(item.sectionIndex).href === 'chapter.xhtml')
+    contents.window.getSelection().removeAllRanges()
+    const frame = contents.window.frameElement.getBoundingClientRect()
+    contents.document.body.dispatchEvent(new contents.window.MouseEvent('click', { bubbles: true, clientX: 380 - frame.left, clientY: 300 - frame.top, detail: 1, view: contents.window }))
+  })
+  await expect.poll(() => readState(page, 'selection_active')).toBe(false)
+  await page.waitForTimeout(400)
+  expect(await page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.rendition.currentLocation().start.cfi)).toBe(location)
+})
diff --git a/tests/e2e/audiobook.spec.js b/tests/e2e/audiobook.spec.js
index 1b8e12e..2e0e8e5 100644
--- a/tests/e2e/audiobook.spec.js
+++ b/tests/e2e/audiobook.spec.js
@@ -91,6 +91,7 @@ async function setupAudiobook(page) {
 async function gotoAudiobookReader(page) {
   await page.goto(`${HARNESS_URL}?audiobook=1`)
   await page.getByRole('button', { name: '听书', exact: true }).waitFor({ state: 'visible' })
+  await expect(page.locator('.v-bottom-navigation button')).toHaveText(['目录', '夜晚', '评论', '设置'])
   await waitForReaderRendered(page)
 }
 
@@ -189,3 +190,11 @@ test('选中正文后可从对应时间轴片段开始听', async ({ page }) =>
   await expect(player).toContainText('头好痛！', { timeout: 5000 })
   await expectActiveHighlight(page, { id: 'seg-2', text: '头好痛！' })
 })
+
+test('有声书数据经宿主回调获取，回调收到书籍上下文', async ({ page }) => {
+  await gotoAudiobookReader(page)
+  await page.getByRole('button', { name: '听书', exact: true }).click()
+  await expect(page.getByTestId('candle-audiobook-player')).toBeVisible()
+  await expect.poll(() => page.evaluate(() => window.__audiobookCalls.find(call => call.operation === 'manifest')?.query))
+    .toMatchObject({ book_id: 101, book_url: '/tests/e2e/fixtures/audiobook/' })
+})
diff --git a/tests/e2e/auth.spec.js b/tests/e2e/auth.spec.js
deleted file mode 100644
index 3cad0bb..0000000
--- a/tests/e2e/auth.spec.js
+++ /dev/null
@@ -1,96 +0,0 @@
-// 登录 / 用户中心相关流程，后端全部 mock。
-const { test, expect } = require('@playwright/test')
-const { setupApiMock, SAMPLE_USER } = require('./helpers/mock-api')
-const { gotoReader, readState } = require('./helpers/reader')
-
-test('未登录时「用户」面板展示登录表单', async ({ page }) => {
-  await setupApiMock(page) // 游客态：/api/user/info 返回未登录
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByRole('button', { name: '点击登录，发表评论' }).click()
-  await expect(page.getByText('登录到书评系统')).toBeVisible()
-  await expect(page.getByRole('button', { name: '登录', exact: true })).toBeVisible()
-})
-
-test('/api/review/me 返回 need_login 时 is_login 置为 false', async ({ page }) => {
-  await setupApiMock(page)
-  await gotoReader(page)
-  await expect.poll(() => readState(page, 'is_login')).toBe(false)
-})
-
-test('输入邮箱密码登录成功后展示用户中心', async ({ page }) => {
-  await setupApiMock(page, {
-    'POST /api/user/sign_in': { err: 'ok', data: SAMPLE_USER },
-  })
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByRole('button', { name: '点击登录，发表评论' }).click()
-  await page.getByLabel('邮箱').fill(SAMPLE_USER.email)
-  await page.getByLabel('密码').fill('secret123')
-  await page.getByRole('button', { name: '登录', exact: true }).click()
-
-  // 登录成功后对话框关闭，本书评论面板展示已登录用户行
-  await expect(page.getByText(SAMPLE_USER.nickname)).toBeVisible()
-  await expect.poll(() => readState(page, 'user')).not.toBeNull()
-})
-
-test('登录失败时展示错误提示且不进入用户中心', async ({ page }) => {
-  await setupApiMock(page, {
-    'POST /api/user/sign_in': { err: 'auth.failed', msg: '邮箱或密码错误' },
-  })
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByRole('button', { name: '点击登录，发表评论' }).click()
-  await page.getByLabel('邮箱').fill('wrong@example.com')
-  await page.getByLabel('密码').fill('bad')
-  await page.getByRole('button', { name: '登录', exact: true }).click()
-
-  await expect(page.getByText('邮箱或密码错误')).toBeVisible()
-  await expect(page.getByText('退出登录')).toBeHidden()
-})
-
-test('忘记密码：重置成功展示提示', async ({ page }) => {
-  await setupApiMock(page, {
-    'POST /api/user/reset': { err: 'ok' },
-  })
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByRole('button', { name: '点击登录，发表评论' }).click()
-  await page.getByRole('button', { name: '忘记密码?' }).click()
-  await page.getByLabel('邮箱').fill('reset@example.com')
-  await page.getByRole('button', { name: '重置密码' }).click()
-  await expect(page.getByText('重置成功！请查阅密码通知邮件。')).toBeVisible()
-})
-
-test('快速注册：注册成功展示提示并回到登录', async ({ page }) => {
-  await setupApiMock(page, {
-    'POST /api/user/sign_up': { err: 'ok' },
-  })
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByRole('button', { name: '点击登录，发表评论' }).click()
-  await page.getByRole('button', { name: '快速注册' }).click()
-  await page.getByLabel('邮箱').fill('newbie@example.com')
-  await page.getByLabel('昵称').fill('新书友')
-  await page.getByRole('button', { name: '注册', exact: true }).click()
-  await expect(page.getByText('注册成功！请查阅密码通知邮件。')).toBeVisible()
-})
-
-test('启动时已登录则「用户」面板直接展示用户中心', async ({ page }) => {
-  await setupApiMock(page, {
-    'GET /api/user/info': { err: 'ok', data: SAMPLE_USER },
-    'GET /api/review/me': { err: 'ok', data: { count: 3 } },
-  })
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  // 已登录：评论面板顶部展示用户行，点击进入用户中心
-  await page.getByText(SAMPLE_USER.nickname).click()
-  await expect(page.getByText('退出登录')).toBeVisible()
-  await expect(page.getByText('登录到书评系统')).toBeHidden()
-})
diff --git a/tests/e2e/comments-login.spec.js b/tests/e2e/comments-login.spec.js
deleted file mode 100644
index 15f3fcb..0000000
--- a/tests/e2e/comments-login.spec.js
+++ /dev/null
@@ -1,46 +0,0 @@
-// 回归测试：段评/章评面板里的「点击登录，发表评论」。
-// 历史 bug：BookComments 直接对只读 prop `login` 赋值（@click="login = !login"），
-// 触发 Vue 警告 "Set operation on key \"login\" failed: target is readonly"，
-// 点击登录无任何反应。修复后改为 $emit('login')，父组件 set_menu('more') 打开登录面板。
-const { test, expect } = require('@playwright/test')
-const { setupApiMock } = require('./helpers/mock-api')
-const { gotoReader, openPanel } = require('./helpers/reader')
-
-test.describe('章评面板登录入口', () => {
-  test.beforeEach(async ({ page }) => {
-    await setupApiMock(page) // 游客态：评论区显示「点击登录」按钮
-  })
-
-  test('未登录时评论面板展示「点击登录」按钮', async ({ page }) => {
-    await gotoReader(page)
-    await openPanel(page, 'comments')
-    await expect(page.getByText('评论列表')).toBeVisible()
-    await expect(page.getByRole('button', { name: '点击登录，发表评论' })).toBeVisible()
-  })
-
-  test('点击「点击登录」切换到登录面板，且无 readonly 警告', async ({ page }) => {
-    // 捕获控制台警告，用于断言不再出现 readonly 报错
-    const warnings = []
-    page.on('console', (msg) => {
-      if (msg.type() === 'warning' || msg.type() === 'error') {
-        warnings.push(msg.text())
-      }
-    })
-
-    await gotoReader(page)
-    await openPanel(page, 'comments')
-
-    // 章评面板「点击登录」→ set_menu('more') 切到本书评论面板
-    await page.getByRole('button', { name: '点击登录，发表评论' }).click()
-    await expect(page.getByText('本书评论')).toBeVisible()
-
-    // 本书评论面板「点击登录」→ 弹出登录对话框（限定在本书评论卡片内，避开收起中的章评面板同名按钮）
-    await page.locator('.book-review-card').getByRole('button', { name: '点击登录，发表评论' }).click()
-    await expect(page.getByText('登录到书评系统')).toBeVisible()
-    await expect(page.getByRole('button', { name: '登录', exact: true })).toBeVisible()
-
-    // 关键断言：不再有“对只读对象赋值”的 Vue 警告
-    const readonlyWarn = warnings.find((w) => /readonly/i.test(w) && /login/i.test(w))
-    expect(readonlyWarn, `不应出现 readonly 警告，实际捕获:\n${warnings.join('\n')}`).toBeUndefined()
-  })
-})
diff --git a/tests/e2e/comments.spec.js b/tests/e2e/comments.spec.js
index 0d788be..43b889c 100644
--- a/tests/e2e/comments.spec.js
+++ b/tests/e2e/comments.spec.js
@@ -1,49 +1,464 @@
-// 章评/段评面板：评论列表展示与发表（已登录态）。
+// 统一评论：抽屉、完整评论页、评论详情页，以及赞、踩、回复、修改、删除。
+// 数据全部来自内存版宿主（annotation_callbacks），阅读器不直接请求任何后端。
 const { test, expect } = require('@playwright/test')
-const { setupApiMock, SAMPLE_COMMENTS } = require('./helpers/mock-api')
-const { gotoReader, openCommentsPanel, readState } = require('./helpers/reader')
+const { setupApiMock } = require('./helpers/mock-api')
+const { gotoHostReader } = require('./helpers/reader')
 
-// 已登录态：review/me 返回 ok，使 is_login 保持 true（评论区显示输入框而非登录按钮）
-const LOGGED_IN = { 'GET /api/review/me': { err: 'ok', data: { count: 0 } } }
+test.use({ viewport: { width: 402, height: 874 } })
 
-test('已登录时评论面板展示输入框与发表按钮', async ({ page }) => {
-  await setupApiMock(page, LOGGED_IN)
-  await gotoReader(page)
-  await openCommentsPanel(page)
+const nav = page => page.locator('.v-bottom-navigation').getByRole('button', { name: '评论' })
+const drawer = page => page.locator('.reader-comments-drawer')
+const fullPage = page => page.getByRole('dialog', { name: '完整评论页' })
+const detail = page => page.getByRole('dialog', { name: '评论详情' })
+const item = (scope, id) => scope.locator(`[data-comment="${id}"]`)
+const hostCalls = (page, operation) => page.evaluate(op => window.__host.calls.filter(call => call.operation === op), operation)
 
-  await expect(page.getByPlaceholder('爱书之人，维持良好的社区氛围')).toBeVisible()
-  await expect(page.getByRole('button', { name: '发表' })).toBeVisible()
-  await expect(page.getByRole('button', { name: '点击登录，发表评论' })).toBeHidden()
+let api
+test.beforeEach(async ({ page }) => {
+  api = await setupApiMock(page)
 })
 
-test('评论列表渲染后端返回的评论', async ({ page }) => {
-  await setupApiMock(page, {
-    ...LOGGED_IN,
-    'GET /api/review/list': { err: 'ok', data: { list: SAMPLE_COMMENTS } },
-  })
-  await gotoReader(page)
-  await openCommentsPanel(page)
+test('评论抽屉默认展示本章公开评论，自己的在前，阅读器不直接请求评论或账号接口', async ({ page }) => {
+  await gotoHostReader(page)
+  await nav(page).click()
+  await expect(drawer(page).getByText('本章评论', { exact: true })).toBeVisible()
+  const items = drawer(page).locator('.comment-item')
+  await expect(items).toHaveCount(3)
+  await expect(items.first()).toHaveAttribute('data-mine', 'true')
+  // 私密记录、整书评论和别的章节不进入本章评论。
+  for (const id of [3, 5, 6, 7]) await expect(item(drawer(page), id)).toHaveCount(0)
+  // 别人的评论没有修改和删除入口。
+  await expect(item(drawer(page), 1).getByRole('button', { name: '修改' })).toHaveCount(0)
+  await expect(item(drawer(page), 2).getByRole('button', { name: '修改' })).toBeVisible()
+  // 抽屉展开时底部菜单仍可见可点，占菜单上方区域的 90%。
+  const menu = await page.locator('.v-bottom-navigation').boundingBox()
+  const sheet = () => page.locator('.annotation-bottom-sheet .v-overlay__content').boundingBox()
+  await expect.poll(async () => Math.round((await sheet()).y)).toBe(Math.round(menu.y * 0.1))
+  expect(Math.round((await sheet()).height)).toBe(Math.round(menu.y * 0.9))
+  await expect(drawer(page).getByPlaceholder(/搜索/)).toHaveCount(0)
+  expect(api.calls.filter(call => /\/api\/(review|user)\//.test(call.url))).toEqual([])
+  await nav(page).click()
+  await expect(drawer(page)).toBeHidden()
+})
+
+test('滚动到底自动加载下一页，切换范围重置分页且迟到响应不混入', async ({ page }) => {
+  await gotoHostReader(page, '&extra=45')
+  await nav(page).click()
+  const items = drawer(page).locator('.comment-item')
+  await expect(items).toHaveCount(20)
+  await expect(drawer(page).getByText('继续下滑，加载更多评论')).toBeVisible()
+  await drawer(page).locator('.comment-list').evaluate(el => { el.scrollTop = el.scrollHeight })
+  await expect(items).toHaveCount(40)
+  await drawer(page).locator('.comment-list').evaluate(el => { el.scrollTop = el.scrollHeight })
+  await expect(items).toHaveCount(48)
+  await expect(drawer(page).getByText('已显示全部评论')).toBeVisible()
+  expect((await hostCalls(page, 'list')).map(call => call.query.cursor)).toEqual([null, '20', '40'])
+
+  await drawer(page).getByRole('button', { name: /查看更多评论/ }).click()
+  const pageItems = fullPage(page).locator('.comment-item')
+  await expect(pageItems).toHaveCount(20)
+  // 本章的下一页还在路上时切到「我的」：迟到的本章数据不能混进来。
+  await page.evaluate(() => window.__host.hold('list'))
+  await fullPage(page).locator('.comment-list').evaluate(el => { el.scrollTop = el.scrollHeight })
+  await expect.poll(async () => (await hostCalls(page, 'list')).length).toBe(5)
+  await page.evaluate(() => { window.__host.release('list') ; window.__host.hold('list') })
+  await fullPage(page).getByRole('button', { name: '我的' }).click()
+  await page.evaluate(() => window.__host.release('list'))
+  await expect(pageItems).toHaveCount(3)
+  await expect(fullPage(page).locator('.comment-item[data-mine="false"]')).toHaveCount(0)
+})
+
+test('完整评论页独立占满区域，「我的」含私密记录，返回后恢复抽屉', async ({ page }) => {
+  await gotoHostReader(page, '&extra=30')
+  await nav(page).click()
+  await expect(drawer(page).locator('.comment-item')).toHaveCount(20)
+  await drawer(page).locator('.comment-list').evaluate(el => { el.scrollTop = 300 })
+  await drawer(page).getByRole('button', { name: /查看更多评论/ }).click()
+  await expect(fullPage(page)).toBeVisible()
+  await expect.poll(async () => Object.values(await fullPage(page).locator('.rc-page').boundingBox())).toEqual([0, 0, 402, 874])
+  // 独立页面盖住阅读菜单。
+  expect(await page.evaluate(() => document.elementFromPoint(200, 860).closest('.v-bottom-navigation'))).toBe(null)
+  await expect(fullPage(page).locator('.rc-tab')).toHaveText(['本章评论', '全书评论', '我的'])
+
+  await fullPage(page).getByRole('button', { name: '全书评论' }).click()
+  await expect(item(fullPage(page), 6)).toBeVisible()
+  await expect(item(fullPage(page), 7)).toBeVisible()
+  await expect(item(fullPage(page), 5)).toHaveCount(0)
+
+  await fullPage(page).getByRole('button', { name: '我的' }).click()
+  await expect(fullPage(page).locator('.comment-item')).toHaveCount(3)
+  await expect(item(fullPage(page), 3).locator('.comment-tag')).toHaveText(['划线'])
+  await expect(item(fullPage(page), 3).locator('.comment-private')).toHaveText('私密')
+  await expect(item(fullPage(page), 3).getByRole('button', { name: '修改' })).toHaveCount(0)
+  // 修改、删除放在每条记录底部一行的右端，不跟在正文后面；按钮留 8px 内边距，文字与右侧时间对齐。
+  const placements = await fullPage(page).locator('.comment-item').evaluateAll(items => items.map(el => {
+    const footer = el.querySelector('.comment-footer').getBoundingClientRect()
+    const remove = Array.from(el.querySelectorAll('button')).find(button => button.textContent.trim() === '删除')
+    const rect = remove.getBoundingClientRect()
+    return { inFooter: Boolean(remove.closest('.comment-footer')), inContent: Boolean(remove.closest('.comment-content')), rightGap: Math.round(footer.right - rect.right), below: rect.top >= el.querySelector('.comment-content').getBoundingClientRect().bottom - 1 }
+  }))
+  expect(placements).toHaveLength(3)
+  for (const placement of placements) expect(placement).toEqual({ inFooter: true, inContent: false, rightGap: -8, below: true })
+  // 私密记录没有赞踩和回复入口。
+  await expect(item(fullPage(page), 5).locator('.comment-vote')).toHaveCount(0)
+  await expect(item(fullPage(page), 5).getByRole('button', { name: '1 条回复 · 仅你可见' })).toBeVisible()
+
+  // 浏览器返回回到抽屉：范围、已加载数量与滚动位置保持不变。
+  await page.goBack()
+  await expect(fullPage(page)).toBeHidden()
+  await expect(drawer(page).locator('.comment-item')).toHaveCount(20)
+  expect(await drawer(page).locator('.comment-list').evaluate(el => el.scrollTop)).toBe(300)
+  await expect(drawer(page).getByRole('button', { name: /查看更多评论/ })).toBeFocused()
+})
+
+test('赞踩互斥可取消，失败时恢复原状', async ({ page }) => {
+  await gotoHostReader(page)
+  await nav(page).click()
+  const like = item(drawer(page), 1).getByRole('button', { name: /^赞/ })
+  const dislike = item(drawer(page), 1).getByRole('button', { name: /^踩/ })
+  await expect(like).toHaveAccessibleName('赞 12')
+  await like.click()
+  await expect(like).toHaveAccessibleName('赞 13')
+  await expect(like).toHaveAttribute('aria-pressed', 'true')
+  await dislike.click()
+  await expect(like).toHaveAccessibleName('赞 12')
+  await expect(dislike).toHaveAccessibleName('踩 2')
+  await dislike.click()
+  await expect(dislike).toHaveAccessibleName('踩 1')
+  await expect(dislike).toHaveAttribute('aria-pressed', 'false')
+  expect((await hostCalls(page, 'vote')).map(call => call.query.value)).toEqual([1, -1, 0])
+  // 允许给自己的评论投票。
+  await item(drawer(page), 2).getByRole('button', { name: /^赞/ }).click()
+  await expect(item(drawer(page), 2).getByRole('button', { name: /^赞/ })).toHaveAccessibleName('赞 5')
+  // 点赞踩不进入详情页。
+  await expect(detail(page)).toBeHidden()
+
+  await page.evaluate(() => window.__host.fail('vote', '模拟投票失败'))
+  await like.click()
+  await expect(page.getByText('操作失败：模拟投票失败')).toBeVisible()
+  await expect(like).toHaveAccessibleName('赞 12')
+  await expect(like).toHaveAttribute('aria-pressed', 'false')
+})
+
+test('点击单条评论进入详情页：第一层回复不缩进，之后统一缩进一级，可回复、修改、删除', async ({ page }) => {
+  await gotoHostReader(page)
+  await nav(page).click()
+  await item(drawer(page), 1).locator('.comment-content').click()
+  await expect(detail(page)).toBeVisible()
+  // 列表内不展开回复。
+  await expect(drawer(page).locator('[data-comment="901"]')).toHaveCount(0)
+  const left = async id => (await item(detail(page), id).locator('.comment-content').boundingBox()).x
+  await expect.poll(() => left(1)).toBe(20)
+  expect(await left(901)).toBe(await left(1))
+  expect(await left(902)).toBeGreaterThan(await left(901) + 16)
+  expect(await left(903)).toBe(await left(902))
+  await expect(item(detail(page), 902).locator('.comment-content')).toContainText('回复 小舟：')
+  await expect(item(detail(page), 901).getByRole('button', { name: '删除' })).toHaveCount(0)
+
+  // 回复第二层回复：仍在同一组内，不再加深。
+  const input = detail(page).getByLabel('回复内容')
+  await item(detail(page), 903).getByRole('button', { name: '回复', exact: true }).click()
+  await expect(input).toHaveAttribute('placeholder', '回复 林间')
+  await input.fill('第三遍了')
+  await detail(page).getByRole('button', { name: '发送' }).click()
+  const third = detail(page).locator('.comment-item', { hasText: '第三遍了' })
+  await expect(third).toContainText('回复 林间：')
+  expect((await third.locator('.comment-content').boundingBox()).x).toBe(await left(902))
+  await expect(item(detail(page), 1).getByRole('button', { name: '回复 4' })).toBeVisible()
+
+  // 回复主评论：新的第一层回复，不缩进。
+  await item(detail(page), 1).getByRole('button', { name: '回复 4' }).click()
+  await expect(input).toHaveAttribute('placeholder', '回复 林间')
+  await input.fill('直接回主评论')
+  await detail(page).getByRole('button', { name: '发送' }).click()
+  const first = detail(page).locator('.comment-item', { hasText: '直接回主评论' })
+  expect((await first.locator('.comment-content').boundingBox()).x).toBe(await left(1))
+
+  // 修改自己的回复，不显示「已编辑」。
+  await item(detail(page), 902).getByRole('button', { name: '修改' }).click()
+  await expect(input).toHaveValue('所以这一段我读了两遍。')
+  await input.fill('这一段我读了三遍。')
+  await detail(page).getByRole('button', { name: '保存' }).click()
+  await expect(item(detail(page), 902)).toContainText('这一段我读了三遍。')
+  await expect(item(detail(page), 902)).not.toContainText('已编辑')
+
+  // 删除自己的第一层回复：其下回复一并删除。
+  await first.getByRole('button', { name: '回复', exact: true }).click()
+  await input.fill('自己接一句')
+  await detail(page).getByRole('button', { name: '发送' }).click()
+  await expect(item(detail(page), 1).getByRole('button', { name: '回复 6' })).toBeVisible()
+  await first.getByRole('button', { name: '删除' }).click()
+  await expect(page.getByText('这条回复下的 1 条回复也会一并删除。确定删除吗？')).toBeVisible()
+  await page.getByRole('button', { name: '删除', exact: true }).last().click()
+  await expect(detail(page).locator('.comment-item', { hasText: '自己接一句' })).toHaveCount(0)
+  await expect(item(detail(page), 1).getByRole('button', { name: '回复 4' })).toBeVisible()
+
+  // 返回后列表里的回复数同步，焦点回到进入时的条目。
+  await detail(page).getByRole('button', { name: '返回评论列表' }).click()
+  await expect(detail(page)).toBeHidden()
+  await expect(item(drawer(page), 1).getByRole('button', { name: '回复 4' })).toBeFocused()
+})
 
-  await expect(page.getByText('这一段写得真好')).toBeVisible()
-  await expect(page.getByText('深有同感')).toBeVisible()
+test('在详情页删除主评论：连同回复删除并回到列表', async ({ page }) => {
+  await gotoHostReader(page)
+  await nav(page).click()
+  await item(drawer(page), 2).getByRole('button', { name: '回复 0' }).click()
+  await expect(detail(page)).toBeVisible()
+  await detail(page).getByLabel('回复内容').fill('先回一条')
+  await detail(page).getByRole('button', { name: '发送' }).click()
+  await item(detail(page), 2).getByRole('button', { name: '删除' }).click()
+  await expect(page.getByText('这条评论下的 1 条回复也会一并删除。确定删除吗？')).toBeVisible()
+  await page.getByRole('button', { name: '删除', exact: true }).last().click()
+  await expect(detail(page)).toBeHidden()
+  await expect(item(drawer(page), 2)).toHaveCount(0)
+  expect(await page.evaluate(() => window.__host.records.filter(record => record.id === 2 || record.root_id === 2).length)).toBe(0)
 })
 
-test('发表评论成功后追加到列表', async ({ page }) => {
-  const newComment = { id: 99, content: '写得很好', nickName: '测试书友', avatar: 'mdi-account', level: 3, createTime: '2026-06-02', geo: '杭州', likeCount: 0 }
-  await setupApiMock(page, {
-    ...LOGGED_IN,
-    'GET /api/review/list': { err: 'ok', data: { list: [] } },
-    'POST /api/review/add': { err: 'ok', data: newComment },
+test('私密记录的详情只读，回复仅作者可见', async ({ page }) => {
+  await gotoHostReader(page)
+  await nav(page).click()
+  await drawer(page).getByRole('button', { name: /查看更多评论/ }).click()
+  await fullPage(page).getByRole('button', { name: '我的' }).click()
+  await item(fullPage(page), 5).getByRole('button', { name: '1 条回复 · 仅你可见' }).click()
+  await expect(detail(page).getByText('1 条回复 · 仅你可见')).toBeVisible()
+  await expect(item(detail(page), 904)).toBeVisible()
+  await expect(detail(page).locator('.comment-vote')).toHaveCount(0)
+  await expect(detail(page).getByLabel('回复内容')).toHaveCount(0)
+  // Esc 只退出详情页，仍停在完整页「我的」。
+  await page.keyboard.press('Escape')
+  await expect(detail(page)).toBeHidden()
+  await expect(fullPage(page).getByRole('button', { name: '我的' })).toHaveAttribute('aria-pressed', 'true')
+})
+
+test('修改评论并改为私密后，只在「我的」中出现', async ({ page }) => {
+  await gotoHostReader(page)
+  await nav(page).click()
+  await item(drawer(page), 2).getByRole('button', { name: '修改' }).click()
+  const editor = page.getByRole('dialog', { name: '编辑评论' })
+  await expect(editor.getByLabel('评论内容')).toHaveValue('读到这里想到上周的散步。')
+  await editor.getByLabel('评论内容').fill('改过的内容')
+  await editor.getByRole('switch', { name: '公开这条评论' }).uncheck()
+  await editor.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(editor).toBeHidden()
+  await expect(item(drawer(page), 2)).toHaveCount(0)
+  await drawer(page).getByRole('button', { name: /查看更多评论/ }).click()
+  await fullPage(page).getByRole('button', { name: '我的' }).click()
+  await expect(item(fullPage(page), 2)).toContainText('改过的内容')
+  await expect(item(fullPage(page), 2)).not.toContainText('已编辑')
+  // 编辑已有记录不改变「新建时默认公开范围」的偏好。
+  expect(await page.evaluate(() => localStorage.getItem('candle-reader:comment-public'))).toBe(null)
+})
+
+test('写整书评论：只出现在全书评论，公开范围偏好被记住', async ({ page }) => {
+  await gotoHostReader(page)
+  await nav(page).click()
+  await drawer(page).getByRole('button', { name: '写评论' }).click()
+  const editor = page.getByRole('dialog', { name: '写整书评论' })
+  await expect(editor.getByRole('switch', { name: '公开这条评论' })).toBeChecked()
+  await editor.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(editor.getByText('请填写评论内容')).toBeVisible()
+  await editor.getByLabel('评论内容').fill('整本书都很好看')
+  await editor.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(page.getByText('评论已保存，可在「全书评论」中查看')).toBeVisible()
+  await expect(drawer(page).getByText('整本书都很好看')).toHaveCount(0)
+  const saved = (await hostCalls(page, 'save')).pop().query
+  expect(saved).toMatchObject({ annotation_type: 'book_comment', is_private: false, content: '整本书都很好看' })
+  expect(saved.cfi).toMatch(/^epubcfi\(.+!\/4\)$/)
+  await drawer(page).getByRole('button', { name: /查看更多评论/ }).click()
+  await fullPage(page).getByRole('button', { name: '全书评论' }).click()
+  await expect(fullPage(page).getByText('整本书都很好看')).toBeVisible()
+
+  // 改成私密保存后，下次新建沿用私密；刷新后仍保留。
+  await fullPage(page).getByRole('button', { name: '写评论' }).click()
+  await editor.getByRole('switch', { name: '公开这条评论' }).uncheck()
+  await editor.getByLabel('评论内容').fill('只给自己看')
+  await editor.getByRole('button', { name: '保存', exact: true }).click()
+  await expect(page.getByText('已保存为私密，可在「查看更多评论 › 我的」中查看')).toBeVisible()
+  await expect(fullPage(page).getByText('只给自己看')).toHaveCount(0)
+  await page.reload()
+  await nav(page).click()
+  await drawer(page).getByRole('button', { name: '写评论' }).click()
+  await expect(editor.getByRole('switch', { name: '公开这条评论' })).not.toBeChecked()
+})
+
+test('游客可以浏览，互动与「我的」引导登录', async ({ page }) => {
+  await gotoHostReader(page, '&guest=1')
+  await nav(page).click()
+  await expect(drawer(page).locator('.comment-item')).toHaveCount(3)
+  await expect(drawer(page).locator('.comment-item[data-mine="true"]')).toHaveCount(0)
+  await item(drawer(page), 1).getByRole('button', { name: /^赞/ }).click()
+  await expect(page.getByText('请先登录后再操作')).toBeVisible()
+  await expect(item(drawer(page), 1).getByRole('button', { name: /^赞/ })).toHaveAccessibleName('赞 12')
+  expect(await hostCalls(page, 'vote')).toEqual([])
+  expect((await hostCalls(page, 'login')).length).toBe(1)
+  await drawer(page).getByRole('button', { name: '写评论' }).click()
+  await expect(page.getByRole('dialog', { name: '写整书评论' })).toHaveCount(0)
+  await drawer(page).getByRole('button', { name: /查看更多评论/ }).click()
+  await fullPage(page).getByRole('button', { name: '我的' }).click()
+  await expect(fullPage(page).getByText('登录后查看你的划线和评论')).toBeVisible()
+  // 游客可以进入详情查看回复，但不能回复。
+  await fullPage(page).getByRole('button', { name: '本章评论' }).click()
+  await item(fullPage(page), 1).locator('.comment-content').click()
+  await expect(item(detail(page), 901)).toBeVisible()
+  await detail(page).getByLabel('回复内容').fill('游客回复')
+  await detail(page).getByRole('button', { name: '发送' }).click()
+  expect(await hostCalls(page, 'save')).toEqual([])
+})
+
+test('加载失败可重试，空范围有空状态', async ({ page }) => {
+  await gotoHostReader(page)
+  await page.evaluate(() => window.__host.fail('list', '模拟读取失败'))
+  await nav(page).click()
+  await expect(drawer(page).getByRole('alert')).toContainText('模拟读取失败')
+  await expect(drawer(page).getByText('这里还没有公开评论')).toHaveCount(0)
+  await page.evaluate(() => window.__host.fail('list'))
+  await drawer(page).getByRole('button', { name: '重新加载' }).click()
+  await expect(drawer(page).locator('.comment-item')).toHaveCount(3)
+  await page.evaluate(() => { window.__host.records.length = 0 })
+  await nav(page).click()
+  await nav(page).click()
+  await expect(drawer(page).getByText('这里还没有公开评论')).toBeVisible()
+})
+
+test('桌面端评论是右侧覆盖式侧边栏，目录在左侧，底部菜单保持可用', async ({ page }) => {
+  await page.setViewportSize({ width: 1280, height: 800 })
+  await gotoHostReader(page)
+  const reader = await page.locator('#reader').boundingBox()
+  await nav(page).click()
+  const menu = await page.locator('.v-bottom-navigation').boundingBox()
+  // 避开顶部栏与底部菜单，贴右侧。
+  await expect.poll(async () => Object.values(await page.locator('.annotation-bottom-sheet .v-overlay__content').boundingBox())).toEqual([860, 48, 420, menu.y - 48])
+  expect((await page.locator('#reader').boundingBox()).width).toBe(reader.width)
+  await page.locator('.v-bottom-navigation').getByRole('button', { name: '目录' }).click()
+  await expect(drawer(page)).toBeHidden()
+  await expect.poll(async () => { const toc = await page.locator('.reader-side-left .v-overlay__content').boundingBox(); return [toc.x, toc.y, toc.width] }).toEqual([0, 48, 300])
+})
+
+test('宿主要求登录才能看评论时，游客看到登录提示，登录后自动加载', async ({ page }) => {
+  await gotoHostReader(page, '&guest=1&locked=1')
+  await nav(page).click()
+  await expect(drawer(page).getByText('登录后查看评论')).toBeVisible()
+  await expect(drawer(page).getByRole('alert')).toHaveCount(0)
+  // 模拟宿主的登录流程：login 回调里完成登录。
+  await page.evaluate(() => {
+    const host = window.__host
+    const original = host.callbacks.login
+    host.callbacks.login = async (...args) => { await original(...args); host.setUser(true) }
   })
-  // on_add_review 成功后会 alert('评论成功')，自动接受弹窗
-  page.on('dialog', (d) => d.accept())
+  await drawer(page).getByRole('button', { name: '去登录' }).click()
+  await expect(drawer(page).locator('.comment-item')).toHaveCount(3)
+})
+
+test('评论区强调色文字在各主题下与底色对比度不低于 4.5:1', async ({ page }) => {
+  await gotoHostReader(page)
+  await nav(page).click()
+  const more = drawer(page).getByRole('button', { name: /查看更多评论/ })
+  await expect(more).toBeVisible()
+  for (const theme of ['white', 'eyecare', 'grey', 'dark', 'zhulin', 'parchment', 'huitu', 'xingye']) {
+    await page.evaluate(theme => {
+      const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+      r.update_settings({ ...r.settings, theme })
+    }, theme)
+    await expect.poll(() => more.evaluate(el => {
+      // color-mix 的计算值是 color(srgb r g b)，分量为 0–1；rgb() 分量为 0–255。
+      const parse = c => {
+        const m = c.match(/[\d.]+/g).map(Number)
+        return { rgb: c.startsWith('color(') ? m.slice(0, 3).map(v => v * 255) : m.slice(0, 3), a: m.length > 3 ? m[3] : 1 }
+      }
+      const layers = []
+      for (let e = el; e; e = e.parentElement) {
+        const c = parse(getComputedStyle(e).backgroundColor)
+        if (c.a > 0) { layers.unshift(c); if (c.a >= 1) break }
+      }
+      const bg = layers.reduce((rgb, l) => rgb.map((v, i) => v * (1 - l.a) + l.rgb[i] * l.a), [255, 255, 255])
+      const fg = parse(getComputedStyle(el).color)
+      const lum = rgb => rgb.map(v => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4 })
+        .reduce((s, v, i) => s + v * [0.2126, 0.7152, 0.0722][i], 0)
+      const [a, b] = [lum(fg.rgb.map((v, i) => v * fg.a + bg[i] * (1 - fg.a))), lum(bg)]
+      return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05)
+    }), `${theme} 主题下「查看更多评论」对比度不足`).toBeGreaterThanOrEqual(4.5)
+  }
+})
+
+test('一页横跨两章时，页尾那一章的段落评论也显示气泡，点开按段落所在章节列出', async ({ page }) => {
+  // 西游记一个正文文件里有好几回；从第三回开头那段所在的页开始读，这一页从第二回末尾跨进第三回。
+  await gotoHostReader(page, '&book=xi-you-ji.epub&at=' + encodeURIComponent('5039418960600707614_23962-0-0.txt.xhtml#chapter-003'))
+  const target = '那厢乃傲来国界'
+  const layout = await page.evaluate(async target => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const find = () => {
+      for (const c of r.rendition.getContents()) {
+        const p = [...c.document.querySelectorAll('p')].find(p => p.textContent.includes(target))
+        if (p) return { c, p }
+      }
+    }
+    const { c, p } = find()
+    await r.rendition.display(c.cfiFromNode(p))
+    await new Promise(resolve => setTimeout(resolve, 1500))
+    return { start: r.current_toc.label }
+  }, target)
+  expect(layout.start, '前置条件：页首仍在第二回').toContain('第二回')
 
-  await gotoReader(page)
-  await openCommentsPanel(page)
+  // 在第三回的这段选几个字，写一条公开评论。
+  await page.evaluate(async target => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    for (const c of r.rendition.getContents()) {
+      const p = [...c.document.querySelectorAll('p')].find(p => p.textContent.includes(target))
+      if (!p) continue
+      const walker = c.document.createTreeWalker(p, NodeFilter.SHOW_TEXT)
+      let node
+      while ((node = walker.nextNode()) && node.textContent.trim().length < 5);
+      const range = c.document.createRange()
+      range.setStart(node, 0)
+      range.setEnd(node, 4)
+      r.rendition.emit('selected', c.cfiFromRange(range), c)
+    }
+    r.open_note_editor()
+    r.annotation_editor_content = '跨章页面的段落评论'
+    r.annotation_editor_private = false
+    await r.save_note()
+  }, target)
+  const saved = (await hostCalls(page, 'save')).at(-1)
+  expect(saved.query.chapter).toContain('第三回')
 
-  await page.getByPlaceholder('爱书之人，维持良好的社区氛围').fill('写得很好')
-  await page.getByRole('button', { name: '发表' }).click()
+  // 保存后气泡立刻出现在这段末尾，不用翻页。
+  const bubble = () => page.evaluate(target => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    for (const c of r.rendition.getContents()) {
+      const p = [...c.document.querySelectorAll('p')].find(p => p.textContent.includes(target))
+      const icon = p && p.querySelector('.comment-icon')
+      if (icon) return icon.textContent.trim()
+    }
+    return null
+  }, target)
+  await expect.poll(bubble).toBe('1')
 
-  await expect.poll(() => readState(page, 'comments').then(c => c.length)).toBe(1)
-  await expect(page.getByText('写得很好')).toBeVisible()
+  // 点气泡：本段评论按第三回查询，列出刚写的评论。
+  await page.evaluate(target => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    for (const c of r.rendition.getContents()) {
+      const p = [...c.document.querySelectorAll('p')].find(p => p.textContent.includes(target))
+      p?.querySelector('.comment-icon')?.click()
+    }
+  }, target)
+  await expect(drawer(page).getByText('跨章页面的段落评论')).toBeVisible()
+  const query = (await hostCalls(page, 'list')).at(-1).query
+  expect(query.scope).toBe('paragraph')
+  expect(query.chapter).toContain('第三回')
+})
+
+test('一屏跨好几章时，页首到页尾之间的每一章都读取气泡和划线', async ({ page }) => {
+  // 西游记前十一回在同一个正文文件里。模拟一屏从第一回跨到第五回（短章、宽屏或连续滚动时会出现）。
+  await gotoHostReader(page, '&book=xi-you-ji.epub&at=' + encodeURIComponent('5039418960600707614_23962-0-0.txt.xhtml#chapter-003'))
+  const chapters = await page.evaluate(() => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const flat = []
+    const collect = items => items.forEach(item => { flat.push(item); if (item.subitems?.length) collect(item.subitems) })
+    collect(r.toc_items)
+    const pick = prefix => flat.find(item => item.label.trim().startsWith(prefix))
+    const contents = r.rendition.getContents().find(c => r.book.spine.get(c.sectionIndex).href === pick('第一回').href.split('#')[0])
+    return r.tocs_between({ contents, toc: pick('第一回') }, { contents, toc: pick('第五回') }, r.rendition.getContents())
+      .map(item => item.toc.label.trim().slice(0, 3))
+  })
+  expect(chapters).toEqual(['第一回', '第二回', '第三回', '第四回', '第五回'])
 })
diff --git a/tests/e2e/fixtures/README.md b/tests/e2e/fixtures/README.md
new file mode 100644
index 0000000..427ffaa
--- /dev/null
+++ b/tests/e2e/fixtures/README.md
@@ -0,0 +1,3 @@
+`missing-toc/` 是故意只将封面写入 NCX 的 EPUB，正文包括有标题的段落和无标题的 div。用于验证缺目录时保存真实选区/CFI、刷新及开关后恢复。
+
+`audiobook/` 是固定的两节 EPUB，保留 `audiobook.spec.js` 时间轴依赖的 href、fragment、段落次序和文本。原测试使用 demo 整卷（单节 HTML 约 2.5 MB），连续分页布局可令 display Promise 超过用例超时；此夹具将有声书 UI/定位行为与整卷排版性能分开，四项有声书断言保持不变。完整真实书籍的笔记验收另由 Talebook 集成脚本执行。
diff --git a/tests/e2e/fixtures/audiobook/META-INF/container.xml b/tests/e2e/fixtures/audiobook/META-INF/container.xml
new file mode 100644
index 0000000..80f6c50
--- /dev/null
+++ b/tests/e2e/fixtures/audiobook/META-INF/container.xml
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container"><rootfiles><rootfile full-path="content.opf" media-type="application/oebps-package+xml" /></rootfiles></container>
diff --git a/tests/e2e/fixtures/audiobook/content.opf b/tests/e2e/fixtures/audiobook/content.opf
new file mode 100644
index 0000000..4eeb7e7
--- /dev/null
+++ b/tests/e2e/fixtures/audiobook/content.opf
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="2.0" unique-identifier="book-id">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/"><dc:identifier id="book-id">candle-audiobook-regression</dc:identifier><dc:title>朗读定位回归书</dc:title><dc:language>zh</dc:language></metadata>
+  <manifest><item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" /><item id="one" href="index_split_002.html" media-type="application/xhtml+xml" /><item id="two" href="next.xhtml" media-type="application/xhtml+xml" /></manifest>
+  <spine toc="ncx"><itemref idref="one" /><itemref idref="two" /></spine>
+</package>
diff --git a/tests/e2e/fixtures/audiobook/index_split_002.html b/tests/e2e/fixtures/audiobook/index_split_002.html
new file mode 100644
index 0000000..1484119
--- /dev/null
+++ b/tests/e2e/fixtures/audiobook/index_split_002.html
@@ -0,0 +1 @@
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>朗读定位回归书</title></head><body><p>第一部 小丑</p><p id="filepos138679">第一章 绯红</p><p>好痛！</p><p>头好痛！</p><p>这是固定的朗读定位夹具，保留时间轴使用的章节地址、段落次序和文本。</p></body></html>
diff --git a/tests/e2e/fixtures/audiobook/next.xhtml b/tests/e2e/fixtures/audiobook/next.xhtml
new file mode 100644
index 0000000..51003ec
--- /dev/null
+++ b/tests/e2e/fixtures/audiobook/next.xhtml
@@ -0,0 +1 @@
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>下一章</title></head><body><h1>下一章</h1><p>手动翻页后应暂停朗读跟随，点击返回时回到时间轴中的原始位置。</p></body></html>
diff --git a/tests/e2e/fixtures/audiobook/toc.ncx b/tests/e2e/fixtures/audiobook/toc.ncx
new file mode 100644
index 0000000..86d46e0
--- /dev/null
+++ b/tests/e2e/fixtures/audiobook/toc.ncx
@@ -0,0 +1,2 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1"><head><meta name="dtb:uid" content="candle-audiobook-regression" /></head><docTitle><text>朗读定位回归书</text></docTitle><navMap><navPoint id="one" playOrder="1"><navLabel><text>第一章 绯红</text></navLabel><content src="index_split_002.html" /></navPoint><navPoint id="two" playOrder="2"><navLabel><text>下一章</text></navLabel><content src="next.xhtml" /></navPoint></navMap></ncx>
diff --git a/tests/e2e/fixtures/missing-toc/META-INF/container.xml b/tests/e2e/fixtures/missing-toc/META-INF/container.xml
new file mode 100644
index 0000000..3788cfa
--- /dev/null
+++ b/tests/e2e/fixtures/missing-toc/META-INF/container.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
+  <rootfiles><rootfile full-path="content.opf" media-type="application/oebps-package+xml" /></rootfiles>
+</container>
diff --git a/tests/e2e/fixtures/missing-toc/bare.xhtml b/tests/e2e/fixtures/missing-toc/bare.xhtml
new file mode 100644
index 0000000..422de3d
--- /dev/null
+++ b/tests/e2e/fixtures/missing-toc/bare.xhtml
@@ -0,0 +1 @@
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>缺目录回归书</title></head><body><div id="passage">没有标题和段落标签的正文也可以选择，阅读笔记不能依赖这些标签是否存在。</div></body></html>
diff --git a/tests/e2e/fixtures/missing-toc/chapter.xhtml b/tests/e2e/fixtures/missing-toc/chapter.xhtml
new file mode 100644
index 0000000..b429eeb
--- /dev/null
+++ b/tests/e2e/fixtures/missing-toc/chapter.xhtml
@@ -0,0 +1 @@
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>缺目录回归书</title></head><body><h1>未收录的章节</h1><p id="passage">这段正文没有对应目录项，但是选择的文字和精确位置仍然必须完整保存。</p></body></html>
diff --git a/tests/e2e/fixtures/missing-toc/content.opf b/tests/e2e/fixtures/missing-toc/content.opf
new file mode 100644
index 0000000..7bd89d3
--- /dev/null
+++ b/tests/e2e/fixtures/missing-toc/content.opf
@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<package xmlns="http://www.idpf.org/2007/opf" version="2.0" unique-identifier="book-id">
+  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
+    <dc:identifier id="book-id">tb199-missing-toc</dc:identifier>
+    <dc:title>缺目录回归书</dc:title><dc:language>zh</dc:language>
+  </metadata>
+  <manifest>
+    <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />
+    <item id="cover" href="cover.xhtml" media-type="application/xhtml+xml" />
+    <item id="chapter" href="chapter.xhtml" media-type="application/xhtml+xml" />
+    <item id="bare" href="bare.xhtml" media-type="application/xhtml+xml" />
+  </manifest>
+  <spine toc="ncx"><itemref idref="cover" /><itemref idref="chapter" /><itemref idref="bare" /></spine>
+</package>
diff --git a/tests/e2e/fixtures/missing-toc/cover.xhtml b/tests/e2e/fixtures/missing-toc/cover.xhtml
new file mode 100644
index 0000000..6e7335a
--- /dev/null
+++ b/tests/e2e/fixtures/missing-toc/cover.xhtml
@@ -0,0 +1 @@
+<html xmlns="http://www.w3.org/1999/xhtml"><head><title>缺目录回归书</title></head><body><h1>封面</h1><p>目录故意只收录封面，正文仍在 EPUB spine 中。</p></body></html>
diff --git a/tests/e2e/fixtures/missing-toc/toc.ncx b/tests/e2e/fixtures/missing-toc/toc.ncx
new file mode 100644
index 0000000..51985c0
--- /dev/null
+++ b/tests/e2e/fixtures/missing-toc/toc.ncx
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<ncx xmlns="http://www.daisy.org/z3986/2005/ncx/" version="2005-1">
+  <head><meta name="dtb:uid" content="tb199-missing-toc" /></head>
+  <docTitle><text>缺目录回归书</text></docTitle>
+  <navMap><navPoint id="cover" playOrder="1"><navLabel><text>封面</text></navLabel><content src="cover.xhtml" /></navPoint></navMap>
+</ncx>
diff --git a/tests/e2e/fixtures/mock-host.js b/tests/e2e/fixtures/mock-host.js
new file mode 100644
index 0000000..657068a
--- /dev/null
+++ b/tests/e2e/fixtures/mock-host.js
@@ -0,0 +1,47 @@
+// e2e 用的宿主：在内存版宿主（demo/memory-host.js）上加固定的示例数据，以及记录调用、制造失败、挂起调用的测试开关。
+import { createMemoryHost } from '/demo/memory-host.js'
+
+const ME = { id: 1, nickname: '测试书友', avatar: '' }
+
+// chapter 传 '*' 时示例评论出现在任意章节。
+export function createMockHost({ guest = false, chapter = '*', paragraphCfi = '', extra = 0 } = {}) {
+  const calls = []
+  const failures = {}
+  const delays = {}
+  const host = createMemoryHost({
+    user: guest ? null : ME,
+    async intercept(name, query) {
+      calls.push({ operation: name, query: JSON.parse(JSON.stringify(query || {})) })
+      if (delays[name]) await new Promise(resolve => { delays[name] = resolve })
+      if (failures[name]) throw new Error(failures[name])
+    },
+  })
+  const stamp = minutes => new Date(Date.now() - minutes * 60000).toISOString()
+  const record = (id, author, fields) => host.add({
+    id, client_id: `seed-${id}`, chapter, cfi: paragraphCfi, range_cfi: paragraphCfi, quote_text: '被评论的原文',
+    author_id: author === ME.nickname ? ME.id : id + 5000, author_name: author, created_at: stamp(id), ...fields,
+  })
+  record(1, '林间', { content: '有时我们缺少的不是风景，而是停下来的心情。', like_count: 12, dislike_count: 1 })
+  record(2, ME.nickname, { content: '读到这里想到上周的散步。', like_count: 4 })
+  record(3, ME.nickname, { annotation_type: 'highlight', is_private: true, quote_text: '我的私密划线原文' })
+  record(4, '小舟', { content: '声音把这幅景象连在了一起。', like_count: 2 })
+  record(5, ME.nickname, { content: '这一段适合留给忙碌时的自己。', is_private: true })
+  record(6, '阿遥', { annotation_type: 'book_comment', chapter: '', content: '喜欢这本书安静的节奏。' })
+  record(7, '南风', { chapter: '别的章节', content: '另一章的评论。' })
+  record(901, '小舟', { root_id: 1, content: '同感，停下来本身就是一种风景。', like_count: 3 })
+  record(902, ME.nickname, { root_id: 1, thread_id: 901, reply_to_id: 901, reply_to_name: '小舟', content: '所以这一段我读了两遍。' })
+  record(903, '林间', { root_id: 1, thread_id: 901, reply_to_id: 902, reply_to_name: ME.nickname, content: '哈哈，我也是。', like_count: 1 })
+  record(904, '阿遥', { root_id: 5, content: '忙的时候更需要这样的段落。' })
+  for (let i = 0; i < extra; i++) record(100 + i, `书友${i}`, { content: `第 ${i + 1} 条补充评论` })
+
+  return {
+    callbacks: host.callbacks,
+    calls,
+    records: host.records,
+    setUser(next) { host.setUser(next ? ME : null) },
+    fail(name, message) { if (message) failures[name] = message; else delete failures[name] },
+    // hold(name) 让下一次调用挂起，release(name) 放行。
+    hold(name) { delays[name] = true },
+    release(name) { const resolve = delays[name]; delete delays[name]; if (typeof resolve === 'function') resolve() },
+  }
+}
diff --git a/tests/e2e/fixtures/reader-harness.html b/tests/e2e/fixtures/reader-harness.html
index e260b68..1b1a417 100644
--- a/tests/e2e/fixtures/reader-harness.html
+++ b/tests/e2e/fixtures/reader-harness.html
@@ -2,25 +2,70 @@
 <html lang="zh-CN">
 <head>
   <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
   <title>candle-reader e2e harness</title>
   <!-- 与生产 index.html 一致：JSZip 必须在 epub.js 之前引入（epub.js 靠全局 window.JSZip 解压 .epub） -->
   <script src="/js/jszip-v3.10.1.min.js"></script>
   <script src="/js/epub-v0.3.88.js"></script>
   <script type="module">
     import { Reader } from "/src/main.js"
-    const audiobookEnabled = new URLSearchParams(window.location.search).has('audiobook')
-    // server 指向本地同源，使所有 /api/** 请求都走同源、便于 Playwright route mock；
+    const params = new URLSearchParams(window.location.search)
+    const audiobookEnabled = params.has('audiobook')
+    // ?host=1 注入内存版宿主（完整回调契约）；不带参数时阅读器使用本地存储。
+    let annotationCallbacks = null
+    if (params.has('host')) {
+      const { createMockHost } = await import('./mock-host.js')
+      window.__host = createMockHost({
+        guest: params.has('guest'),
+        chapter: params.get('chapter') || '*',
+        paragraphCfi: params.get('paragraph') || '',
+        extra: Number(params.get('extra')) || 0,
+      })
+      annotationCallbacks = window.__host.callbacks
+      // &locked=1：模拟要求登录才能看评论的宿主（如 Talebook），游客读取列表时以 need_login 拒绝。
+      if (params.has('locked')) {
+        const needLogin = () => Object.assign(new Error('登录后查看评论'), { code: 'need_login' })
+        const guard = name => async (...args) => {
+          if (!(await window.__host.callbacks.user())) throw needLogin()
+          return window.__host.callbacks[name](...args)
+        }
+        annotationCallbacks = { ...annotationCallbacks, list: guard('list'), replies: guard('replies'), login: (...args) => window.__host.callbacks.login(...args) }
+      }
+    }
+    // ?audiobook=1：像真实宿主一样，把有声书回调翻译成对宿主 HTTP 接口的请求（e2e 里由 Playwright 拦截）。
+    const getJson = async (url, options) => {
+      const data = await (await fetch(url, { credentials: 'include', ...options })).json()
+      if (data.err !== 'ok' && data.err !== 'progress.conflict') throw new Error(data.msg || data.err)
+      return data
+    }
+    window.__audiobookCalls = []
+    const audiobookCallbacks = {
+      async manifest(query) { window.__audiobookCalls.push({ operation: 'manifest', query }); return getJson('/api/audiobooks/7/manifest') },
+      async timeline({ manifest_id, chapter }) {
+        return (await getJson(chapter.timeline_url || `/api/audiobooks/${manifest_id}/chapters/${chapter.number}/timeline`)).timeline
+      },
+      async start_session({ manifest_id, source, device_id }) {
+        return getJson(`/api/audiobooks/${manifest_id}/sessions`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ source, device_id }) })
+      },
+      async report_progress({ session_id, book_id, book_url, ...progress }) {
+        window.__audiobookCalls.push({ operation: 'report_progress', query: progress })
+        return getJson(`/api/audiobook-sessions/${session_id}`, { method: 'PATCH', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(progress) })
+      },
+      async end_session({ session_id }) { return getJson(`/api/audiobook-sessions/${session_id}`, { method: 'POST' }) },
+    }
+    // 评论与登录态全部走 annotation_callbacks，阅读器自身不请求任何后端；
     // book_url 用 .epub 压缩包，与生产从 talebook 服务取书一致；JSZip 就位后 headless 下可正常解压渲染。
     new Reader('#app', {
       debug: false,
       themes_css: "/css/themes.css",
-      server: window.location.origin,
-      book_url: "/demo/book1.epub",
-      display_url: "",
+      book_url: params.has('missing_toc') ? '/tests/e2e/fixtures/missing-toc/'
+        : audiobookEnabled ? '/tests/e2e/fixtures/audiobook/'
+        : params.has('book') ? `/demo/${params.get('book')}` : '/demo/book1.epub',
+      // ?book=xi-you-ji.epub&at=…：换用一个正文文件里有多章的书，并从指定位置开始读（跨章页面的用例）。
+      display_url: params.get('at') || "",
       book_id: 101,
-      audiobook_edition_id: audiobookEnabled ? 7 : null,
-      audiobook_manifest_url: audiobookEnabled ? '/api/audiobooks/7/manifest' : '',
+      annotation_callbacks: annotationCallbacks,
+      audiobook_callbacks: audiobookEnabled ? audiobookCallbacks : null,
     })
   </script>
 </head>
diff --git a/tests/e2e/helpers/mock-api.js b/tests/e2e/helpers/mock-api.js
index 2a090bd..928898b 100644
--- a/tests/e2e/helpers/mock-api.js
+++ b/tests/e2e/helpers/mock-api.js
@@ -1,30 +1,8 @@
-// 后端接口 mock。candle-reader 通过 $backend(server + url) 请求 talebook 后端，
-// 这里用 Playwright route 拦截所有 /api/** 请求并返回受控 JSON，
+// 后端接口 mock。用 Playwright route 拦截所有 /api/** 请求并返回受控 JSON，
 // 使 UI 测试不依赖真实服务、结果可复现。
 
-// 默认的“游客（未登录）”后端状态
-const GUEST_RESPONSES = {
-  'GET /api/review/me': { err: 'user.need_login', msg: '请先登录' },
-  'GET /api/user/info': { err: 'need_login', msg: '未登录' },
-  'GET /api/review/book': { err: 'ok', data: { id: 101 } },
-  'GET /api/review/book/list': { err: 'ok', data: { list: [] } },
-  'GET /api/review/summary': { err: 'ok', data: { list: [] } },
-  'GET /api/review/list': { err: 'ok', data: { list: [] } },
-}
-
-// 一个示例已登录用户
-const SAMPLE_USER = {
-  id: 1,
-  nickname: '测试书友',
-  email: 'reader@example.com',
-  avatar: 'mdi-account',
-}
-
-// 示例章评列表
-const SAMPLE_COMMENTS = [
-  { id: 11, content: '这一段写得真好', nickName: '路人甲', avatar: 'mdi-account', level: 1, createTime: '2026-06-01', geo: '北京', likeCount: 5 },
-  { id: 12, content: '深有同感', nickName: '路人乙', avatar: 'mdi-account', level: 2, createTime: '2026-06-02', geo: '上海', likeCount: 2 },
-]
+// 阅读器自身不请求评论或账号接口（这些都经 annotation_callbacks 交给宿主），
+// 这里只需要为有声书等仍走 HTTP 的接口提供受控响应。
 
 /**
  * 安装后端 mock。
@@ -33,7 +11,7 @@ const SAMPLE_COMMENTS = [
  * @returns {{ calls: Array<{method:string,url:string}> }} 记录被调用的接口，便于断言
  */
 async function setupApiMock(page, overrides = {}) {
-  const responses = { ...GUEST_RESPONSES, ...overrides }
+  const responses = { ...overrides }
   const calls = []
 
   await page.route('**/api/**', async (route) => {
@@ -74,4 +52,4 @@ async function setupApiMock(page, overrides = {}) {
   return { calls }
 }
 
-module.exports = { setupApiMock, SAMPLE_USER, SAMPLE_COMMENTS, GUEST_RESPONSES }
+module.exports = { setupApiMock }
diff --git a/tests/e2e/helpers/reader.js b/tests/e2e/helpers/reader.js
index 25f246e..3b6e8cc 100644
--- a/tests/e2e/helpers/reader.js
+++ b/tests/e2e/helpers/reader.js
@@ -34,19 +34,18 @@ async function readState(page, key) {
   }, key)
 }
 
-/**
- * 模拟“选中段落 -> 发段评”的入口：调用 show_selected_comments，
- * 它会写入 comments_location、拉取评论列表并打开评论面板。
- * 相比裸调 set_menu('comments')，这里能让 comments_location 就绪，
- * 从而支持后续“发表评论”用例。
- */
-async function openCommentsPanel(page, toc) {
-  await page.evaluate((t) => {
-    const app = document.querySelector('#app').__vue_app__
-    const epub = app._instance.subTree.component
-    const tocObj = t || { label: '第一章', chapter_id: 7 }
-    epub.proxy.show_selected_comments(tocObj, 3, 'epubcfi(/6/4!/4/2)')
-  }, toc)
+const HOST_URL = `${HARNESS_URL}?host=1`
+
+/** 取 EpubReader 组件实例的句柄，便于在页面内直接调用其方法。 */
+async function readerProxy(page) {
+  return page.evaluateHandle(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy)
+}
+
+/** 打开注入了内存版宿主（tests/e2e/fixtures/mock-host.js）的阅读器，并等到正文与当前章节就绪。 */
+async function gotoHostReader(page, query = '') {
+  await page.goto(`${HOST_URL}${query}`)
+  await waitForReaderRendered(page)
+  await page.waitForFunction(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.current_toc)
 }
 
 /**
@@ -80,4 +79,4 @@ async function readIframeStyle(page, selector, prop) {
   }, { selector, prop })
 }
 
-module.exports = { HARNESS_URL, gotoReader, openPanel, readState, openCommentsPanel, waitForReaderRendered, readIframeStyle }
+module.exports = { HARNESS_URL, HOST_URL, gotoReader, gotoHostReader, openPanel, readState, readerProxy, waitForReaderRendered, readIframeStyle }
diff --git a/tests/e2e/missing-toc.spec.js b/tests/e2e/missing-toc.spec.js
new file mode 100644
index 0000000..a99fda5
--- /dev/null
+++ b/tests/e2e/missing-toc.spec.js
@@ -0,0 +1,86 @@
+const { test, expect } = require('@playwright/test')
+const { setupApiMock } = require('./helpers/mock-api')
+const { HARNESS_URL, openPanel, waitForReaderRendered } = require('./helpers/reader')
+
+test.use({ viewport: { width: 402, height: 874 }, deviceScaleFactor: 3, isMobile: true, hasTouch: true })
+
+for (const [chapter, label] of [['chapter.xhtml', '未收录的章节'], ['bare.xhtml', '正文 3']]) {
+  test(`缺目录 ${chapter} 保存整段评论、刷新和开关后的标记`, async ({ page }) => {
+    const errors = []
+    page.on('pageerror', error => errors.push(error.message))
+    await setupApiMock(page)
+    await page.goto(`${HARNESS_URL}?missing_toc=1`)
+    await waitForReaderRendered(page)
+    await page.evaluate(async chapter => {
+      const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+      await r.rendition.display(chapter)
+    }, chapter)
+    // A rendered comment count must neither execute markup nor change the
+    // fallback chapter label used to save and reload annotations.
+    const comment = await page.evaluate(chapter => {
+      const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+      const contents = r.rendition.getContents().find(c => r.book.spine.get(c.sectionIndex).href === chapter)
+      const element = contents.document.querySelector('h1') || contents.document.getElementById('passage')
+      const cfi = new window.ePub.CFI(element, contents.cfiBase)
+      const toc = r.find_toc(cfi, contents)
+      const count = '<img src=x onerror="window.__injected=true">'
+      r.add_icon_into_paragraph(contents, element, { paragraph_cfi: cfi.toString(), count }, toc)
+      return {
+        text: element.querySelector('.comment-count').textContent,
+        images: element.querySelectorAll('.comment-count img').length,
+        chapter: r.find_toc(cfi, contents).label,
+      }
+    }, chapter)
+    expect(comment).toEqual({ text: '<img src=x onerror="window.__injected=true">', images: 0, chapter: label })
+    const selection = await page.evaluate(chapter => {
+      const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+      const contents = r.rendition.getContents().find(c => r.book.spine.get(c.sectionIndex).href === chapter)
+      const element = contents.document.getElementById('passage')
+      const range = contents.document.createRange()
+      range.setStart(element.firstChild, 2)
+      range.setEnd(element.firstChild, 18)
+      const selection = contents.document.getSelection()
+      selection.removeAllRanges()
+      selection.addRange(range)
+      const paragraphRange = contents.document.createRange()
+      paragraphRange.setStart(element.firstChild, 0)
+      paragraphRange.setEnd(element.firstChild, element.firstChild.length)
+      return { cfi: contents.cfiFromRange(paragraphRange), quote: element.firstChild.textContent }
+    }, chapter)
+    const toolbar = page.locator('#comments-toolbar')
+    await expect(toolbar).toBeVisible()
+    await toolbar.getByRole('button', { name: '写评论' }).click()
+    await page.getByLabel('评论内容').fill('缺目录也能保存真实选区')
+    await page.getByRole('button', { name: '保存', exact: true }).click()
+    await expect(page.getByText('评论已保存')).toBeVisible()
+    const saved = await page.evaluate(() => JSON.parse(localStorage['candle-reader:annotations:v1:101']))
+    expect(saved).toHaveLength(1)
+    expect(saved[0]).toMatchObject({ cfi: selection.cfi, quote_text: selection.quote, chapter: label })
+
+    // 同一段落的两条评论都保留；正文不铺底色，段尾气泡计两条，开关后随之消失与恢复。
+    await page.evaluate(() => {
+      const key = 'candle-reader:annotations:v1:101'
+      const records = JSON.parse(localStorage[key])
+      records.push({ ...records[0], id: 'same-cfi-second-note', client_id: 'same-cfi-second-note', content: '同一选区的第二条笔记' })
+      localStorage[key] = JSON.stringify(records)
+    })
+
+    await page.reload()
+    await waitForReaderRendered(page)
+    await page.evaluate(async cfi => {
+      const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+      await r.rendition.display(cfi)
+    }, selection.cfi)
+    const bubbles = () => page.evaluate(() => Array.from(document.querySelectorAll('#reader iframe')).flatMap(f => Array.from(f.contentDocument.querySelectorAll('.comment-count')).map(item => item.textContent)))
+    await expect.poll(bubbles).toEqual(['2'])
+    await expect(page.locator('.candle-reader-annotation')).toHaveCount(0)
+    await openPanel(page, 'settings')
+    const row = page.locator('[data-setting=show_comments]')
+    await row.getByRole('switch').uncheck()
+    await expect.poll(bubbles).toEqual([])
+    await row.getByRole('switch').check()
+    await expect.poll(bubbles).toEqual(['2'])
+    expect(await page.evaluate(() => JSON.parse(localStorage['candle-reader:annotations:v1:101']).length)).toBe(2)
+    expect(errors).toEqual([])
+  })
+}
diff --git a/tests/e2e/note-settings-layout.spec.js b/tests/e2e/note-settings-layout.spec.js
new file mode 100644
index 0000000..e2a9884
--- /dev/null
+++ b/tests/e2e/note-settings-layout.spec.js
@@ -0,0 +1,46 @@
+const { test, expect } = require('@playwright/test')
+const { setupApiMock } = require('./helpers/mock-api')
+const { gotoReader, openPanel } = require('./helpers/reader')
+
+for (const width of [320, 402]) {
+  test(`开关设置使用左侧完整描述和右侧滑动开关 ${width}px`, async ({ page }) => {
+    await page.setViewportSize({ width, height: 874 })
+    await setupApiMock(page)
+    await gotoReader(page)
+    await openPanel(page, 'settings')
+    const rows = page.locator('[data-setting]')
+    await expect(rows).toHaveCount(3)
+    await expect(rows.getByRole('button')).toHaveCount(0)
+
+    // 在同一帧测量所有行，避免面板入场动画影响相邻行的坐标差。
+    const { reference, geometry } = await rows.evaluateAll(items => {
+      const item = items[0].previousElementSibling
+      const button = item.querySelector('button')
+      const row = item.getBoundingClientRect()
+      const previous = item.previousElementSibling.getBoundingClientRect()
+      const style = getComputedStyle(item)
+      // 窄屏下原有两字标签可能换行；以原有控件高度和行内留白比较单行设置。
+      const height = button.getBoundingClientRect().height + parseFloat(style.paddingTop) + parseFloat(style.paddingBottom)
+      return {
+        reference: { height, bottom: row.bottom, gap: row.top - previous.bottom },
+        geometry: items.map(item => {
+          const row = item.getBoundingClientRect()
+          const label = item.querySelector('label').getBoundingClientRect()
+          const toggle = item.querySelector('.v-selection-control__wrapper').getBoundingClientRect()
+          return { top: row.top, bottom: row.bottom, height: row.height, labelLeft: label.left, labelRight: label.right, switchLeft: toggle.left, switchRight: toggle.right }
+        }),
+      }
+    })
+    let previousBottom = reference.bottom
+    for (const row of geometry) {
+      // 面板入场动画中的坐标带亚像素误差，按 0.01px 精度比较。
+      expect(row.height).toBeCloseTo(reference.height, 2)
+      expect(row.top - previousBottom).toBeCloseTo(reference.gap, 2)
+      previousBottom = row.bottom
+      expect(row.labelLeft).toBe(geometry[0].labelLeft)
+      expect(row.switchRight).toBe(geometry[0].switchRight)
+      expect(row.labelRight).toBeLessThanOrEqual(row.switchLeft)
+      expect(row.switchRight).toBeLessThanOrEqual(width - 8)
+    }
+  })
+}
diff --git a/tests/e2e/note-settings.spec.js b/tests/e2e/note-settings.spec.js
new file mode 100644
index 0000000..adee7a3
--- /dev/null
+++ b/tests/e2e/note-settings.spec.js
@@ -0,0 +1,93 @@
+const { test, expect } = require('@playwright/test')
+const { setupApiMock } = require('./helpers/mock-api')
+const { gotoReader, gotoHostReader, openPanel, readState, waitForReaderRendered } = require('./helpers/reader')
+
+test.use({ viewport: { width: 402, height: 874 }, deviceScaleFactor: 3 })
+
+for (const comments of [true, false]) {
+  for (const toolbar of [true, false]) {
+    test(`旧设置迁移并保存偏好 comments=${comments} annotations=${toolbar}`, async ({ page }) => {
+      await setupApiMock(page)
+      await page.addInitScript(({ comments, toolbar }) => {
+        if (!localStorage.readerSettings) localStorage.readerSettings = JSON.stringify({ show_comments: comments, show_annotations: toolbar })
+      }, { comments, toolbar })
+      await gotoReader(page)
+      await waitForReaderRendered(page)
+      const settings = await readState(page, 'settings')
+      expect(settings).toMatchObject({ show_comments: comments, show_selection_toolbar: toolbar })
+      expect(settings).not.toHaveProperty('notes_enabled')
+      expect(settings).not.toHaveProperty('show_annotations')
+    })
+  }
+}
+
+test('曾关闭旧总开关的读者迁移后两项都关闭，重新打开后不会被旧值压回去', async ({ page }) => {
+  await setupApiMock(page)
+  await page.addInitScript(() => {
+    if (!localStorage.readerSettings) localStorage.readerSettings = JSON.stringify({ notes_enabled: false, show_comments: true, show_selection_toolbar: true })
+  })
+  await gotoReader(page)
+  await waitForReaderRendered(page)
+  expect(await readState(page, 'settings')).toMatchObject({ show_comments: false, show_selection_toolbar: false })
+  await openPanel(page, 'settings')
+  await page.locator('[data-setting=show_comments]').getByRole('switch').check()
+  await page.reload()
+  await waitForReaderRendered(page)
+  expect(await readState(page, 'settings')).toMatchObject({ show_comments: true, show_selection_toolbar: false })
+  expect(await page.evaluate(() => JSON.parse(localStorage.readerSettings))).not.toHaveProperty('notes_enabled')
+})
+
+for (const comments of [true, false]) {
+  for (const toolbar of [true, false]) {
+    test(`开关组合 显示评论=${comments} 工具栏=${toolbar}`, async ({ page }) => {
+      await setupApiMock(page)
+      await page.addInitScript(settings => { localStorage.readerSettings = JSON.stringify(settings) }, {
+        show_comments: comments, show_selection_toolbar: toolbar,
+      })
+      await gotoHostReader(page)
+      await page.evaluate(() => {
+        const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+        r.show_toolbar({ left: 20, top: 100, bottom: 130 }, { x: 0, y: 0 })
+      })
+      await expect(page.locator('#comments-toolbar')).toBeVisible({ visible: toolbar })
+      await expect(page.locator('.v-bottom-navigation button')).toHaveText(['目录', '夜晚', '评论', '设置'])
+      const operations = () => page.evaluate(() => window.__host.calls.map(call => call.operation))
+      // 正文里的划线标记（load）和段尾气泡数量（summary）只在「显示全部划线和评论」开启时读取。
+      if (comments) {
+        await expect.poll(async () => (await operations()).includes('summary')).toBe(true)
+        await expect.poll(async () => (await operations()).includes('load')).toBe(true)
+      } else {
+        expect((await operations()).filter(name => name === 'summary' || name === 'load')).toEqual([])
+      }
+      // 评论入口始终可用。
+      await page.locator('.v-bottom-navigation').getByRole('button', { name: '评论' }).click()
+      await expect(page.locator('.reader-comments-drawer .comment-item')).toHaveCount(3)
+    })
+  }
+}
+
+test('关闭期间迟到的评论数量响应不能恢复段尾气泡', async ({ page }) => {
+  await setupApiMock(page)
+  await gotoHostReader(page)
+  await page.evaluate(() => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    const toc = r.current_toc
+    const contents = r.rendition.getContents().find(c => c.document === toc.elem.ownerDocument)
+    delete toc.load_time
+    const cfi = r.paragraph_location(toc.elem, contents).paragraph_cfi
+    r.annotation_repository.summary = () => new Promise(resolve => { window.finishSummary = () => resolve([{ paragraph_cfi: cfi, count: 9 }]) })
+    window.pendingSummary = r.load_comments_summary(contents, toc)
+    r.update_settings({ ...r.settings, show_comments: false })
+    window.finishSummary()
+  })
+  await page.evaluate(() => window.pendingSummary)
+  const icons = () => page.evaluate(() => Array.from(document.querySelectorAll('#reader iframe')).reduce((n, f) => n + f.contentDocument.querySelectorAll('.comment-icon').length, 0))
+  expect(await icons()).toBe(0)
+  // 重新开启后气泡恢复。
+  await page.evaluate(() => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    r.update_settings({ ...r.settings, show_comments: true })
+    window.finishSummary()
+  })
+  await expect.poll(icons).toBe(1)
+})
diff --git a/tests/e2e/note-switches.spec.js b/tests/e2e/note-switches.spec.js
new file mode 100644
index 0000000..ccc473b
--- /dev/null
+++ b/tests/e2e/note-switches.spec.js
@@ -0,0 +1,34 @@
+const { test, expect } = require('@playwright/test')
+const fs = require('node:fs')
+const path = require('node:path')
+const { setupApiMock } = require('./helpers/mock-api')
+const { gotoReader, openPanel } = require('./helpers/reader')
+test.use({ viewport: { width: 402, height: 874 }, deviceScaleFactor: 3 })
+
+test('滑动开关有完整描述，支持键盘操作，两个评论开关互相独立', async ({ page }) => {
+  await setupApiMock(page)
+  await gotoReader(page)
+  await openPanel(page, 'settings')
+  if (process.env.TB199_EVIDENCE_DIR) {
+    await page.locator('[data-setting=show_selection_toolbar]').scrollIntoViewIfNeeded()
+    const directory = path.resolve(process.env.TB199_EVIDENCE_DIR)
+    fs.mkdirSync(directory, { recursive: true })
+    await page.screenshot({ path: path.join(directory, 'tb199-settings-402x874.png') })
+  }
+  await expect(page.locator('[data-setting]')).toHaveCount(3)
+  for (const name of ['使用鼠标滚轮翻页', '显示全部划线和评论', '选中文字后显示工具栏']) {
+    await expect(page.getByRole('switch', { name, exact: true })).toBeChecked()
+  }
+  const geometry = await page.evaluate(() => ['wheel_paging', 'show_comments', 'show_selection_toolbar'].map(key => document.querySelector(`#setting-${key}`).getBoundingClientRect().x))
+  expect(geometry[1]).toBe(geometry[0])
+  expect(geometry[2]).toBe(geometry[0])
+  // 两个开关互相独立，都可以用键盘或点击文字切换。
+  const comments = page.getByRole('switch', { name: '显示全部划线和评论', exact: true })
+  await comments.focus()
+  await page.keyboard.press('Space')
+  await expect(comments).not.toBeChecked()
+  await expect(page.getByRole('switch', { name: '选中文字后显示工具栏', exact: true })).toBeEnabled()
+  await expect(page.getByRole('switch', { name: '选中文字后显示工具栏', exact: true })).toBeChecked()
+  await page.locator('label[for="switch-show_comments"]').click()
+  await expect(comments).toBeChecked()
+})
diff --git a/tests/e2e/panel-focus.spec.js b/tests/e2e/panel-focus.spec.js
new file mode 100644
index 0000000..a5dc1ec
--- /dev/null
+++ b/tests/e2e/panel-focus.spec.js
@@ -0,0 +1,90 @@
+const { test, expect } = require('@playwright/test')
+const { setupApiMock } = require('./helpers/mock-api')
+const { gotoHostReader } = require('./helpers/reader')
+
+test.use({ viewport: { width: 402, height: 874 }, deviceScaleFactor: 3 })
+
+for (const theme of ['white', 'grey']) {
+  test(`面板最终关闭恢复入口，切换不抢焦 ${theme}`, async ({ page }) => {
+    await setupApiMock(page)
+    await page.addInitScript(theme => localStorage.setItem('readerSettings', JSON.stringify({ theme })), theme)
+    await gotoHostReader(page)
+    const comments = page.locator('.v-bottom-navigation').getByRole('button', { name: '评论' })
+    const settings = page.locator('.v-bottom-navigation').getByRole('button', { name: '设置' })
+    const drawer = page.locator('.reader-comments-drawer')
+    const fullPage = page.getByRole('dialog', { name: '完整评论页' })
+    const detail = page.getByRole('dialog', { name: '评论详情' })
+    async function enter(button) { await button.focus(); await page.keyboard.press('Enter') }
+    // 等焦点进入抽屉后再继续，避免在展开动画的同一帧里按键。
+    async function settled() {
+      await expect(drawer).toBeVisible()
+      await expect.poll(() => page.evaluate(() => !!document.activeElement.closest('.annotation-bottom-sheet'))).toBe(true)
+    }
+    async function open() { await enter(comments); await settled() }
+
+    // Esc 与点击抽屉外区域收起后，焦点回到底部「评论」入口。
+    await open()
+    await page.keyboard.press('Escape')
+    await expect(drawer).toBeHidden()
+    await expect(comments).toBeFocused()
+    await page.keyboard.press('Tab')
+    await expect(settings).toBeFocused()
+    await open()
+    await page.locator('.annotation-bottom-sheet .v-overlay__scrim').click({ position: { x: 10, y: 60 } }) // 顶部栏下方、抽屉上方的外部区域
+    await expect(drawer).toBeHidden()
+    await expect(comments).toBeFocused()
+
+    // 独立页面逐层返回：详情页 → 完整页 → 抽屉，Esc 每次只退一层，最后回到入口。
+    await open()
+    await enter(drawer.getByRole('button', { name: /查看更多评论/ }))
+    await expect(fullPage).toBeVisible()
+    // 等完整页接管焦点后再用键盘操作。
+    await expect.poll(() => page.evaluate(() => !!document.activeElement.closest('.rc-standalone'))).toBe(true)
+    await enter(fullPage.locator('[data-comment="1"]').getByRole('button', { name: '回复 3' }))
+    await expect(detail).toBeVisible()
+    await page.keyboard.press('Escape')
+    await expect(detail).toBeHidden()
+    await expect(fullPage).toBeVisible()
+    await expect(fullPage.locator('[data-comment="1"]').getByRole('button', { name: '回复 3' })).toBeFocused()
+    await page.keyboard.press('Escape')
+    await expect(fullPage).toBeHidden()
+    await expect(drawer).toBeVisible()
+    await expect(drawer.getByRole('button', { name: /查看更多评论/ })).toBeFocused()
+    await page.keyboard.press('Escape')
+    await expect(drawer).toBeHidden()
+    await expect(comments).toBeFocused()
+
+    // 在面板之间切换时，焦点不能被正在离场的面板抢回底部菜单。
+    await open()
+    await page.evaluate(() => {
+      window.panelFocusLog = []
+      document.addEventListener('focusin', e => {
+        if (e.target.closest('.v-bottom-navigation')) window.panelFocusLog.push(e.target.textContent)
+      })
+    })
+    await page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.set_menu('settings'))
+    await expect(page.locator('[data-setting=show_comments]')).toBeVisible()
+    await page.waitForTimeout(500) // include outgoing Vuetify transitions and delayed focus handlers
+    expect(await page.evaluate(() => !!document.activeElement.closest('.v-overlay--active'))).toBe(true)
+    expect(await page.evaluate(() => window.panelFocusLog)).toEqual([])
+    await page.keyboard.press('Escape')
+    await expect(comments).toBeFocused()
+
+    await enter(settings)
+    await expect(page.locator('[data-setting=show_comments]')).toBeVisible()
+    await page.keyboard.press('Escape')
+    await expect(settings).toBeFocused()
+
+    // 由外部触发元素打开时，该元素已不在页面上，回退到底部「评论」入口。
+    await page.evaluate(() => {
+      const trigger = document.createElement('button')
+      document.body.appendChild(trigger)
+      trigger.focus()
+      document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.on_open_annotations()
+      trigger.remove()
+    })
+    await settled()
+    await page.keyboard.press('Escape')
+    await expect(comments).toBeFocused()
+  })
+}
diff --git a/tests/e2e/panel-resize.spec.js b/tests/e2e/panel-resize.spec.js
new file mode 100644
index 0000000..8f58e52
--- /dev/null
+++ b/tests/e2e/panel-resize.spec.js
@@ -0,0 +1,136 @@
+// 宽屏侧边栏（目录、评论、设置）的宽度调整条：拖动、键盘调整、记住宽度；手机底部抽屉不显示。
+const { test, expect } = require('@playwright/test')
+const { setupApiMock } = require('./helpers/mock-api')
+const { gotoHostReader, openPanel } = require('./helpers/reader')
+
+const sheetWidth = page => page.evaluate(() => {
+  const content = [...document.querySelectorAll('.v-bottom-sheet__content')].find(el => el.getBoundingClientRect().width > 0)
+  return Math.round(content.getBoundingClientRect().width)
+})
+
+test.beforeEach(async ({ page }) => {
+  await setupApiMock(page)
+})
+
+test.describe('宽屏', () => {
+  test.use({ viewport: { width: 1280, height: 800 } })
+
+  for (const [panel, label, side, width] of [['toc', '目录', 'left', 300], ['annotations', '评论', 'right', 420], ['settings', '设置', 'right', 380]]) {
+    test(`${label}侧边栏显示胶囊分隔条，拖动调整宽度并记住`, async ({ page }) => {
+      await gotoHostReader(page)
+      await openPanel(page, panel)
+      const resizer = page.getByRole('separator', { name: `调整${label}宽度` })
+      await expect(resizer).toBeVisible()
+      await expect(resizer.locator('.panel-resizer-knob')).toBeVisible()
+      await expect.poll(() => sheetWidth(page)).toBe(width)
+
+      // 拖动：朝外侧拉宽 100px
+      const box = await resizer.boundingBox()
+      const x = box.x + box.width / 2
+      const y = box.y + box.height / 2
+      await page.mouse.move(x, y)
+      await page.mouse.down()
+      await page.mouse.move(x + (side === 'left' ? 50 : -50), y)
+      // 拖动中宽度立即跟上指针，不带过渡动画
+      expect(await sheetWidth(page)).toBe(width + 50)
+      await page.mouse.move(x + (side === 'left' ? 100 : -100), y, { steps: 5 })
+      await page.mouse.up()
+      await expect.poll(() => sheetWidth(page)).toBe(width + 100)
+      await expect(resizer).toHaveAttribute('aria-valuenow', String(width + 100))
+
+      // 键盘：朝正文一侧收窄一步
+      await expect.poll(() => page.evaluate(() => document.activeElement?.classList.contains('v-bottom-sheet__content'))).toBe(true)
+      await resizer.focus()
+      await page.keyboard.press(side === 'left' ? 'ArrowLeft' : 'ArrowRight')
+      await expect.poll(() => sheetWidth(page)).toBe(width + 84)
+
+      // 刷新后沿用上次的宽度
+      await page.reload()
+      await page.waitForFunction(() => document.querySelector('#app')?.__vue_app__?._instance?.subTree?.component?.proxy?.current_toc)
+      await openPanel(page, panel)
+      await expect.poll(() => sheetWidth(page)).toBe(width + 84)
+
+      // 双击恢复默认宽度
+      await page.getByRole('separator', { name: `调整${label}宽度` }).dblclick()
+      await expect.poll(() => sheetWidth(page)).toBe(width)
+    })
+  }
+
+  test('宽度不小于 260px，并给正文至少留 360px；Home 恢复默认', async ({ page }) => {
+    await gotoHostReader(page)
+    await openPanel(page, 'annotations')
+    const resizer = page.getByRole('separator', { name: '调整评论宽度' })
+    // 面板展开动画结束时浮层会把焦点移进面板，等焦点进了面板再聚焦分隔条。
+    await expect.poll(() => page.evaluate(() => document.activeElement?.classList.contains('v-bottom-sheet__content'))).toBe(true)
+    const box = await resizer.boundingBox()
+    const y = box.y + box.height / 2
+    // 拖到最窄、最宽都会被限制住
+    await page.mouse.move(box.x + 4, y)
+    await page.mouse.down()
+    await page.mouse.move(box.x + 600, y, { steps: 5 })
+    await page.mouse.up()
+    await expect.poll(() => sheetWidth(page)).toBe(260)
+    await expect(resizer).toHaveAttribute('aria-valuemin', '260')
+    await expect(resizer).toHaveAttribute('aria-valuemax', '720')
+    const left = await resizer.boundingBox()
+    await page.mouse.move(left.x + 4, y)
+    await page.mouse.down()
+    await page.mouse.move(left.x - 900, y, { steps: 5 })
+    await page.mouse.up()
+    await expect.poll(() => sheetWidth(page)).toBe(720)
+    await resizer.focus()
+    await page.keyboard.press('Home')
+    await expect.poll(() => sheetWidth(page)).toBe(420)
+    await page.setViewportSize({ width: 900, height: 800 })
+    await page.keyboard.press('ArrowLeft')
+    await page.keyboard.press('ArrowLeft')
+    await page.keyboard.press('ArrowLeft')
+    await page.keyboard.press('ArrowLeft')
+    await page.keyboard.press('ArrowLeft')
+    await page.keyboard.press('ArrowLeft')
+    await page.keyboard.press('ArrowLeft')
+    await page.keyboard.press('ArrowLeft')
+    await page.keyboard.press('ArrowLeft')
+    await expect.poll(() => sheetWidth(page)).toBe(540)
+  })
+
+  test('分隔线与面板边界重合，胶囊 8×24，悬停与拖动时变为深蓝', async ({ page }) => {
+    await gotoHostReader(page)
+    for (const [panel, label, side, sheet] of [['toc', '目录', 'left', '.reader-side-left'], ['annotations', '评论', 'right', '.annotation-bottom-sheet'], ['settings', '设置', 'right', '.settings-bottom-sheet']]) {
+      await openPanel(page, panel)
+      const resizer = page.getByRole('separator', { name: `调整${label}宽度` })
+      await expect.poll(() => page.evaluate(() => document.activeElement?.classList.contains('v-bottom-sheet__content'))).toBe(true)
+      const geometry = await resizer.evaluate((el, [side, sheet]) => {
+        const pane = document.querySelector(`${sheet} > .v-bottom-sheet__content`).getBoundingClientRect()
+        const knob = el.querySelector('.panel-resizer-knob').getBoundingClientRect()
+        return {
+          hit: el.getBoundingClientRect().width,
+          line: el.getBoundingClientRect().x + 4,
+          edge: side === 'left' ? pane.x + pane.width : pane.x,
+          knob: [knob.width, knob.height],
+        }
+      }, [side, sheet])
+      expect(geometry.hit).toBe(9)
+      expect(Math.abs(geometry.line - geometry.edge)).toBeLessThan(0.5)
+      expect(geometry.knob).toEqual([8, 24])
+      const colors = () => resizer.evaluate(el => ({
+        line: getComputedStyle(el, '::before').backgroundColor,
+        knob: getComputedStyle(el.querySelector('.panel-resizer-knob')).backgroundColor,
+        grip: getComputedStyle(el.querySelector('.panel-resizer-knob')).color,
+      }))
+      expect((await colors()).knob).not.toBe('rgb(37, 99, 235)')
+      await resizer.hover()
+      await expect.poll(colors).toEqual({ line: 'rgb(37, 99, 235)', knob: 'rgb(37, 99, 235)', grip: 'rgb(255, 255, 255)' })
+      await page.mouse.move(0, 400)
+    }
+  })
+})
+
+test('手机上的底部抽屉没有宽度调整条', async ({ page }) => {
+  await page.setViewportSize({ width: 402, height: 874 })
+  await gotoHostReader(page)
+  for (const panel of ['toc', 'annotations', 'settings']) {
+    await openPanel(page, panel)
+    await expect(page.locator('.panel-resizer')).toHaveCount(0)
+  }
+})
diff --git a/tests/e2e/reader-theme.spec.js b/tests/e2e/reader-theme.spec.js
index 44be304..1f2a8b9 100644
--- a/tests/e2e/reader-theme.spec.js
+++ b/tests/e2e/reader-theme.spec.js
@@ -138,4 +138,113 @@ test.describe('图片皮肤 iframe 渲染回归', () => {
     expect(await readIframeStyle(page, 'html', 'colorScheme')).toBe('normal')
     expect(await readIframeStyle(page, 'body', 'backgroundColor')).toBe('rgb(26, 26, 26)')
   })
+
+  // 回归：夜灰/纯黑的 `.grey *`、`.dark *` 曾给评论数 span 刷上不透明底色，
+  // 绝对定位的 span 盖住气泡上部，段尾气泡只剩尾巴、看不到轮廓。
+  test('段尾评论气泡在各主题下都显示气泡轮廓', async ({ page }) => {
+    await gotoReader(page)
+    await waitForReaderRendered(page)
+    await page.evaluate(() => {
+      const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+      // 可能同时渲染了封面和下一章两个 iframe，取当前可见的那个；本页没有段落（如封面）时在末尾补一段文字再挂。
+      // 气泡不参与排版、垂直居中在末行文字上，直接挂 body 会贴着封面图，取不到纯背景色做对比。
+      const contents = r.rendition.getContents().find(c => {
+        const rect = c.document.defaultView.frameElement.getBoundingClientRect()
+        return rect.right > 0 && rect.left < window.innerWidth
+      })
+      const doc = contents.document
+      const p = [...doc.querySelectorAll('p')].find(p => {
+        const rect = p.getBoundingClientRect()
+        return p.textContent.trim() && rect.left >= 0 && rect.right <= doc.defaultView.innerWidth
+      })
+      let target = p
+      if (!target) {
+        target = doc.createElement('p')
+        target.textContent = '气泡'
+        doc.body.appendChild(target)
+      }
+      r.add_icon_into_paragraph(contents, target, { paragraph_cfi: 'test', count: 7 }, null)
+    })
+    // 读取气泡所在 iframe 的主题 class、气泡样式，以及气泡在主页面中的位置
+    const bubble = () => page.evaluate(() => {
+      for (const f of document.querySelectorAll('#reader iframe')) {
+        const doc = f.contentDocument
+        const icon = doc && doc.querySelector('.comment-icon')
+        if (!icon) continue
+        const r = icon.getBoundingClientRect()
+        const fr = f.getBoundingClientRect()
+        return {
+          themes: [...doc.body.classList],
+          image: getComputedStyle(icon).backgroundImage,
+          countBg: getComputedStyle(icon.querySelector('.comment-count')).backgroundColor,
+          clip: { x: fr.x + r.x, y: fr.y + r.y, width: r.width, height: r.height },
+        }
+      }
+      return null
+    })
+    for (const theme of ['white', 'grey', 'dark', 'xingye']) {
+      await page.evaluate(theme => {
+        const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+        r.update_settings({ ...r.settings, theme })
+      }, theme)
+      await expect.poll(() => bubble().then(b => b && b.themes)).toContain(theme)
+      const b = await bubble()
+      expect(b.image).toContain('data:image/svg+xml')
+      expect(b.countBg).toBe('rgba(0, 0, 0, 0)')
+      // 像素级：气泡顶部一条带（数字画不到的位置）必须有与背景明显不同的轮廓色
+      const png = (await page.screenshot({ clip: b.clip })).toString('base64')
+      const outline = await page.evaluate(async png => {
+        const img = new Image()
+        img.src = `data:image/png;base64,${png}`
+        await img.decode()
+        const canvas = document.createElement('canvas')
+        canvas.width = img.width
+        canvas.height = img.height
+        const ctx = canvas.getContext('2d')
+        ctx.drawImage(img, 0, 0)
+        const data = ctx.getImageData(0, 0, img.width, img.height).data
+        const bg = data.slice(0, 3) // 左上角在气泡圆角之外，取作背景色
+        let count = 0
+        for (let y = 0; y < Math.ceil(img.height * 0.15); y++) {
+          for (let x = 0; x < img.width; x++) {
+            const i = (y * img.width + x) * 4
+            if (Math.max(...[0, 1, 2].map(c => Math.abs(data[i + c] - bg[c]))) > 60) count++
+          }
+        }
+        // 气泡下方的尖角朝左：底部一条带里，左半边的轮廓像素多于右半边
+        const tail = [0, 0]
+        for (let y = Math.floor(img.height * 0.85); y < img.height; y++) {
+          for (let x = 0; x < img.width; x++) {
+            const i = (y * img.width + x) * 4
+            if (Math.max(...[0, 1, 2].map(c => Math.abs(data[i + c] - bg[c]))) > 60) tail[x < img.width / 2 ? 0 : 1]++
+          }
+        }
+        return { count, tail }
+      }, png)
+      expect(outline.count, `${theme} 主题下气泡顶部轮廓不可见`).toBeGreaterThan(0)
+      expect(outline.tail[0], `${theme} 主题下气泡尖角应朝左`).toBeGreaterThan(outline.tail[1])
+    }
+  })
+})
+
+test('开启选中工具栏时正文关闭 iOS 系统文字菜单，关闭工具栏后恢复 @epub', async ({ page }) => {
+  await setupApiMock(page)
+  await gotoReader(page)
+  await waitForReaderRendered(page)
+  // Chromium 不认识 -webkit-touch-callout，样式表里留不下来，所以直接检查注入给正文的样式规则。
+  const callout = () => page.evaluate(() => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    let rules
+    const original = r.rendition.themes.default
+    r.rendition.themes.default = value => { rules = value; return original.call(r.rendition.themes, value) }
+    r.apply_custom_style()
+    r.rendition.themes.default = original
+    return rules['body, body *']['-webkit-touch-callout'] || null
+  })
+  expect(await callout()).toBe('none !important')
+  await page.evaluate(() => {
+    const r = document.querySelector('#app').__vue_app__._instance.subTree.component.proxy
+    r.update_settings({ ...r.settings, show_selection_toolbar: false })
+  })
+  expect(await callout()).toBe(null)
 })
diff --git a/tests/e2e/reader-ui.spec.js b/tests/e2e/reader-ui.spec.js
index 275f636..3c0951f 100644
--- a/tests/e2e/reader-ui.spec.js
+++ b/tests/e2e/reader-ui.spec.js
@@ -2,7 +2,7 @@
 // 这些 UI 是静态模板，不依赖 epub 渲染，因此用例稳定。
 const { test, expect } = require('@playwright/test')
 const { setupApiMock } = require('./helpers/mock-api')
-const { gotoReader, readState, waitForReaderRendered } = require('./helpers/reader')
+const { HARNESS_URL, gotoReader, openPanel, readState, waitForReaderRendered } = require('./helpers/reader')
 
 test.beforeEach(async ({ page }) => {
   await setupApiMock(page) // 默认游客态
@@ -12,8 +12,7 @@ test('页面加载后底部导航栏可见', async ({ page }) => {
   await gotoReader(page)
   await expect(page.getByRole('button', { name: '目录' })).toBeVisible()
   await expect(page.getByRole('button', { name: '设置' })).toBeVisible()
-  await expect(page.getByRole('button', { name: '评论' })).toBeVisible()
-  await expect(page.getByRole('button', { name: 'AI' })).toBeVisible()
+  await expect(page.locator('.v-bottom-navigation button')).toHaveText(['目录', '夜晚', '评论', '设置'])
 })
 
 test('点击「设置」打开设置面板', async ({ page }) => {
@@ -23,9 +22,9 @@ test('点击「设置」打开设置面板', async ({ page }) => {
   await expect(page.getByText('翻页', { exact: true })).toBeVisible()
 })
 
-test('点击「AI」打开开发中占位面板', async ({ page }) => {
+test('顶部更多选项打开开发中占位面板', async ({ page }) => {
   await gotoReader(page)
-  await page.getByRole('button', { name: 'AI', exact: true }).click()
+  await page.getByRole('button', { name: '更多选项', exact: true }).click()
   await expect(page.getByText('开发中')).toBeVisible()
 })
 
@@ -61,11 +60,10 @@ test('设置面板可切换翻页模式 @epub', async ({ page }) => {
 test('设置面板可切换滚轮翻页', async ({ page }) => {
   await gotoReader(page)
   await page.getByRole('button', { name: '设置' }).click()
-  // 「滚轮翻页」行的 关闭 按钮（用 row-scoped 定位避开「章评」同名按钮）
   const wheelRow = page.locator('.v-list-item').filter({ hasText: '滚轮翻页' })
-  await wheelRow.getByRole('button', { name: '关闭' }).click()
+  await wheelRow.getByRole('switch').uncheck()
   await expect.poll(() => readState(page, 'settings').then(s => s.wheel_paging)).toBe(false)
-  await wheelRow.getByRole('button', { name: '开启' }).click()
+  await wheelRow.getByRole('switch').check()
   await expect.poll(() => readState(page, 'settings').then(s => s.wheel_paging)).toBe(true)
 })
 
@@ -77,3 +75,60 @@ test('点击主题按钮在白天/夜晚间切换 @epub', async ({ page }) => {
   await page.getByRole('button', { name: /夜晚|白天/ }).click()
   await expect.poll(() => readState(page, 'settings').then(s => s.theme_mode)).not.toBe(before)
 })
+
+test('左右翻页时拦截阅读区域外框的拖动，正文里不拦（保留 iOS 选区手柄），整页固定 @epub', async ({ page }) => {
+  await gotoReader(page)
+  await waitForReaderRendered(page)
+  const prevented = () => page.evaluate(() => {
+    const drag = target => {
+      const doc = target.ownerDocument
+      const touch = new (doc.defaultView.Touch)({ identifier: 1, target, clientX: 100, clientY: 100 })
+      const event = new (doc.defaultView.TouchEvent)('touchmove', { cancelable: true, bubbles: true, touches: [touch] })
+      return !target.dispatchEvent(event)
+    }
+    const sheet = document.querySelector('.v-overlay--active .v-overlay__content')
+    return {
+      iframe: drag(document.querySelector('#reader iframe').contentDocument.body),
+      main: drag(document.querySelector('#main')),
+      panel: sheet ? drag(sheet) : null,
+    }
+  })
+  expect(await page.evaluate(() => ['position', 'overflow'].map(key => getComputedStyle(document.body)[key]))).toEqual(['fixed', 'hidden'])
+  await page.getByRole('button', { name: '设置' }).click()
+  await expect(page.getByText('亮度')).toBeVisible()
+  expect(await prevented()).toEqual({ iframe: false, main: true, panel: false })
+  await page.getByRole('button', { name: '上下滑动' }).click()
+  await expect.poll(() => readState(page, 'settings').then(settings => settings.flow)).toBe('scrolled')
+  expect(await prevented()).toMatchObject({ iframe: false, main: false })
+})
+
+test('正文加载超过 60 秒提示「加载较慢」但不中断，加载完成后提示自动关闭', async ({ page }) => {
+  let release
+  const held = new Promise(resolve => { release = resolve })
+  await page.route('**/demo/book1.epub', async route => { await held; await route.continue() })
+  await page.clock.install()
+  await gotoReader(page)
+  const dialog = page.getByRole('dialog', { name: '加载较慢' })
+  await page.clock.fastForward(59000)
+  await expect(dialog).toHaveCount(0)
+  await page.clock.fastForward(2000)
+  await expect(dialog).toBeVisible()
+  await expect(dialog.getByRole('button', { name: '继续等待' })).toBeVisible()
+  await page.clock.resume()
+  release()
+  await waitForReaderRendered(page)
+  await expect(dialog).toBeHidden()
+})
+
+test('一个正文文件里有多章时，目录只高亮当前这一章', async ({ page }) => {
+  // 西游记前十一回在同一个正文文件里，目录项只靠锚点区分。
+  await page.goto(HARNESS_URL + '?book=xi-you-ji.epub&at=' + encodeURIComponent('5039418960600707614_23962-0-0.txt.xhtml#chapter-003'))
+  await waitForReaderRendered(page)
+  await page.waitForFunction(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.current_toc)
+  await openPanel(page, 'toc')
+  const current = page.locator('.current-chapter')
+  await expect(current).toHaveCount(1)
+  // 当前章节以页首为准（这一页从第二回末尾开始），与顶部和评论用的章节一致。
+  const label = await page.evaluate(() => document.querySelector('#app').__vue_app__._instance.subTree.component.proxy.current_toc.label)
+  await expect(current).toContainText(label.trim().slice(0, 6))
+})
diff --git a/tests/e2e/user-center.spec.js b/tests/e2e/user-center.spec.js
deleted file mode 100644
index 074ef18..0000000
--- a/tests/e2e/user-center.spec.js
+++ /dev/null
@@ -1,82 +0,0 @@
-// 用户中心：登出、改昵称、未读消息红点。均以“已登录”态启动。
-const { test, expect } = require('@playwright/test')
-const { setupApiMock, SAMPLE_USER } = require('./helpers/mock-api')
-const { gotoReader, readState } = require('./helpers/reader')
-
-// 已登录态：user/info 返回用户，review/me 返回 ok
-function loggedIn(extra = {}) {
-  return {
-    'GET /api/user/info': { err: 'ok', data: SAMPLE_USER },
-    'GET /api/review/me': { err: 'ok', data: { count: 0 } },
-    ...extra,
-  }
-}
-
-test('退出登录：确认后回到游客登录表单', async ({ page }) => {
-  await setupApiMock(page, loggedIn({ 'GET /api/user/sign_out': { err: 'ok' } }))
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByText(SAMPLE_USER.nickname).click()
-  await page.getByText('退出登录').click()
-  // 弹出确认框
-  await expect(page.getByText('是否要退出登录？')).toBeVisible()
-  await page.getByRole('button', { name: '确认' }).click()
-
-  // 登出后 user 置空，用户中心关闭，本书评论面板回到游客态（展示「点击登录」入口）
-  await expect.poll(() => readState(page, 'user')).toBeNull()
-  await expect(page.locator('.book-review-card').getByRole('button', { name: '点击登录，发表评论' })).toBeVisible()
-})
-
-test('退出登录：失败时停留并提示错误', async ({ page }) => {
-  await setupApiMock(page, loggedIn({
-    'GET /api/user/sign_out': { err: 'exception', msg: '服务异常' },
-  }))
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByText(SAMPLE_USER.nickname).click()
-  await page.getByText('退出登录').click()
-  await page.getByRole('button', { name: '确认' }).click()
-
-  await expect(page.getByText('服务异常')).toBeVisible()
-  await expect.poll(() => readState(page, 'user')).not.toBeNull()
-})
-
-test('修改昵称：保存成功后关闭对话框', async ({ page }) => {
-  await setupApiMock(page, loggedIn({
-    'POST /api/user/update': { err: 'ok', data: { ...SAMPLE_USER, nickname: '新昵称' } },
-  }))
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByText(SAMPLE_USER.nickname).click()
-  await page.getByText('昵称').click()
-  await expect(page.getByText('修改昵称')).toBeVisible()
-  await page.getByLabel('新昵称').fill('新昵称')
-  await page.getByRole('button', { name: '保存' }).click()
-  await expect(page.getByText('修改昵称')).toBeHidden()
-})
-
-test('修改昵称：失败时对话框保留并提示', async ({ page }) => {
-  await setupApiMock(page, loggedIn({
-    'POST /api/user/update': { err: 'exception', msg: '昵称已被占用' },
-  }))
-  await gotoReader(page)
-
-  await page.getByRole('button', { name: '评论' }).click()
-  await page.getByText(SAMPLE_USER.nickname).click()
-  await page.getByText('昵称').click()
-  await page.getByLabel('新昵称').fill('重复昵称')
-  await page.getByRole('button', { name: '保存' }).click()
-
-  await expect(page.getByText('昵称已被占用')).toBeVisible()
-  await expect(page.getByText('修改昵称')).toBeVisible()
-})
-
-test('有未读消息时「用户」按钮显示红点角标', async ({ page }) => {
-  await setupApiMock(page, loggedIn({ 'GET /api/review/me': { err: 'ok', data: { count: 3 } } }))
-  await gotoReader(page)
-  await expect.poll(() => readState(page, 'unread_count')).toBe(3)
-  await expect(page.locator('.v-badge__badge').filter({ hasText: '3' })).toBeVisible()
-})