优化翻页

cmd/reader-smoke/main.go

@@ -14,6 +14,7 @@ import (
 	"fmt"
 	"net/http"
 	"os"
+	"path/filepath"
 	"strings"
 	"sync"
 	"time"
@@ -76,7 +77,15 @@ func main() {
 		fatal("未从输入中识别到书源")
 	}
 
-	svc := reader.NewReaderService(&config.Config{}, zap.NewNop(), &repository.Container{})
+	// 书源文件缓存根目录：java.downloadFile / cacheFile 需要它才能落盘，
+	// 否则「拷贝轻小说」这类把整卷文本缓存到本地再读的源会被判为不支持。
+	// 用固定子目录而不是每次 MkdirTemp，避免反复运行在临时目录里留一堆垃圾。
+	cfg := &config.Config{}
+	cacheDir := filepath.Join(os.TempDir(), "reader-smoke-cache")
+	if err := os.MkdirAll(cacheDir, 0o750); err == nil {
+		cfg.Cache.CacheDir = cacheDir
+	}
+	svc := reader.NewReaderService(cfg, zap.NewNop(), &repository.Container{})
 	ctx := context.Background()
 
 	results := make([]*reader.SmokeChainResult, len(sources))

docs/reader-ui-spec.md

@@ -95,6 +95,9 @@
 - 菜单打开时正文整体下移一个顶栏高度（用 `transform`，不改视口高度、不触发重新分页），顶栏不再压住开头 1–2 行。
 - 界面面板的字号/行距/段距三个调节组用 `flex-wrap`，窄屏自动折行，不会把「段距」挤出屏幕。
 - 点击分区：翻页模式渲染一层 `absolute inset-0` 的三分区按钮（左 30% 上一页 / 中 40% 呼出菜单 / 右 30% 下一页）；**滚动模式不能渲染这层覆盖层**——它不是滚动容器的子节点，手机上手指落在覆盖层按钮上时浏览器找不到可滚动的祖先，纵向滑动完全失效、只剩点左右能翻屏。滚动模式改为在滚动容器自身的 `onClick` 上按 x 坐标分区（`handleZoneTap`），手指拖动不会产生 click，原生纵向滚动照常。
+- 手机横向滑动翻页（`hooks/useHorizontalSwipe.ts`）：翻页模式（文本/漫画）在三分区覆盖层上再接一层触摸手势——**从左往右滑=上一页、从右往左滑=下一页**，并且**跟手**：位移超过 12px 且横向明显大于纵向（1.2 倍）之后，内容就跟着手指走，松手再按「位移 ≥45px」决定翻页还是回弹（跟手手势不再看手势时长，慢慢拖过去同样是拖动）。跟手手势一律吞掉随之而来的 click，否则短距离拖动会「回弹 + 再翻一页」；没走跟手的手势仍按原来的「≥45px + 时长 ≤800ms」判定一次滑动，短距离当点击交给分区按钮。`consumeSwipe()` 让三个分区按钮的 `onClick` 先判断这次 click 是否已被手势吃掉，标记在每次 `touchstart` 重置。
+- 跟手拖拽平移的是两个不同的元素。文本：正文列外面单挂一层「跟手层」（`pageDragRef`），分页平移由 `applyTextPageTransform` 命令式写在里层（`contentRef`），跟手层只管手指位移；松手时两层同时动（跟手位移归零 + 页码变化），合起来就是一次连续滑动。正文用 `ReaderTextPageBody` memo，避免长章每次 `setPage` 重渲染整棵段落树（手机会先卡一下再翻页）。漫画：平移 `ReaderComic` 的舞台，舞台左右各摆一页（见下一条）。
+- 漫画单页翻页的跟手轨道与预取（`ReaderComic` 的 `draggable` 分支）：翻页模式且没有并排铺开两页时，当前页左右各摆一页，手指横滑整条舞台跟着走。单元格按图片序号做 key、位置用 `left` 百分比铺开（不是固定三个槽位换内容），所以翻页时变的只是 `left`，`<img>` 的 src 不变，浏览器不会重新解码、也不会先闪一下转圈。松手要翻页时先把新页瞬移到手指离开的位置（这一步必须关掉过渡，否则会先反着滑一段），读一次布局把这一帧定成过渡起点，再打开过渡滑回 0；同时页码 +1/-1，单元格的 `left` 在同一次提交里跟着换，两边相抵，屏幕上看不出切换。**两侧那两页同时就是下一页/上一页的预取**（带 `eager`：它们被 `overflow-hidden` 裁在屏幕外，懒加载会认为「离视口还远」而不去取，横滑过去就会看到转圈）——这正是「手机上翻一页要等一秒、电脑上（双页开着会顺带往后探测 8 张）不卡」的根因。
 - 滚动模式的滚轮（`useSmoothWheelScroll`）：把滚轮格数累加成一个目标位置，再逐帧向它逼近，滚动连续、松手后自己滑行一段，仿手机上下滑动，而不是浏览器整格跳变。只在文本/漫画的上下滚动模式接管；翻页模式仍走下面的翻页监听器。按真实帧间隔换算逼近比例，120Hz 屏上速度不会翻倍；`ctrl/cmd+滚轮` 保留缩放；手指按下（滑动、拖滚动条、点分区）立刻停掉动画把控制权交还用户。
 - 漫画双页铺开（`hooks/useComicSpreads.ts` + `utils/comicSpread.ts`，legado 无对应项，是桌面端补充）：窗口宽度 ≥900px 且漫画处于翻页模式时，一屏并排显示两页（`settings.comicDoublePage` 为设备级偏好，默认开，可在菜单里关；窗口不够宽时自动退回单页）。分组规则同 Tachiyomi 的 dual page——宽度明显大于高度（比值 ≥1.1）的图视为「跨页宽图」独占一屏，其余连续的竖版页两两配对；列表接口只给 URL，尺寸靠 `new Image()` 探测（`<img>` 渲染时顺带回填），只探测当前页往后 8 张的窗口，避免整章预载。进度仍按图片序号记，翻页时换算成「第几屏」，所以关掉再开双页进度不会错位。菜单动作行改为 `flex` 等分，容纳「双页/单页」入口（`grid-cols-N` 得写死列数字面量，多一个按钮无法复用）。
 - 漫画图片显示尺寸（`utils/comicImageFit.ts`，仅上下滚动模式）：legado 的漫画阅读有「缩放」，Web 版原先只有一种写死的宽度（正文列封顶 900px），桌面端放不大也缩不小，所以补上一组档位，在界面面板的「图片尺寸」一行切换。`default` 就是老样子（900px 居中），`width` 适应宽度（正文列不再封顶、铺满窗口），`height` 适应高度（一屏一页），`long` 适应长边（整页完整可见），`original` 原图（原始像素 1:1，超出部分横向滚动）。`default`/`width` 由外层列宽决定，其余三个由 `<img>` 自身约束，**所以后三种必须放开 900px 列宽上限**，否则会被列再压回去。`height`/`long` 要按「一屏多高」换算，所以量的是滚动容器本身而不是 `window.innerHeight`（正文区是 root 里的 `flex-1`，另挂上下条之后就不等于窗口高度了），并用 `ResizeObserver` 跟随；只在启用了自尺寸档位时才挂观察器，默认档位不白白重渲染整章。`settings.comicImageFit` 是设备级偏好（不同屏幕和源分辨率合适的尺寸不同），和 `comicDoublePage` 一样只存本机、不参与账号同步。翻页模式是整页缩放进视口，本来就不存在「太大/太小」，档位对它不生效、也不显示入口。`ctrl/cmd+滚轮` 依然留给浏览器缩放，本功能只用档位做粗调。

internal/helper/http.go

@@ -104,10 +104,19 @@ func NewSiteHTTPClient(timeoutSeconds int, useProxy bool) *http.Client {
 //
 // 交给 net/http 管理后：请求仍会带 `Accept-Encoding: gzip`（浏览器常见取值），
 // 且响应被自动解压；另外也避免服务端挑选我们无法解码的 br。
+// 注意：Accept 刻意用 `*/*` 而不是浏览器页面导航的
+// `text/html,application/xhtml+xml,...`。
+//
+// 很多书源接口是 DRF（Django REST framework）一类会做内容协商的后端：当 Accept
+// 首选 text/html 时，它按浏览器语义返回「可浏览的 HTML 页面」（HTTP 200），
+// 而不是 JSON。引擎再把这份 HTML 交给 JSONPath 解析，结果永远是 0 条——表现为
+// 「同一个源在手机 App 里能搜到，在 MeBox 里搜不到」（拷贝系列源就是这个坑）。
+// 手机端阅读 App 走 OkHttp，不显式设置 Accept，等价于 `*/*`；这里对齐该行为。
+// 需要页面型 Accept 的书源可以在自身 header 里显式声明覆盖。
 func HTTPHeaderPresets() map[string]string {
 	return map[string]string{
 		"User-Agent":                defaultUserAgent,
-		"Accept":                    "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7",
+		"Accept":                    "*/*",
 		"Accept-Language":           "zh-CN,zh;q=0.9,en;q=0.8",
 		"Connection":                "keep-alive",
 		"Upgrade-Insecure-Requests": "1",

internal/helper/http_test.go

@@ -12,6 +12,18 @@ import (
 // 背景：预设头里曾显式写 `Accept-Encoding: gzip, deflate, br`，导致 net/http
 // 不再自动解压（它只在调用方没设置该头时才解压），压缩字节直接进入规则层。
 
+// TestHeaderPresetsAcceptIsWildcard 预设 Accept 不得首选 text/html。
+//
+// 背景：DRF（Django REST framework）等会做内容协商的后端，在 Accept 首选
+// text/html 时返回「可浏览 HTML 页面」而不是 JSON，书源 JSONPath 因此永远
+// 解析出 0 条（拷贝轻小说源在 MeBox 搜不到、在阅读 App 能搜到的根因）。
+func TestHeaderPresetsAcceptIsWildcard(t *testing.T) {
+	got := HTTPHeaderPresets()["Accept"]
+	if got != "*/*" {
+		t.Fatalf("Accept 预设应为 */*（对齐 legado/OkHttp），实际 %q", got)
+	}
+}
+
 // TestHeaderPresetsDoNotSetAcceptEncoding 预设头不得设置 Accept-Encoding。
 // 一旦设置，net/http 的透明解压就失效，压缩响应会以原始字节交给上层。
 func TestHeaderPresetsDoNotSetAcceptEncoding(t *testing.T) {

internal/service/reader/reader.go

@@ -13,6 +13,7 @@ import (
 	"io"
 	"net/http"
 	"net/url"
+	"path/filepath"
 	"regexp"
 	"sort"
 	"strings"
@@ -404,6 +405,12 @@ func (s *ReaderService) executeWithState(ctx context.Context, req *rule.Request,
 		break
 	}
 	data = helper.DecompressBody(resp, data)
+	// Raw：按原始字节返回（书源文件落盘用），不做 charset 解码。
+	// 必须先于 HexBody 判断之外处理：GBK 文本一旦按 UTF-8 解码就变成 U+FFFD，
+	// 落盘的文件会坏掉。
+	if req.Raw {
+		return string(data), resp.Request.URL.String(), resp.StatusCode, nil
+	}
 	// 声明了 type 的请求按「原始字节的 hex」返回（对应 legado AnalyzeUrl.type），
 	// 不做 charset 解码——书源会自己 hexDecodeToString 取回内容。
 	if req.HexBody {
@@ -641,9 +648,28 @@ func (sess *sourceSession) runner(key string, page int) *rule.JSRunner {
 		JSLib:   SPtr(sess.bs.JSLib),
 		Ctx:     sess.ctx,
 		Browser: host,
+		// 书源文件缓存根目录：java.downloadFile / cacheFile 落盘用。
+		CacheDir: sess.svc.readerFileCacheDir(),
 	})
 }
 
+// readerFileCacheDir 书源文件缓存根目录（java.downloadFile / cacheFile）。
+// 优先用配置的 cache_dir，退回 data_dir/cache；都不可用时返回空串，
+// 此时文件类 JS 接口会抛出「未配置缓存目录」而不是写到进程当前目录。
+func (s *ReaderService) readerFileCacheDir() string {
+	if s == nil || s.cfg == nil {
+		return ""
+	}
+	if base := strings.TrimSpace(s.cfg.Cache.CacheDir); base != "" {
+		return base
+	}
+	if dataDir := strings.TrimSpace(s.cfg.App.DataDir); dataDir != "" {
+		return filepath.Join(dataDir, "cache")
+	}
+	return ""
+}
+
+
 // srcID 书源记录 ID（登录界面待办按书源隔离）。
 func (sess *sourceSession) srcID() string {
 	if sess.src != nil {

internal/service/reader/reader_copy_source_test.go

@@ -0,0 +1,121 @@
+package reader
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"golang.org/x/text/encoding/simplifiedchinese"
+)
+
+// 本文件：拷贝系列轻小说源的端到端回归。
+//
+// 合成一个「照搬拷贝轻小说写法」的书源，一次覆盖四个修复点：
+//  1. 搜索列表规则 `results.list.[*]`（legado 的 `.[*]` 形式）；
+//  2. 目录规则用 `new Packages.java.util.LinkedHashMap()/ArrayList()` 拼装；
+//  3. 正文规则用 `java.cacheFile(url)` 取整卷文本；
+//  4. 正文是 GBK 文本——必须走 Raw 原始字节通道落盘，否则会被 UTF-8 解码成乱码。
+
+func TestCopyLightNovelSourceEndToEnd(t *testing.T) {
+	var srv *httptest.Server
+	gbkBody, err := simplifiedchinese.GBK.NewEncoder().Bytes([]byte("第一章 开始\n第二章 继续"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	mux := http.NewServeMux()
+	// 搜索：Django REST 风格的 JSON。q_type/_update 参数照抄真实源。
+	mux.HandleFunc("/api/search", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"code":200,"results":{"list":[
+			{"name":"转生成为史莱姆","path_word":"slime","author":[{"name":"作者甲"}],"cover":"https://img.example.com/1.jpg"}
+		]}}`))
+	})
+	mux.HandleFunc("/api/book/", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"code":200,"results":{"book":{"name":"转生成为史莱姆","path_word":"slime"}}}`))
+	})
+	mux.HandleFunc("/api/volumes", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"code":200,"results":{"list":[{"name":"第一卷","id":7}]}}`))
+	})
+	mux.HandleFunc("/api/volume/", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = fmt.Fprintf(w, `{"code":200,"results":{"volume":{"txt_addr":"%s/api/txt/7","txt_encoding":"GBK"}}}`, srv.URL)
+	})
+	mux.HandleFunc("/api/txt/", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/plain")
+		_, _ = w.Write(gbkBody)
+	})
+	srv = httptest.NewServer(mux)
+	defer srv.Close()
+
+	source := map[string]any{
+		"bookSourceName": "合成拷贝轻小说源",
+		"bookSourceUrl":  srv.URL,
+		"enabled":        true,
+		"enabledExplore": true,
+		"searchUrl":      srv.URL + "/api/search?limit=20&q_type=&q={{key}}&_update=true",
+		"ruleSearch": map[string]any{
+			"bookList": "results.list.[*]",
+			"name":     "$.name",
+			"author":   "$.author[*].name",
+			"coverUrl": "$.cover",
+			"bookUrl":  srv.URL + "/api/book/{{$.path_word}}?_update=true",
+		},
+		"ruleBookInfo": map[string]any{
+			"init":  "$.results.book",
+			"name":  "$.name",
+			"intro": "$.brief",
+			"tocUrl": srv.URL + "/api/volumes?book={{$.path_word}}&_update=true",
+		},
+		"ruleToc": map[string]any{
+			"chapterList": `<js>
+function mk(n, u) { var m = new Packages.java.util.LinkedHashMap(); m.put('name', n); m.put('url', u); return m; }
+var base = '` + srv.URL + `/api/volume/';
+var out = new Packages.java.util.ArrayList();
+var vols = JSON.parse(result).results.list;
+for (var i = 0; i < vols.length; i++) { out.add(mk(vols[i].name, base + vols[i].id + '?_update=true')); }
+out;</js>`,
+			"chapterName": "$.name",
+			"chapterUrl":  "$.url",
+		},
+		"ruleContent": map[string]any{
+			"content": `@js:java.cacheFile(java.getString('$..txt_addr'))`,
+		},
+	}
+	raw, err := json.Marshal(source)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	svc, _ := newLoginTestService(t)
+	svc.cfg.Cache.CacheDir = t.TempDir()
+
+	res := svc.SmokeSource(t.Context(), string(raw), "史莱姆")
+	if !res.OK {
+		t.Fatalf("链路失败于 %s: %s\n%s", res.FailedAt, res.Error, joinLogs(res))
+	}
+	if res.SearchHits != 1 {
+		t.Fatalf("搜索命中=%d, want 1（`.[*]` 路径修复）", res.SearchHits)
+	}
+	if res.Chapters != 1 {
+		t.Fatalf("章节数=%d, want 1（Packages 修复）", res.Chapters)
+	}
+	if res.ContentLen == 0 {
+		t.Fatalf("正文长度=0（cacheFile/Raw 修复未生效）\n%s", joinLogs(res))
+	}
+	if !strings.Contains(joinLogs(res), "第一章") {
+		t.Fatalf("正文未正确解码（GBK 落盘被 utf-8 破坏）\n%s", joinLogs(res))
+	}
+}
+
+func joinLogs(res *SmokeChainResult) string {
+	var b strings.Builder
+	for _, l := range res.Logs {
+		fmt.Fprintf(&b, "[%s/%s] %s\n", l.Stage, l.Level, l.Message)
+	}
+	return b.String()
+}

internal/service/reader/rule/bridge.go

@@ -10,6 +10,8 @@ import (
 	"encoding/hex"
 	"fmt"
 	"hash"
+	"os"
+	"path/filepath"
 	"strings"
 
 	"github.com/dop251/goja"
@@ -435,6 +437,95 @@ func newJavaObject(vm *goja.Runtime, r *JSRunner, a *AnalyzeRule) *goja.Object {
 		return goja.Null()
 	})
 
+	// ── 本地文件（对应 legado JsExtensions 的缓存/文件系列） ──
+	//
+	// 服务端把文件限制在自己的缓存目录（<cache>/reader/files）内，
+	// 书源只能用相对路径（允许以 / 开头，downloadFile 的返回值即此形态）。
+	set("downloadFile", func(call goja.FunctionCall) goja.Value {
+		// 旧签名 downloadFile(contentHex, url)：把 hex 字符串落成文件。
+		if len(call.Arguments) >= 2 && !goja.IsUndefined(call.Arguments[1]) && !goja.IsNull(call.Arguments[1]) {
+			url := stringArg(call, 1)
+			raw, err := hex.DecodeString(strings.TrimSpace(stringArg(call, 0)))
+			if err != nil {
+				bridgeErr("downloadFile", err)
+			}
+			rel, err := writeCacheFile(r.cfg.CacheDir, cacheFileName(url), raw)
+			if err != nil {
+				bridgeErr("downloadFile", err)
+			}
+			return vm.ToValue(rel)
+		}
+		rel, err := downloadToCache(r, stringArg(call, 0))
+		if err != nil {
+			bridgeErr("downloadFile", err)
+		}
+		return vm.ToValue(rel)
+	})
+	// cacheFile(url): 下载并缓存文本文件，返回文件**内容**（对应 legado 语义）。
+	set("cacheFile", func(call goja.FunctionCall) goja.Value {
+		url := stringArg(call, 0)
+		if dir := readerFilesDir(r.cfg.CacheDir); dir != "" {
+			if b, err := os.ReadFile(filepath.Join(dir, cacheFileName(url))); err == nil && len(b) > 0 {
+				return vm.ToValue(decodeTextAuto(b))
+			}
+		}
+		rel, err := downloadToCache(r, url)
+		if err != nil {
+			bridgeErr("cacheFile", err)
+		}
+		full, err := resolveCacheFilePath(r.cfg.CacheDir, rel)
+		if err != nil {
+			bridgeErr("cacheFile", err)
+		}
+		b, err := os.ReadFile(full)
+		if err != nil {
+			bridgeErr("cacheFile", err)
+		}
+		return vm.ToValue(decodeTextAuto(b))
+	})
+	set("readFile", func(call goja.FunctionCall) goja.Value {
+		full, err := resolveCacheFilePath(r.cfg.CacheDir, stringArg(call, 0))
+		if err != nil {
+			return goja.Null()
+		}
+		b, err := os.ReadFile(full)
+		if err != nil {
+			return goja.Null()
+		}
+		return vm.ToValue(vm.NewArrayBuffer(b))
+	})
+	set("readTxtFile", func(call goja.FunctionCall) goja.Value {
+		full, err := resolveCacheFilePath(r.cfg.CacheDir, stringArg(call, 0))
+		if err != nil {
+			return vm.ToValue("")
+		}
+		b, err := os.ReadFile(full)
+		if err != nil {
+			return vm.ToValue("")
+		}
+		if cs := stringArgOr(call, 1, ""); cs != "" {
+			if s, derr := DecodeBytes(b, cs); derr == nil {
+				return vm.ToValue(s)
+			}
+		}
+		return vm.ToValue(decodeTextAuto(b))
+	})
+	set("deleteFile", func(call goja.FunctionCall) goja.Value {
+		full, err := resolveCacheFilePath(r.cfg.CacheDir, stringArg(call, 0))
+		if err != nil {
+			return vm.ToValue(false)
+		}
+		return vm.ToValue(os.Remove(full) == nil)
+	})
+	// getFile(path): 返回 File 对象（提供书源常用的 exists/length/name/delete/readText）。
+	set("getFile", func(call goja.FunctionCall) goja.Value {
+		full, err := resolveCacheFilePath(r.cfg.CacheDir, stringArg(call, 0))
+		if err != nil {
+			full = ""
+		}
+		return newFileObject(vm, full, stringArg(call, 0))
+	})
+
 	// ── 书源会话状态（legado 中 `java` 与 `source` 是同一对象） ──
 	if r.state != nil {
 		bindSourceState(vm, set, r.state, r.cfg.SourceProps)
@@ -540,13 +631,15 @@ func newJavaObject(vm *goja.Runtime, r *JSRunner, a *AnalyzeRule) *goja.Object {
 		set(name, unsupported(name, "需要无头浏览器（WebView）"))
 	}
 	for _, name := range []string{
-		"importScript", "cacheFile", "downloadFile", "readFile", "readTxtFile", "deleteFile",
 		"unzipFile", "un7zFile", "unrarFile", "unArchiveFile", "getTxtInFolder",
 		"getZipStringContent", "getZipByteArrayContent",
 		"getRarStringContent", "get7zStringContent",
 	} {
-		set(name, unsupported(name, "需要本地文件/压缩包能力"))
+		set(name, unsupported(name, "需要压缩包解压能力"))
 	}
+	// importScript 在 legado 里是「下载 JS 文件并 eval」，服务端可做但会引入
+	// 任意脚本执行面，暂不支持，保持明确报错。
+	set("importScript", unsupported("importScript", "服务端不支持动态加载外部脚本"))
 
 	return o
 }

internal/service/reader/rule/bridge_files.go

@@ -0,0 +1,209 @@
+package rule
+
+import (
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/dop251/goja"
+)
+
+// 本文件实现 legado JsExtensions 里的「本地文件」能力
+// （cacheFile / downloadFile / readFile / readTxtFile / deleteFile / getFile）。
+//
+// 与 legado 的语义保持一致：
+//   - downloadFile(url) 下载到缓存目录，返回「相对缓存根目录」的路径；
+//   - cacheFile(url) 下载（带缓存）后返回文件的**文本内容**（不是路径）；
+//   - readFile/readTxtFile/deleteFile/getFile 接受相对路径（允许以 / 开头），
+//     一律解析到缓存目录下。
+//
+// 服务端把缓存根目录固定为 <cache>/reader/files，并且只允许访问该目录内的文件，
+// 避免书源通过 `../../` 之类读到宿主上的任意文件。
+
+// filesSubdir 书源文件缓存目录（相对 ReaderService 的缓存根目录）。
+const filesSubdir = "reader/files"
+
+// readerFilesDir 返回书源文件缓存目录；未配置缓存目录时返回空串。
+func readerFilesDir(cacheDir string) string {
+	if strings.TrimSpace(cacheDir) == "" {
+		return ""
+	}
+	return filepath.Join(cacheDir, "reader", "files")
+}
+
+// cacheFileName 计算某个 URL 在缓存目录里的文件名（对应 legado 的
+// `${md5Encode16(url)}.${type}`：md5 十六进制取中间 16 位，保留 URL 后缀）。
+func cacheFileName(rawURL string) string {
+	name := md5Hex(rawURL, true)
+	if ext := urlFileSuffix(rawURL); ext != "" {
+		name += "." + ext
+	}
+	return name
+}
+
+// urlFileSuffix 取 URL 路径部分的后缀（不含 `.`），只接受字母数字（长度 1~8）。
+func urlFileSuffix(rawURL string) string {
+	u := rawURL
+	if i := strings.IndexAny(u, "?#"); i >= 0 {
+		u = u[:i]
+	}
+	if i := strings.LastIndex(u, "/"); i >= 0 {
+		u = u[i+1:]
+	}
+	dot := strings.LastIndex(u, ".")
+	if dot < 0 || dot == len(u)-1 {
+		return ""
+	}
+	ext := u[dot+1:]
+	if len(ext) > 8 {
+		return ""
+	}
+	for i := 0; i < len(ext); i++ {
+		c := ext[i]
+		if !(c >= 'a' && c <= 'z' || c >= 'A' && c <= 'Z' || c >= '0' && c <= '9') {
+			return ""
+		}
+	}
+	return strings.ToLower(ext)
+}
+
+// resolveCacheFilePath 把书源给的相对路径解析成缓存目录下的绝对路径。
+// 允许以 `/` 开头（downloadFile 的返回值就是这种形态），但拒绝越出缓存目录。
+func resolveCacheFilePath(cacheDir, p string) (string, error) {
+	dir := readerFilesDir(cacheDir)
+	if dir == "" {
+		return "", fmt.Errorf("未配置缓存目录")
+	}
+	p = strings.TrimSpace(p)
+	if p == "" {
+		return "", fmt.Errorf("文件路径为空")
+	}
+	rel := filepath.Clean(filepath.FromSlash(strings.Trim(p, `/\`)))
+	if rel == "." || rel == ".." || strings.HasPrefix(rel, ".."+string(os.PathSeparator)) {
+		return "", fmt.Errorf("非法文件路径: %s", p)
+	}
+	return filepath.Join(dir, rel), nil
+}
+
+// writeCacheFile 把字节写入缓存目录，返回相对路径（以 / 开头，对应 legado）。
+func writeCacheFile(cacheDir, name string, data []byte) (string, error) {
+	dir := readerFilesDir(cacheDir)
+	if dir == "" {
+		return "", fmt.Errorf("未配置缓存目录")
+	}
+	if err := os.MkdirAll(dir, 0o750); err != nil {
+		return "", err
+	}
+	if err := os.WriteFile(filepath.Join(dir, name), data, 0o600); err != nil {
+		return "", err
+	}
+	return "/" + name, nil
+}
+
+// downloadToCache 下载 URL 并落到缓存目录（已存在则直接复用），
+// 返回相对缓存根目录的路径。下载走书源会话，因此会带上书源请求头与 Cookie。
+func downloadToCache(r *JSRunner, rawURL string) (string, error) {
+	dir := readerFilesDir(r.cfg.CacheDir)
+	if dir == "" {
+		return "", fmt.Errorf("未配置缓存目录")
+	}
+	name := cacheFileName(rawURL)
+	full := filepath.Join(dir, name)
+	if st, err := os.Stat(full); err == nil && st.Size() > 0 {
+		return "/" + name, nil
+	}
+	req, err := ParseAnalyzeUrlWithJS(rawURL, "", 0, r.cfg.BaseURL, r)
+	if err != nil {
+		return "", err
+	}
+	if req.Unsupported != nil {
+		return "", req.Unsupported
+	}
+	// Raw：响应按原始字节返回，避免 charset 解码破坏二进制/非 UTF-8 文本。
+	// 同时清掉 HexBody：URL 选项里的 `type` 在 legado 是文件后缀提示，
+	// 这里不该把下载内容按 hex 字符串落盘。
+	req.Raw = true
+	req.HexBody = false
+	body, _, code, err := r.fetch(req)
+	if err != nil {
+		return "", err
+	}
+	if code >= 400 {
+		return "", fmt.Errorf("下载失败 HTTP %d: %s", code, rawURL)
+	}
+	return writeCacheFile(r.cfg.CacheDir, name, []byte(body))
+}
+
+// decodeTextAuto 解码文本文件：UTF-8 BOM → 去 BOM；合法 UTF-8 → 原样；
+// 否则按 GBK 解（中文站点/书源最常见的另一种编码），失败再原样返回。
+func decodeTextAuto(b []byte) string {
+	if len(b) >= 3 && b[0] == 0xEF && b[1] == 0xBB && b[2] == 0xBF {
+		return string(b[3:])
+	}
+	if utf8.Valid(b) {
+		return string(b)
+	}
+	if s, err := DecodeBytes(b, "gbk"); err == nil && s != "" {
+		return s
+	}
+	return string(b)
+}
+
+// fileSuffixFromName 取路径的最后一段（getFile 的 name 语义）。
+func fileSuffixFromName(p string) string {
+	return path.Base(strings.ReplaceAll(p, "\\", "/"))
+}
+
+// newFileObject 构造 `java.getFile(path)` 返回的 File 等价物，
+// 提供书源常用的 exists / length / name / delete / readText。
+func newFileObject(vm *goja.Runtime, full, raw string) *goja.Object {
+	o := vm.NewObject()
+	set := func(k string, v any) { _ = o.Set(k, v) }
+	set("path", full)
+	set("name", fileSuffixFromName(raw))
+	set("exists", func(goja.FunctionCall) goja.Value {
+		if full == "" {
+			return vm.ToValue(false)
+		}
+		_, err := os.Stat(full)
+		return vm.ToValue(err == nil)
+	})
+	set("isDirectory", func(goja.FunctionCall) goja.Value {
+		if full == "" {
+			return vm.ToValue(false)
+		}
+		st, err := os.Stat(full)
+		return vm.ToValue(err == nil && st.IsDir())
+	})
+	set("length", func(goja.FunctionCall) goja.Value {
+		if full == "" {
+			return vm.ToValue(0)
+		}
+		st, err := os.Stat(full)
+		if err != nil {
+			return vm.ToValue(0)
+		}
+		return vm.ToValue(st.Size())
+	})
+	set("delete", func(goja.FunctionCall) goja.Value {
+		if full == "" {
+			return vm.ToValue(false)
+		}
+		return vm.ToValue(os.Remove(full) == nil)
+	})
+	set("readText", func(goja.FunctionCall) goja.Value {
+		if full == "" {
+			return vm.ToValue("")
+		}
+		b, err := os.ReadFile(full)
+		if err != nil {
+			return vm.ToValue("")
+		}
+		return vm.ToValue(decodeTextAuto(b))
+	})
+	set("toString", func(goja.FunctionCall) goja.Value { return vm.ToValue(full) })
+	return o
+}

internal/service/reader/rule/files_test.go

@@ -0,0 +1,152 @@
+package rule
+
+import (
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync/atomic"
+	"testing"
+
+	"golang.org/x/text/encoding/simplifiedchinese"
+)
+
+// 本文件：java 文件接口（cacheFile / downloadFile / readTxtFile / deleteFile）
+// 的语义回归。对应 legado JsExtensions：
+//   - cacheFile(url) → 返回文件**文本内容**（不是路径）；
+//   - downloadFile(url) → 返回相对缓存根目录的路径；
+//   - readTxtFile(path[, charset]) → 返回文本；
+//   - 只允许访问缓存目录内的文件。
+
+func newFileTestRunner(cacheDir, baseURL string, hits *int32) *JSRunner {
+	return NewJSRunner(JSConfig{
+		CacheDir: cacheDir,
+		BaseURL:  baseURL,
+		Fetch: func(req *Request) (string, string, int, error) {
+			if hits != nil {
+				atomic.AddInt32(hits, 1)
+			}
+			resp, err := http.Get(req.URL) //nolint:gosec // 测试内固定 httptest 地址
+			if err != nil {
+				return "", "", 0, err
+			}
+			defer resp.Body.Close()
+			b, _ := io.ReadAll(resp.Body)
+			return string(b), req.URL, resp.StatusCode, nil
+		},
+	})
+}
+
+func TestCacheFileReturnsTextContent(t *testing.T) {
+	var hits int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte("第一章 开始\n第二章 继续"))
+	}))
+	defer srv.Close()
+
+	r := newFileTestRunner(t.TempDir(), srv.URL, &hits)
+	ar := NewAnalyzeRule()
+	v, err := r.Run(ar, "java.cacheFile('"+srv.URL+"/vol.txt')", nil, "")
+	if err != nil {
+		t.Fatalf("cacheFile 失败: %v", err)
+	}
+	if got := anyToString(v); got != "第一章 开始\n第二章 继续" {
+		t.Fatalf("cacheFile 应返回文本内容，实际 %q", got)
+	}
+	// 第二次应命中缓存，不再发起请求。
+	if _, err := r.Run(ar, "java.cacheFile('"+srv.URL+"/vol.txt')", nil, ""); err != nil {
+		t.Fatal(err)
+	}
+	if n := atomic.LoadInt32(&hits); n != 1 {
+		t.Fatalf("重复调用应命中缓存（请求次数=%d）", n)
+	}
+}
+
+func TestCacheFileDecodesGBK(t *testing.T) {
+	gbk, err := simplifiedchinese.GBK.NewEncoder().Bytes([]byte("中文内容测试"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write(gbk)
+	}))
+	defer srv.Close()
+
+	r := newFileTestRunner(t.TempDir(), srv.URL, nil)
+	v, err := r.Run(NewAnalyzeRule(), "java.cacheFile('"+srv.URL+"/gbk.txt')", nil, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := anyToString(v); got != "中文内容测试" {
+		t.Fatalf("GBK 文本未正确解码: %q", got)
+	}
+}
+
+func TestDownloadFileThenReadTxtFile(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_, _ = w.Write([]byte("正文内容"))
+	}))
+	defer srv.Close()
+
+	cacheDir := t.TempDir()
+	r := newFileTestRunner(cacheDir, srv.URL, nil)
+	ar := NewAnalyzeRule()
+
+	rawPath, err := r.Run(ar, "java.downloadFile('"+srv.URL+"/a.txt')", nil, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	rel := anyToString(rawPath)
+	if !strings.HasPrefix(rel, "/") || !strings.HasSuffix(rel, ".txt") {
+		t.Fatalf("downloadFile 应返回相对缓存路径，实际 %q", rel)
+	}
+	if _, err := os.Stat(filepath.Join(cacheDir, "reader", "files", strings.TrimPrefix(rel, "/"))); err != nil {
+		t.Fatalf("文件未落到缓存目录: %v", err)
+	}
+
+	v, err := r.Run(ar, "java.readTxtFile('"+rel+"')", nil, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := anyToString(v); got != "正文内容" {
+		t.Fatalf("readTxtFile = %q", got)
+	}
+
+	del, err := r.Run(ar, "String(java.deleteFile('"+rel+"'))", nil, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if anyToString(del) != "true" {
+		t.Fatalf("deleteFile 应返回 true，实际 %q", anyToString(del))
+	}
+}
+
+func TestFileOpsRejectPathTraversal(t *testing.T) {
+	cacheDir := t.TempDir()
+	secret := filepath.Join(cacheDir, "secret.txt")
+	if err := os.WriteFile(secret, []byte("不该被读到"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	r := newFileTestRunner(cacheDir, "", nil)
+	ar := NewAnalyzeRule()
+
+	for _, p := range []string{"/../../secret.txt", "../secret.txt", "/../reader/files/../../secret.txt"} {
+		v, err := r.Run(ar, "java.readTxtFile('"+p+"')", nil, "")
+		if err != nil {
+			t.Fatalf("%s 不应报错: %v", p, err)
+		}
+		if got := anyToString(v); strings.Contains(got, "不该被读到") {
+			t.Fatalf("越权读到了缓存目录外的文件（%s）", p)
+		}
+	}
+}
+
+func TestFileOpsWithoutCacheDirFail(t *testing.T) {
+	r := NewJSRunner(JSConfig{})
+	_, err := r.Run(NewAnalyzeRule(), "java.cacheFile('https://example.com/a.txt')", nil, "")
+	if err == nil || !strings.Contains(err.Error(), "缓存目录") {
+		t.Fatalf("未配置缓存目录时应明确报错，实际 %v", err)
+	}
+}

internal/service/reader/rule/goja.go

@@ -72,6 +72,9 @@ type JSConfig struct {
 	// Browser 宿主浏览器实现（java.startBrowser / startBrowserAwait）。
 	// nil 时这两个函数抛出不支持错误。
 	Browser BrowserHost
+	// CacheDir 书源文件缓存根目录（java.downloadFile / cacheFile 落盘用）。
+	// 为空时这些函数抛出明确错误。
+	CacheDir string
 	// Ctx 本次执行的可取消上下文，透传给 BrowserHost 的等待。
 	Ctx context.Context
 }
@@ -211,11 +214,100 @@ func NewJSRunner(cfg JSConfig) *JSRunner {
 	vm.Set("source", srcObj)
 	// java 也要在 jsLib 之前就位（jsLib 顶层可能引用 java.*）。
 	r.installJava(nil)
+	// Packages（Java 类命名空间）同样要在 jsLib 之前注入：不少书源在 jsLib 或
+	// 目录/正文规则里用 `new Packages.java.util.LinkedHashMap()` 这类写法。
+	r.installPackages()
 	// 部分源把 source 的方法也当 java 成员用（同一 Kotlin 对象暴露两份）。
 	r.loadJSLib()
 	return r
 }
 
+// installPackages 注入 Java 风格类命名空间（Packages.java.util.*）。
+//
+// goja 是纯 JS 运行时，没有 Java。书源（尤其照搬 Java 教程写的）常用
+// `new Packages.java.util.ArrayList()` / `LinkedHashMap` / `HashMap` 来拼
+// 目录列表和请求头，缺了它整条规则直接 ReferenceError（拷贝漫画轻小说源的
+// 目录规则就是这么写的）。
+//
+// 实现要点：容器用「真正的 JS 数组 / 对象」，方法用 Object.defineProperty 定义为
+// 不可枚举属性。这样容器交给引擎侧（GetElements/GetString）时导出的是干净的
+// 数组（[]any）或映射（map[string]any），而不会把 add/put 这些方法也当成元素或
+// 请求头带出去。
+func (r *JSRunner) installPackages() {
+	if _, err := r.vm.RunString(packagesPreamble); err != nil {
+		// 注入失败不影响其它规则，只是 Packages.* 不可用。
+		r.jsLibErr = fmt.Errorf("Packages 环境初始化失败: %w", err)
+	}
+}
+
+// packagesPreamble 定义全局 Packages（以及与之等价的 java.util / java.lang 常用类）。
+const packagesPreamble = `
+var Packages = (function () {
+  function def(o, k, v) {
+    Object.defineProperty(o, k, { value: v, enumerable: false, writable: true, configurable: true });
+  }
+  function makeMap() {
+    var m = {};
+    def(m, 'put', function (k, v) { m[k] = v; return v; });
+    def(m, 'putAll', function (o) { if (o) { for (var k in o) { m[k] = o[k]; } } });
+    def(m, 'get', function (k) { return m[k] === undefined ? null : m[k]; });
+    def(m, 'getOrDefault', function (k, d) { return m[k] === undefined ? d : m[k]; });
+    def(m, 'containsKey', function (k) { return Object.prototype.hasOwnProperty.call(m, k); });
+    def(m, 'containsValue', function (v) { for (var k in m) { if (m[k] === v) { return true; } } return false; });
+    def(m, 'remove', function (k) { var v = m[k]; delete m[k]; return v; });
+    def(m, 'size', function () { return Object.keys(m).length; });
+    def(m, 'isEmpty', function () { return Object.keys(m).length === 0; });
+    def(m, 'clear', function () { for (var k in m) { delete m[k]; } });
+    def(m, 'keySet', function () { return Object.keys(m); });
+    def(m, 'values', function () { var a = []; for (var k in m) { a.push(m[k]); } return a; });
+    def(m, 'entrySet', function () { var a = []; for (var k in m) { a.push({ key: k, value: m[k] }); } return a; });
+    def(m, 'toString', function () { return JSON.stringify(m); });
+    return m;
+  }
+  function makeList() {
+    var a = [];
+    def(a, 'add', function (x) { a.push(x); return true; });
+    def(a, 'addAll', function (xs) { if (xs) { for (var i = 0; i < xs.length; i++) { a.push(xs[i]); } } return true; });
+    def(a, 'get', function (i) { return a[i]; });
+    def(a, 'size', function () { return a.length; });
+    def(a, 'isEmpty', function () { return a.length === 0; });
+    def(a, 'contains', function (x) { return a.indexOf(x) >= 0; });
+    def(a, 'remove', function (i) { return a.splice(i, 1)[0]; });
+    def(a, 'clear', function () { a.length = 0; });
+    def(a, 'toArray', function () { return a.slice(); });
+    def(a, 'toString', function () { return a.join(','); });
+    return a;
+  }
+  var util = {};
+  var mapNames = ['LinkedHashMap', 'HashMap', 'TreeMap', 'Hashtable', 'ConcurrentHashMap', 'LinkedTreeMap'];
+  for (var i = 0; i < mapNames.length; i++) { util[mapNames[i]] = makeMap; }
+  var listNames = ['ArrayList', 'LinkedList', 'Vector'];
+  for (var j = 0; j < listNames.length; j++) { util[listNames[j]] = makeList; }
+  util.HashSet = makeList;
+  util.Arrays = { asList: function () { return Array.prototype.slice.call(arguments); } };
+  util.Collections = {
+    emptyList: function () { return []; },
+    emptyMap: function () { return makeMap(); },
+    singletonList: function (x) { return [x]; }
+  };
+  var lang = {
+    String: function (v) { return v == null ? '' : String(v); },
+    Integer: function (v) { return parseInt(v, 10) || 0; },
+    Long: function (v) { return parseInt(v, 10) || 0; },
+    Double: function (v) { return parseFloat(v) || 0; },
+    Boolean: function (v) { return !!v; },
+    StringBuilder: function () {
+      var s = '';
+      var o = {};
+      def(o, 'append', function (x) { s += (x == null ? '' : x); return o; });
+      def(o, 'toString', function () { return s; });
+      return o;
+    }
+  };
+  return { java: { util: util, lang: lang } };
+})();
+`
+
 // installJava 安装/刷新本次执行可见的 java 对象（桥回指定解析器）。
 func (r *JSRunner) installJava(a *AnalyzeRule) {
 	r.vm.Set("java", newJavaObject(r.vm, r, a))
@@ -399,7 +491,7 @@ func (r *JSRunner) Run(a *AnalyzeRule, js string, result any, baseURL string) (a
 	}
 	vm.Set("nextChapterUrl", nil)
 
-	prog, err := compileCached(scopedRuleJS(js))
+	prog, err := compileRuleJS(js)
 	if err != nil {
 		return nil, fmt.Errorf("JS 编译失败: %w", err)
 	}
@@ -441,6 +533,31 @@ func scopedRuleJS(js string) string {
 	return "{\n" + js + "\n}"
 }
 
+// functionRuleJS 把规则 JS 包成函数体后求值。
+//
+// legado 允许书源规则用顶层 `return` 提前返回（拷贝漫画轻小说源的正文规则
+// 就在 if 分支里 `return '<img ...>'`），而 JS 脚本语法不允许顶层 return，
+// 只有函数体允许。这里作为块形式的兜底。
+func functionRuleJS(js string) string {
+	return "(function(){\n" + js + "\n})()"
+}
+
+// compileRuleJS 编译一段书源规则 JS。
+//
+// 优先用「块」形式：块的完成值就是最后一条语句的值，大量书源依赖它
+// （如 `@js:1+2` 直接产出 3），且块作用域能隔离顶层 let/const（见 scopedRuleJS）。
+// 块形式编译失败时退回「函数体」形式，兼容 legado 允许的顶层 return。
+func compileRuleJS(js string) (*goja.Program, error) {
+	prog, err := compileCached(scopedRuleJS(js))
+	if err == nil {
+		return prog, nil
+	}
+	if prog2, err2 := compileCached(functionRuleJS(js)); err2 == nil {
+		return prog2, nil
+	}
+	return nil, err // 两种形式都编译不过，返回块形式的错误（更贴近书源原文）
+}
+
 // exportValue 把 JS 返回值转为 Go 值（字符串/数值/映射/切片）。
 func exportValue(v goja.Value) any {
 	if v == nil || goja.IsUndefined(v) || goja.IsNull(v) {
@@ -495,6 +612,9 @@ func newResponseObject(vm *goja.Runtime, body string, code int, finalURL string,
 	}
 	mustSet("body", func(call goja.FunctionCall) goja.Value { return vm.ToValue(body) })
 	mustSet("bodyStr", body)
+	// bodyAsBytes：部分书源用 `java.bytesToStr(resp.bodyAsBytes(), enc)` 处理
+	// 非 UTF-8（GBK）正文（拷贝漫画轻小说源即如此）。
+	mustSet("bodyAsBytes", func(call goja.FunctionCall) goja.Value { return vm.ToValue(vm.NewArrayBuffer([]byte(body))) })
 	mustSet("code", func(call goja.FunctionCall) goja.Value { return vm.ToValue(code) })
 	mustSet("url", func(call goja.FunctionCall) goja.Value { return vm.ToValue(finalURL) })
 	mustSet("header", func(call goja.FunctionCall) goja.Value {

internal/service/reader/rule/js_test.go

@@ -332,14 +332,51 @@ func TestJSUnsupportedStillWorks(t *testing.T) {
 
 // ─── 沙箱边界 ───────────────────────────────────────────────────────────────
 
+// TestJSSandboxUnsupported 服务端不接受书源读取宿主任意文件。
+//
+// 文件类接口（cacheFile/downloadFile/readTxtFile/...）已实现，但路径被限制在
+// 书源自己的缓存目录内：越权路径安全地返回空，而不是把 /etc/passwd 交出去，
+// 也不应因为越权路径抛异常（否则书源会误判为「线路故障」反复重试）。
+// 真正无实现的能力（解压包、无头浏览器等）继续明确抛「不支持」。
 func TestJSSandboxUnsupported(t *testing.T) {
 	r := newTestRunner()
 	a := NewAnalyzeRule()
 	a.SetJSRunner(r.ForAnalyzer(a))
 	a.SetContent("", "")
-	_, err := a.GetString(`@js:java.readTxtFile('/etc/passwd')`, nil, false)
-	if err == nil || !strings.Contains(err.Error(), "不支持") {
-		t.Fatalf("expected sandbox error, got %v", err)
+	got, err := a.GetString(`@js:java.readTxtFile('/etc/passwd')`, nil, false)
+	if err != nil {
+		t.Fatalf("越权路径应安全返回空而不是抛异常: %v", err)
+	}
+	if strings.Contains(got, "root:") || strings.Contains(got, "/bin/") {
+		t.Fatalf("沙箱被突破，读到了宿主文件: %q", got)
+	}
+	for _, call := range []string{`java.unzipFile('/tmp/a.zip')`, `java.webView('x')`} {
+		if _, err := a.GetString(`@js:`+call, nil, false); err == nil || !strings.Contains(err.Error(), "不支持") {
+			t.Fatalf("%s 应继续抛「不支持」，实际 %v", call, err)
+		}
+	}
+}
+
+// TestRuleJSTopLevelReturn legado 允许规则 JS 顶层 return；无 return 时仍取最后
+// 一条语句的值（`@js:1+2` → 3）。
+func TestRuleJSTopLevelReturn(t *testing.T) {
+	r := NewJSRunner(JSConfig{})
+	ar := NewAnalyzeRule()
+
+	v, err := r.Run(ar, "if (1) { return '早退'; }\nreturn '兜底';", nil, "")
+	if err != nil {
+		t.Fatalf("顶层 return 应可用: %v", err)
+	}
+	if got := anyToString(v); got != "早退" {
+		t.Fatalf("top-level return = %q, want 早退", got)
+	}
+
+	v2, err := r.Run(ar, "1 + 2", nil, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := anyToString(v2); got != "3" {
+		t.Fatalf("最后一条语句的值 = %q, want 3", got)
 	}
 }
 

internal/service/reader/rule/json.go

@@ -32,13 +32,53 @@ func jsonRead(root any, path string) any {
 	if root == nil || path == "" {
 		return nil
 	}
-	v, err := jsonpathGet(path, root)
+	v, err := jsonpathGet(normalizeJSONPath(path), root)
 	if err != nil {
 		return nil
 	}
 	return v
 }
 
+// normalizeJSONPath 把 legado（Jayway）允许、而 PaesslerAG/jsonpath 拒绝的写法
+// 归一化成合法路径，共两处差异：
+//
+//  1. 缺根 `$`：Jayway 要求路径以 `$`/`@` 开头，legado 书源却常直接写
+//     `results.list`、`results.list.[*]`。PaesslerAG 对「不含 `[]`/`*` 的裸路径」
+//     恰好能容忍（内部按 `$.` 解析），但一旦出现 `[*]` 就报
+//     `unexpected "*" while scanning extensions`。这里统一补根。
+//  2. 点后紧跟方括号：`results.list.[*]`、`$.a.[0]`、`$.a.['k']`。Jayway 里
+//     `.[` 等价于 `[`，PaesslerAG 会报 `unexpected "[" while scanning field`。
+//
+// 两处都会让整条规则静默返回空——表现为「书源明明有效却搜不出任何结果」
+// （拷贝轻小说源的搜索列表规则就是 `results.list.[*]`）。
+func normalizeJSONPath(path string) string {
+	p := strings.TrimSpace(path)
+	if p == "" {
+		return path
+	}
+	switch {
+	case strings.HasPrefix(p, "$"), strings.HasPrefix(p, "@"):
+		// 已有根，保持
+	case strings.HasPrefix(p, "."):
+		p = "$" + p // `..a` 这类递归写法，补 `$` 而不是 `$.`
+	default:
+		p = "$." + p
+	}
+	if !strings.Contains(p, ".[") {
+		return p
+	}
+	var b strings.Builder
+	b.Grow(len(p))
+	for i := 0; i < len(p); i++ {
+		// 丢掉 `[` 前多余的点；递归下降 `..[` 保持原样。
+		if p[i] == '.' && i+1 < len(p) && p[i+1] == '[' && i > 0 && p[i-1] != '.' {
+			continue
+		}
+		b.WriteByte(p[i])
+	}
+	return b.String()
+}
+
 // jsonValueToString 对应 Kotlin 的 ob.toString() / joinToString("\n")。
 // 列表按 "\n" 拼接（legado 的 getString 就是这么做的）；对象走 Java 的 Map.toString
 // 形态（见 javaValueString），书源的正则大量依赖这个形态。

internal/service/reader/rule/packages_test.go

@@ -0,0 +1,110 @@
+package rule
+
+import (
+	"testing"
+)
+
+// 本文件：legado 兼容性回归——`Packages.java.util.*` 容器与 `.[*]` 形式的 JSONPath。
+//
+// 背景（拷贝系列轻小说源在 MeBox 搜不到/读不了的根因）：
+//  1. 搜索列表规则写成 `results.list.[*]`（legado/Jayway 接受），PaesslerAG 直接
+//     解析报错返回空；
+//  2. 目录规则用 `new Packages.java.util.LinkedHashMap()` / `ArrayList()` 拼装，
+//     goja 里没有 Java，整条规则 ReferenceError。
+
+// TestNormalizeJSONPathDotBracket 点后跟方括号应归一化成合法路径。
+func TestNormalizeJSONPathDotBracket(t *testing.T) {
+	cases := map[string]string{
+		"results.list.[*]":   "$.results.list[*]",
+		"$.results.list.[*]": "$.results.list[*]",
+		"$.a.[0].b":          "$.a[0].b",
+		"$.a.['k']":          "$.a['k']",
+		"$.results.list":     "$.results.list",
+		"$.results..list[*]": "$.results..list[*]",
+		"results.list":       "$.results.list",
+		"$[0].name":          "$[0].name",
+		"..list[*]":          "$..list[*]",
+	}
+	for in, want := range cases {
+		if got := normalizeJSONPath(in); got != want {
+			t.Errorf("normalizeJSONPath(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+// TestGetElementsDotBracketStarJsonPath 真实书源的 `results.list.[*]` 必须能取到列表。
+func TestGetElementsDotBracketStarJsonPath(t *testing.T) {
+	const body = `{"results":{"list":[{"name":"甲"},{"name":"乙"}]}}`
+	for _, rule := range []string{"results.list.[*]", "$.results.list", "results.list"} {
+		ar := NewAnalyzeRule()
+		ar.SetContent(body, "")
+		els, err := ar.GetElements(rule)
+		if err != nil {
+			t.Fatalf("%s: %v", rule, err)
+		}
+		if len(els) != 2 {
+			t.Fatalf("%s: elements=%d, want 2", rule, len(els))
+		}
+		name, err := ar.GetString("$.name", els[0], false)
+		if err != nil || name != "甲" {
+			t.Fatalf("%s: first name=%q err=%v", rule, name, err)
+		}
+	}
+}
+
+// TestPackagesUtilCollections Packages.java.util 的 List/Map 应能拼出目录列表，
+// 且导出给引擎的是干净的数组/映射（方法不能混进元素里）。
+func TestPackagesUtilCollections(t *testing.T) {
+	r := NewJSRunner(JSConfig{})
+	if err := r.JSLibErr(); err != nil {
+		t.Fatalf("Packages 环境初始化失败: %v", err)
+	}
+	ar := NewAnalyzeRule()
+	ar.SetContent(`{"results":{"list":[{"name":"第一卷","id":7}]}}`, "https://api.example.com/volumes")
+	ar.SetJSRunner(r.ForAnalyzer(ar))
+
+	js := `<js>
+function mk(n, u) { var m = new Packages.java.util.LinkedHashMap(); m.put('name', n); m.put('url', u); return m; }
+var base = 'https://api.example.com/volume/';
+var out = new Packages.java.util.ArrayList();
+var vols = JSON.parse(result).results.list;
+for (var i = 0; i < vols.length; i++) { out.add(mk(vols[i].name, base + vols[i].id)); }
+out;</js>`
+	els, err := ar.GetElements(js)
+	if err != nil {
+		t.Fatalf("GetElements: %v", err)
+	}
+	if len(els) != 1 {
+		t.Fatalf("elements=%d, want 1", len(els))
+	}
+	if m, ok := els[0].(map[string]any); ok {
+		if _, hasMethod := m["put"]; hasMethod {
+			t.Fatalf("容器方法泄漏进了元素: %#v", m)
+		}
+	}
+	name, err := ar.GetString("$.name", els[0], false)
+	if err != nil || name != "第一卷" {
+		t.Fatalf("name=%q err=%v", name, err)
+	}
+	url, _ := ar.GetString("$.url", els[0], false)
+	if url != "https://api.example.com/volume/7" {
+		t.Fatalf("url=%q", url)
+	}
+}
+
+// TestPackagesHashMapUsableAsHeaders java.get(url, headers) 的 headers 用
+// Packages.java.util.HashMap 构造时，导出结果应是干净的键值映射。
+func TestPackagesHashMapUsableAsHeaders(t *testing.T) {
+	r := NewJSRunner(JSConfig{})
+	v, err := r.Run(NewAnalyzeRule(), `(function () {
+  var h = new Packages.java.util.HashMap();
+  h.put('X-Test', 'v1');
+  return JSON.stringify(h);
+})()`, nil, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if s := anyToString(v); s != `{"X-Test":"v1"}` {
+		t.Fatalf("HashMap 导出含额外键: %s", s)
+	}
+}

internal/service/reader/rule/url.go

@@ -43,6 +43,10 @@ type Request struct {
 	// 返回而不是解码成文本（对应 legado AnalyzeUrl.type）。
 	// 书源用它配合 data: 地址当参数信封，见 datauri.go。
 	HexBody bool
+	// Raw 请求响应按「原始字节」返回，跳过 charset 解码。
+	// 供 java.downloadFile / java.cacheFile 这类需要保真落盘的调用使用：
+	// 一旦按 UTF-8 解码，GBK 字节会被替换成 U+FFFD，写出来的文件就坏了。
+	Raw bool
 	// BodyJsFn 对应 UrlOption.bodyJs：响应体二次处理（JS 执行闭包）。
 	BodyJsFn func(body string) string
 	// Unsupported 非 nil 表示该请求依赖当前阶段不支持的能力，

web/src/hooks/useHorizontalSwipe.ts

@@ -0,0 +1,145 @@
+import { useCallback, useRef, type TouchEvent as ReactTouchEvent } from 'react'
+
+// 横向滑动手势：给「左右翻页」的阅读区补上手机上的滑动手势。
+// 原来只能点左 30% / 右 30% 分区翻页，手指横滑没有任何反应，翻页很别扭。
+//
+// 判定规则（和纵向滚动共存的关键）：
+// - 方向要先判定出来：位移超过 slop 后，横向位移要明显大于纵向位移（dominance 倍）
+//   才算横滑，否则算纵向滑动/滚动，本次手势彻底放弃（连 click 也不吞）；
+// - 没走跟手（点按、或没传 onDrag）时，仍按 minDistance + maxDuration 判定一次滑动，
+//   短距离当点击处理，交给下面的分区点击。
+//
+// 跟手拖拽：传了 onDrag 之后，手指横向移动会实时回调位移，松手再回调 onDragEnd，
+// 由宿主把内容平移到位（正文列 / 漫画舞台）并决定翻页还是回弹。滑动途中内容就跟着
+// 手指走，不再等到松手才动一下。跟手手势一律按「拖动」处理，不再走 maxDuration 判定
+// （慢慢拖过去也是拖动）。
+//
+// 一次滑动之后浏览器仍可能补一个 click（落在原来的分区按钮上），
+// 于是会「滑一页又点一页」翻两页。用 consumeSwipe() 让点击回调先问一句：
+// 这次 click 是不是刚被滑动吃掉，是则跳过。每次 touchstart 会重置这个标记，
+// 所以真实滑动不产生 click 时也不会误吞下一次点击。
+
+/** 判定手势方向的位移阈值（px）：比这还小就还在点按的抖动范围内。 */
+const DIRECTION_SLOP = 12
+
+interface HorizontalSwipeOptions {
+  /** 从左往右滑（手指向右移）。 */
+  onSwipeRight: () => void
+  /** 从右往左滑（手指向左移）。 */
+  onSwipeLeft: () => void
+  /** 触发翻页所需的最小水平位移（px）。 */
+  minDistance?: number
+  /** 水平位移需达到垂直位移的这个倍数才算横滑，避免和纵向滚动打架。 */
+  dominance?: number
+  /** 手势超过这个时长不算滑动（毫秒）。只对非跟手的滑动判定生效。 */
+  maxDuration?: number
+  /** 跟手拖拽中的位移（px，向右为正）。传了才启用跟手。 */
+  onDrag?: (dx: number) => void
+  /** 跟手松手：宿主在这里回弹或翻页（随后浏览器补发的 click 会被吞掉）。 */
+  onDragEnd?: (dx: number) => void
+}
+
+interface HorizontalSwipeHandlers {
+  onTouchStart: (e: ReactTouchEvent) => void
+  onTouchMove: (e: ReactTouchEvent) => void
+  onTouchEnd: (e: ReactTouchEvent) => void
+  onTouchCancel: () => void
+  /** 点击回调里先调用；返回 true 表示这次点击已被滑动消费，应跳过默认动作。 */
+  consumeSwipe: () => boolean
+}
+
+export function useHorizontalSwipe({
+  onSwipeRight,
+  onSwipeLeft,
+  minDistance = 45,
+  dominance = 1.2,
+  maxDuration = 800,
+  onDrag,
+  onDragEnd,
+}: HorizontalSwipeOptions): HorizontalSwipeHandlers {
+  const startRef = useRef<{ x: number; y: number; t: number } | null>(null)
+  const consumedRef = useRef(false)
+  /** 本次手势是否已判定为横滑并在跟手。 */
+  const draggingRef = useRef(false)
+  const lastDxRef = useRef(0)
+
+  const onTouchStart = useCallback((e: ReactTouchEvent) => {
+    const t = e.touches[0]
+    if (!t) return
+    startRef.current = { x: t.clientX, y: t.clientY, t: Date.now() }
+    consumedRef.current = false
+    draggingRef.current = false
+    lastDxRef.current = 0
+  }, [])
+
+  const onTouchMove = useCallback(
+    (e: ReactTouchEvent) => {
+      const start = startRef.current
+      const t = e.touches[0]
+      if (!start || !t) return
+      const dx = t.clientX - start.x
+      const dy = t.clientY - start.y
+      if (!draggingRef.current) {
+        if (!onDrag) return
+        if (Math.abs(dx) < DIRECTION_SLOP && Math.abs(dy) < DIRECTION_SLOP) return
+        // 纵向占优：这是滚动，不是翻页。丢掉起点，之后不再判定滑动也不吞 click。
+        if (Math.abs(dx) < Math.abs(dy) * dominance) {
+          startRef.current = null
+          return
+        }
+        draggingRef.current = true
+      }
+      lastDxRef.current = dx
+      onDrag?.(dx)
+    },
+    [onDrag, dominance],
+  )
+
+  const onTouchEnd = useCallback(
+    (e: ReactTouchEvent) => {
+      const start = startRef.current
+      startRef.current = null
+      if (draggingRef.current) {
+        draggingRef.current = false
+        // 跟手手势一律吞掉随之而来的 click：翻页已经在 onDragEnd 里决定了，
+        // 不吞的话短距离拖动会「回弹 + 再翻一页」。
+        consumedRef.current = true
+        const t = e.changedTouches[0]
+        // 用松手这一刻的位置而不是最后一次 touchmove：手指最后那几像素也要算进去。
+        const dx = start && t ? t.clientX - start.x : lastDxRef.current
+        onDragEnd?.(dx)
+        return
+      }
+      const t = e.changedTouches[0]
+      if (!start || !t) return
+
+      const dx = t.clientX - start.x
+      const dy = t.clientY - start.y
+      if (Date.now() - start.t > maxDuration) return
+      if (Math.abs(dx) < minDistance) return
+      if (Math.abs(dx) < Math.abs(dy) * dominance) return
+
+      consumedRef.current = true
+      if (dx > 0) onSwipeRight()
+      else onSwipeLeft()
+    },
+    [onSwipeRight, onSwipeLeft, minDistance, dominance, maxDuration, onDragEnd],
+  )
+
+  const onTouchCancel = useCallback(() => {
+    startRef.current = null
+    if (!draggingRef.current) return
+    draggingRef.current = false
+    // 手势被系统打断（来电、边缘返回手势）：按「没翻页」处理，让内容回弹。
+    // 传 0 而不是最后的位置——打断不等于用户想翻页，别顺手翻过去。
+    onDragEnd?.(0)
+  }, [onDragEnd])
+
+  const consumeSwipe = useCallback(() => {
+    if (!consumedRef.current) return false
+    consumedRef.current = false
+    return true
+  }, [])
+
+  return { onTouchStart, onTouchMove, onTouchEnd, onTouchCancel, consumeSwipe }
+}

web/src/pages/reader/ReaderComic.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useRef, useState, type RefObject } from 'react'
 import { Loader2 } from 'lucide-react'
 
 import { useSmoothWheelScroll } from '../../hooks/useSmoothWheelScroll'
@@ -27,6 +27,13 @@ interface ReaderComicProps {
   spread?: number[] | null
   /** 滚动模式的图片显示尺寸档位（翻页模式不适用，传 default 即可）。 */
   imageFit?: ComicImageFit
+  /**
+   * 翻页模式的跟手拖拽：把当前页左右各摆一页到舞台两侧，整条舞台由外层按
+   * stageRef 直接平移（见 ReaderViewPage 的 onPageDrag）。并排铺开两页时关闭。
+   */
+  draggable?: boolean
+  /** 跟手拖拽要平移的舞台元素（由外层拿着直接写 transform，不走 React state）。 */
+  stageRef?: RefObject<HTMLDivElement>
 }
 
 function ComicImage({
@@ -36,6 +43,7 @@ function ComicImage({
   half = false,
   imageFit = 'default',
   viewportHeight = 0,
+  eager = false,
 }: {
   src: string
   theme: { bg: string; text: string; accent: string }
@@ -47,6 +55,10 @@ function ComicImage({
   imageFit?: ComicImageFit
   // viewportHeight：滚动容器高度（px），height/long 档位按它换算。
   viewportHeight?: number
+  // eager：跟手拖拽摆在舞台两侧的那两页。它们被 overflow-hidden 裁在屏幕外，
+  // 浏览器的懒加载认为「离视口还远」而不去取，横滑过去就会看到转圈，
+  // 所以这两页立刻加载（顺带把下一页提前拉好，翻页不用现等）。
+  eager?: boolean
 }) {
   const [state, setState] = useState<'loading' | 'ok' | 'error'>('loading')
 
@@ -82,7 +94,7 @@ function ComicImage({
     >
       <img
         src={src}
-        loading="lazy"
+        loading={eager ? 'eager' : 'lazy'}
         alt=""
         onLoad={(e) => {
           const el = e.currentTarget
@@ -114,7 +126,7 @@ function ComicImage({
   )
 }
 
-export function ReaderComic({ images, theme, mode, page, onZone, initialImage, onProgress, scrollTo, onScrolled, spread, imageFit = 'default' }: ReaderComicProps) {
+export function ReaderComic({ images, theme, mode, page, onZone, initialImage, onProgress, scrollTo, onScrolled, spread, imageFit = 'default', draggable = false, stageRef }: ReaderComicProps) {
   const scrollRef = useRef<HTMLDivElement>(null)
   const imgRefs = useRef<(HTMLDivElement | null)[]>([])
   const restoredRef = useRef(false)
@@ -174,11 +186,39 @@ export function ReaderComic({ images, theme, mode, page, onZone, initialImage, o
     const group = (spread ?? []).filter((i) => i >= 0 && i < images.length)
     const idxs = group.length > 0 ? group : [Math.min(Math.max(page, 0), images.length - 1)]
     const paired = idxs.length > 1
+
+    if (!draggable) {
+      return (
+        <div className="flex h-full items-center justify-center">
+          {idxs.map((i) => (
+            <ComicImage key={images[i]} src={images[i]} theme={theme} fit half={paired} />
+          ))}
+        </div>
+      )
+    }
+
+    // 跟手拖拽：当前页左右各摆一页，整条舞台由外层直接平移（stageRef），
+    // 于是手指横滑时左右两页就在屏幕边上，滑到一半松手能接着滑完。
+    // 外面再套一层 overflow-hidden：桌面端正文列限宽 900px 居中，两侧那两页要是
+    // 溢出到窗口里会在留白处露出来。
+    //
+    // 单元格按图片序号做 key、位置用 left 百分比铺开，而不是固定三个「上一页/当前/下一页」
+    // 槽位换内容：翻页时变的只是 left 偏移，<img> 的 src 不变，浏览器不会重新解码、
+    // 也不会先闪一下转圈。两侧那两页同时充当下一页/上一页的预取。
+    const cells = [page - 1, page, page + 1].filter((i) => i >= 0 && i < images.length)
     return (
-      <div className="flex h-full items-center justify-center">
-        {idxs.map((i) => (
-          <ComicImage key={images[i]} src={images[i]} theme={theme} fit half={paired} />
-        ))}
+      <div className="relative h-full w-full overflow-hidden">
+        <div ref={stageRef} className="relative h-full w-full">
+          {cells.map((i) => (
+            <div
+              key={images[i]}
+              className="absolute inset-y-0 flex items-center justify-center"
+              style={{ left: `${(i - page) * 100}%`, width: '100%' }}
+            >
+              <ComicImage src={images[i]} theme={theme} fit eager={i !== page} />
+            </div>
+          ))}
+        </div>
       </div>
     )
   }

web/src/pages/reader/ReaderViewPage.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties } from 'react'
 import { useParams } from 'react-router-dom'
 import toast from 'react-hot-toast'
 import {
@@ -28,6 +28,7 @@ import {
   type ReaderSearchOrigin,
 } from '../../api/reader'
 import { useComicSpreads } from '../../hooks/useComicSpreads'
+import { useHorizontalSwipe } from '../../hooks/useHorizontalSwipe'
 import { useSmoothWheelScroll } from '../../hooks/useSmoothWheelScroll'
 import { useReaderAudioStore } from '../../stores/readerAudio'
 import { COMIC_IMAGE_FITS, READER_THEMES, getReaderTheme, useReaderSettingsStore } from '../../stores/readerSettings'
@@ -54,6 +55,11 @@ const COMIC_SAVE_INTERVAL_MS = 2_000
 /** 菜单打开时正文下移过渡（与顶栏动画同节奏）。 */
 const MENU_SHIFT = 'transition-transform duration-200'
 
+/** 翻页动画时长。正文列的平移过渡，以及跟手拖拽松手后的回弹/滑完，都用这一条。 */
+const PAGE_TRANSITION = 'transform 220ms ease'
+/** 跟手拖拽要翻页所需的最小位移（px）。 */
+const DRAG_TURN_DISTANCE = 45
+
 // 滚轮翻页参数（deltaY 已按 deltaMode 归一化成像素）
 /** 单次 deltaY 达到这个量视为鼠标滚轮的一格（一格一页）。 */
 const WHEEL_NOTCH = 40
@@ -79,6 +85,91 @@ interface ReaderParagraphBlock {
   comments: ReaderContentComment[]
 }
 
+/**
+ * 翻页模式正文列：与页码 state 解耦。
+ *
+ * 长章（几百页 CSS 多栏）里，若每次 setPage 都把整棵段落树再调和一遍，
+ * 手机主线程会卡数百毫秒，表现为「松手停一下才翻到下一页」。
+ * 分页位移改走 contentRef 命令式写入；这里用 memo，页码变时跳过段落重渲染。
+ */
+const ReaderTextPageBody = memo(function ReaderTextPageBody({
+  blocks,
+  paragraphSpacing,
+  fontSize,
+  accent,
+  onOpenComment,
+}: {
+  blocks: ReaderParagraphBlock[]
+  paragraphSpacing: number
+  fontSize: number
+  accent: string
+  onOpenComment: (comment: ReaderContentComment) => void
+}) {
+  return (
+    <>
+      {blocks.map((block, key) => {
+        const { text, comments } = block
+        // content-visibility：跳过视口外段落的绘制。长章翻页时否则每次 transform
+        // 都要重绘整章（实测可到数百毫秒）。auto 尺寸会记住上次渲染高度，减少分页抖动。
+        const skipPaint: CSSProperties = {
+          contentVisibility: 'auto',
+          containIntrinsicSize: 'auto 4em',
+        }
+        if (text.startsWith(IMG_MARK)) {
+          return (
+            <p key={key} style={{ marginBottom: paragraphSpacing, textAlign: 'center', ...skipPaint }}>
+              <img
+                src={text.slice(IMG_MARK.length)}
+                alt=""
+                referrerPolicy="no-referrer"
+                style={{ maxWidth: '100%', maxHeight: '70vh', margin: '0 auto', objectFit: 'contain' }}
+              />
+            </p>
+          )
+        }
+        const standalone = text === '' && comments.length > 0
+        return (
+          <p
+            key={key}
+            style={{
+              textIndent: text ? '2em' : undefined,
+              marginBottom: paragraphSpacing,
+              textAlign: standalone && comments.every((c) => c.block) ? 'center' : undefined,
+              ...skipPaint,
+            }}
+          >
+            {text}
+            {comments.map((c, ci) => (
+              <button
+                key={`${c.line}-${ci}`}
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation()
+                  onOpenComment(c)
+                }}
+                title={c.label || '段评'}
+                className="relative z-10 mx-1 inline-flex items-center gap-0.5 rounded-full border align-middle"
+                style={{
+                  borderColor: accent,
+                  color: accent,
+                  fontSize: Math.max(10, fontSize - 4),
+                  lineHeight: 1,
+                  padding: '2px 6px',
+                  verticalAlign: 'middle',
+                  pointerEvents: 'auto',
+                }}
+              >
+                <MessageSquare size={11} />
+                {c.count > 0 && <span>{c.count}</span>}
+              </button>
+            ))}
+          </p>
+        )
+      })}
+    </>
+  )
+})
+
 function firstReadableIndex(chapters: ReaderChapter[]): number {
   const i = chapters.findIndex((c) => !c.is_volume && c.url)
   if (i !== -1) return i
@@ -87,6 +178,40 @@ function firstReadableIndex(chapters: ReaderChapter[]): number {
   return j === -1 ? 0 : j
 }
 
+/**
+ * 漫画跟手拖拽松手后「滑完这一页」。
+ *
+ * 舞台两侧各摆着相邻的一页，手指拖到哪儿舞台就平移到哪儿。松手要翻页时，
+ * 先把新页瞬移到手指离开的位置（这一步必须关掉过渡，否则会先反着滑一段），
+ * 读一次布局把这一帧定成过渡起点，再打开过渡滑回 0；与此同时页码 +1/-1，
+ * ReaderComic 那边单元格的 left 偏移在同一次提交里跟着换，两者相抵，
+ * 屏幕上看到的就是新页从手指离开的位置平滑归位。
+ */
+function settleComicDrag(el: HTMLDivElement, turn: 1 | -1, dx: number, turnPage: () => void): void {
+  const width = el.clientWidth || 1
+  el.style.transition = 'none'
+  el.style.transform = `translateX(${turn > 0 ? width + dx : -width + dx}px)`
+  void el.offsetWidth
+  el.style.transition = PAGE_TRANSITION
+  el.style.transform = 'translateX(0px)'
+  turnPage()
+}
+
+/**
+ * 文本滑动松手后的跟手层归位。正文多栏已瞬移，这里只把跟手层从「画面连续」的
+ * 位移滑回 0。不用 void offsetWidth 强刷布局——长章多栏一强制回流就要几百毫秒。
+ * turn=1 下一页，turn=-1 上一页；dx 为松手时的跟手位移。
+ */
+function settleTextDrag(dragEl: HTMLDivElement, turn: 1 | -1, dx: number): void {
+  const width = dragEl.clientWidth || 1
+  dragEl.style.transition = 'none'
+  dragEl.style.transform = `translate3d(${turn > 0 ? width + dx : -width + dx}px,0,0)`
+  requestAnimationFrame(() => {
+    dragEl.style.transition = 'transform 140ms ease-out'
+    dragEl.style.transform = 'translate3d(0,0,0)'
+  })
+}
+
 export default function ReaderViewPage() {
   const { bookId = '' } = useParams()
   const settings = useReaderSettingsStore()
@@ -129,9 +254,28 @@ export default function ReaderViewPage() {
   const viewportRef = useRef<HTMLDivElement>(null)
   const scrollRef = useRef<HTMLDivElement>(null)
   const contentRef = useRef<HTMLDivElement>(null)
+  /** 文本跟手层：滑动动画也写在这一层，避免给整章多栏做 transition。 */
+  const pageDragRef = useRef<HTMLDivElement>(null)
   const [page, setPage] = useState(0)
   const [pageCount, setPageCount] = useState(1)
   const [vw, setVw] = useState(0)
+  // 文本翻页：位移与页脚先走 DOM，React 的 page state 等到过渡结束后再同步。
+  // 若在同一次点击/触摸里同步 setPage，整页重渲染会堵住下一次绘制，
+  // 命令式 transform 也要等卡完才开始——点按和滑动都会顿一下。
+  const vwRef = useRef(0)
+  const pageRef = useRef(0)
+  const pageCountRef = useRef(1)
+  const chapterTitleRef = useRef('')
+  const pageLabelRef = useRef<HTMLDivElement>(null)
+  const appliedTextPageRef = useRef(-1)
+  const appliedTextVwRef = useRef(-1)
+  const snapTextPageRef = useRef(false)
+  /** 把 pageRef 同步回 React state 的防抖定时器；翻页热路径上绝不同步 setPage。 */
+  const textPageSyncTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+  /** 首次分页完成后锁住 pageCount，避免 content-visibility 改变 scrollWidth 后反复 setPageCount。 */
+  const pageCountLockedRef = useRef(false)
+  vwRef.current = vw
+  pageCountRef.current = pageCount
   // 音频/漫画媒体状态
   const [media, setMedia] = useState<ReaderChapterContent | null>(null)
   const [restorePos, setRestorePos] = useState(0) // 音频秒数 / 漫画图片序号
@@ -170,6 +314,13 @@ export default function ReaderViewPage() {
     comicDoublePage && comicSpreads.length > 0
       ? Math.min(comicSpreadIndexOf[comicPage] ?? 0, comicSpreads.length - 1)
       : 0
+  /** 当前这一屏是不是并排两页（桌面端双页铺开）。 */
+  const comicPaired = comicDoublePage && (comicSpreads[comicSpreadIndex]?.length ?? 0) > 1
+  /**
+   * 漫画翻页模式且单页显示时接跟手拖拽：舞台左右各摆一页，手指横滑整条舞台跟着走。
+   * 并排两页时不接——两侧要摆的是「下一屏」而不是下一张，交给原来的滑动判定即可。
+   */
+  const comicDragSinglePage = contentType === 'image' && settings.pageMode === 'page' && !comicPaired
 
   // ── 漫画滚动模式的图片显示尺寸 ──
   // 档位只在上下滚动模式生效：翻页模式是整页缩放进视口，没有「太大/太小」的问题，
@@ -290,6 +441,11 @@ export default function ReaderViewPage() {
         setContentType(ct.type)
         setMedia(ct)
         setContent(ct.content ?? '')
+        // 换章瞬移到目标页，不要带着上一章的翻页过渡滑过去。
+        snapTextPageRef.current = true
+        appliedTextPageRef.current = -1
+        pageCountLockedRef.current = false
+        pageRef.current = 0
         setPage(0)
         setComicPage(0)
         setCurrentImage(0)
@@ -348,40 +504,155 @@ export default function ReaderViewPage() {
   }, [chapterIndex, book, chapters, contentCacheKey, contentReloadKey])
 
   // ── 分页排版（CSS 多栏 + 平移） ──
+  /** 把正文列平移到指定页。animate=true 时走 220ms 过渡；换章/重排传 false。 */
+  const applyTextPageTransform = useCallback((nextPage: number, animate: boolean) => {
+    const el = contentRef.current
+    if (!el) return
+    const width = vwRef.current > 0 ? vwRef.current : (viewportRef.current?.clientWidth ?? 0)
+    const stride = Math.max(width, 1) + COLUMN_GAP
+    el.style.transition = animate ? PAGE_TRANSITION : 'none'
+    // 正文多栏可能极宽，不要 translate3d / will-change，免得整章被提成巨大合成层。
+    el.style.transform = `translateX(-${nextPage * stride}px)`
+    appliedTextPageRef.current = nextPage
+    appliedTextVwRef.current = width
+  }, [])
+
+  const updateTextPageLabel = useCallback((nextPage: number) => {
+    const label = pageLabelRef.current
+    if (!label) return
+    const title = chapterTitleRef.current
+    label.textContent = title ? `${nextPage + 1} / ${pageCountRef.current} · ${title}` : `${nextPage + 1} / ${pageCountRef.current}`
+  }, [])
+
+  /**
+   * 把 pageRef 写回 React。长章每次 setPage 都会让整页重渲染卡住 1s+，
+   * 所以阅读翻页热路径绝不调用；只在打开菜单 / 换章 / 卸载时同步。
+   */
+  const flushTextPageReactSync = useCallback(() => {
+    if (textPageSyncTimerRef.current !== null) {
+      clearTimeout(textPageSyncTimerRef.current)
+      textPageSyncTimerRef.current = null
+    }
+    setPage((p) => (p === pageRef.current ? p : pageRef.current))
+  }, [])
+
+  /**
+   * 文本翻到指定页（热路径零 setState）。
+   * - 正文多栏瞬移 + 页脚 DOM 更新
+   * - 点按/滚轮：无动画
+   * - 滑动松手：只动画跟手层
+   * dragDx 有值表示来自滑动松手。
+   */
+  const commitTextPage = useCallback(
+    (nextPage: number, opts?: { dragDx?: number }) => {
+      const from = pageRef.current
+      const dragDx = opts?.dragDx
+      const fromSwipe = typeof dragDx === 'number'
+      const turn: 1 | -1 = nextPage >= from ? 1 : -1
+
+      pageRef.current = nextPage
+      applyTextPageTransform(nextPage, false)
+      updateTextPageLabel(nextPage)
+
+      const dragEl = pageDragRef.current
+      if (fromSwipe && dragEl && nextPage !== from) {
+        settleTextDrag(dragEl, turn, dragDx)
+      } else if (dragEl) {
+        dragEl.style.transition = 'none'
+        dragEl.style.transform = 'translate3d(0,0,0)'
+      }
+    },
+    [applyTextPageTransform, updateTextPageLabel],
+  )
+
   const relayout = useCallback(() => {
     const vp = viewportRef.current
     if (!vp) return
     const width = vp.clientWidth
-    setVw(width)
-    const total = vp.scrollWidth
+    // 用正文列自己的 scrollWidth；视口在子元素 transform 时 scrollWidth 会抖，
+    // 导致翻一页就重新 setPageCount → 整页重渲染卡 1s+。
+    const total = contentRef.current?.scrollWidth ?? vp.scrollWidth
     const count = Math.max(1, Math.ceil((total + COLUMN_GAP) / (width + COLUMN_GAP)))
-    setPageCount(count)
-    setPage((p) => {
-      if (pendingEndRef.current && count > 0) {
-        pendingEndRef.current = false
-        return count - 1
-      }
-      if (pendingPosRef.current > 0) {
-        const pos = Math.min(pendingPosRef.current, count - 1)
-        pendingPosRef.current = 0
-        return pos
-      }
-      return Math.min(p, count - 1)
-    })
-  }, [])
+
+    const pendingEnd = pendingEndRef.current && count > 0
+    const pendingPos = pendingPosRef.current > 0
+    const clamped = Math.min(pageRef.current, Math.max(0, count - 1))
+    const nextPage = pendingEnd
+      ? count - 1
+      : pendingPos
+        ? Math.min(pendingPosRef.current, count - 1)
+        : clamped
+
+    if (pendingEnd) pendingEndRef.current = false
+    if (pendingPos) pendingPosRef.current = 0
+
+    const widthChanged = width !== vwRef.current
+    // 窗口宽度变了要重新分页；锁住后忽略 scrollWidth 抖动（content-visibility 估算高度）。
+    if (widthChanged) pageCountLockedRef.current = false
+    const countChanged = !pageCountLockedRef.current && count !== pageCountRef.current
+    const pageChanged = nextPage !== pageRef.current
+
+    // 热路径上尺寸没变就别 setState——否则每次翻页都会重渲染 2000+ 段正文。
+    if (!widthChanged && !countChanged && !pageChanged && !pendingEnd && !pendingPos) {
+      if (count > 1) pageCountLockedRef.current = true
+      return
+    }
+
+    vwRef.current = width
+    if (!pageCountLockedRef.current) pageCountRef.current = count
+    pageRef.current = nextPage
+    if (widthChanged) setVw(width)
+    if (countChanged) {
+      setPageCount(count)
+      if (count > 1) pageCountLockedRef.current = true
+    }
+    if (pageChanged || pendingEnd || pendingPos) {
+      snapTextPageRef.current = true
+      setPage(nextPage)
+      updateTextPageLabel(nextPage)
+      applyTextPageTransform(nextPage, false)
+    }
+  }, [applyTextPageTransform, updateTextPageLabel])
 
   useLayoutEffect(() => {
     relayout()
   }, [relayout, content, settings.fontSize, settings.lineHeight, settings.paragraphSpacing, settings.pageMode, vw])
 
+  // 页码或列宽变了：若翻页回调里已经写过 transform 则跳过，避免把正在播的过渡重开一遍。
+  useLayoutEffect(() => {
+    if (contentType !== 'text' || settings.pageMode !== 'page') return
+    if (appliedTextPageRef.current === page && appliedTextVwRef.current === vw) return
+    const animate = !snapTextPageRef.current && appliedTextPageRef.current !== page
+    snapTextPageRef.current = false
+    pageRef.current = page
+    applyTextPageTransform(page, animate)
+    updateTextPageLabel(page)
+  }, [page, vw, contentType, settings.pageMode, applyTextPageTransform, updateTextPageLabel])
+
   useEffect(() => {
     const vp = viewportRef.current
     if (!vp) return
-    const ro = new ResizeObserver(() => relayout())
+    // 合并同一帧里多次 resize，避免字体/滚动条抖动连带 relayout→setState。
+    let raf = 0
+    const ro = new ResizeObserver(() => {
+      if (raf) cancelAnimationFrame(raf)
+      raf = requestAnimationFrame(() => {
+        raf = 0
+        relayout()
+      })
+    })
     ro.observe(vp)
-    return () => ro.disconnect()
+    return () => {
+      if (raf) cancelAnimationFrame(raf)
+      ro.disconnect()
+    }
   }, [relayout, content, settings.pageMode])
 
+  // 打开菜单时把 pageRef 写回 state，进度条才不会停在旧页。
+  useEffect(() => {
+    if (menuOpen) flushTextPageReactSync()
+  }, [menuOpen, flushTextPageReactSync])
+
   // 滚动模式恢复进度
   useEffect(() => {
     if (settings.pageMode !== 'scroll' || content === null) return
@@ -415,13 +686,22 @@ export default function ReaderViewPage() {
     [book, chapterIndex, chapters],
   )
 
+  // 文本翻页进度：不依赖 React page（翻页热路径不 setPage），定时读 pageRef。
   useEffect(() => {
-    // 只处理文本：听书/漫画的正文为空串（不是 null），不能落到页码保存逻辑里，
-    // 否则打开音频章 1.5 秒后就会把页码 0 写成进度，覆盖掉刚才恢复的秒数。
     if (contentType !== 'text' || settings.pageMode !== 'page' || content === null || chapterIndex === null) return
-    const t = setTimeout(() => savePos(page), 1500)
-    return () => clearTimeout(t)
-  }, [page, content, chapterIndex, settings.pageMode, contentType, savePos])
+    let last = -1
+    const tick = () => {
+      const pos = pageRef.current
+      if (pos === last) return
+      last = pos
+      savePos(pos)
+    }
+    const t = setInterval(tick, 2000)
+    return () => {
+      clearInterval(t)
+      tick()
+    }
+  }, [content, chapterIndex, settings.pageMode, contentType, savePos])
 
   // 漫画单页进度保存
   useEffect(() => {
@@ -599,9 +879,10 @@ export default function ReaderViewPage() {
       scrollRef.current?.scrollBy({ top: -window.innerHeight * 0.9, behavior: 'auto' })
       return
     }
-    if (page > 0) setPage((p) => p - 1)
+    // 文本翻页读 pageRef：动画期间 React page 可能还没跟上，连点不能被旧 state 卡住。
+    if (pageRef.current > 0) commitTextPage(pageRef.current - 1)
     else goChapter(-1, true)
-  }, [contentType, settings.pageMode, comicDoublePage, comicSpreads, comicSpreadIndex, comicPage, page, goChapter])
+  }, [contentType, settings.pageMode, comicDoublePage, comicSpreads, comicSpreadIndex, comicPage, goChapter, commitTextPage])
 
   const goNext = useCallback(() => {
     if (contentType === 'audio') {
@@ -625,15 +906,92 @@ export default function ReaderViewPage() {
       else el?.scrollBy({ top: window.innerHeight * 0.9, behavior: 'auto' })
       return
     }
-    if (page < pageCount - 1) setPage((p) => p + 1)
+    if (pageRef.current < pageCountRef.current - 1) commitTextPage(pageRef.current + 1)
     else goChapter(1)
-  }, [contentType, settings.pageMode, comicDoublePage, comicSpreads, comicSpreadIndex, media, comicPage, page, pageCount, goChapter])
+  }, [contentType, settings.pageMode, comicDoublePage, comicSpreads, comicSpreadIndex, media, comicPage, goChapter, commitTextPage])
 
   // ── 点击分区（左 30% 上一页 / 中间呼出菜单 / 右 30% 下一页） ──
   // 翻页模式用覆盖层上的三个按钮驱动；滚动模式不能再用覆盖层——
   // 覆盖层不是滚动容器的子节点，手机上手指落在它上面会让纵向滑动失效
   // （只能点左右），所以滚动模式改在滚动容器自身的 onClick 上按 x 坐标分区：
   // 纵向拖动不会产生 click，浏览器原生滚动照常工作。
+  //
+  // 手机上再补一层横向滑动：从左往右滑=上一页、从右往左滑=下一页，并且跟手——
+  // 滑动途中内容就跟着手指走，松手再决定翻页还是回弹（判定、跟手位移与
+  // 「滑动后浏览器补发的 click」的去重都在 useHorizontalSwipe 里）。
+  //
+  // 跟手拖拽平移的是两个不同的元素：
+  // - 文本：正文列外面单独挂一层「跟手层」（pageDragRef）。正文多栏只瞬移，
+  //   滑页动画全在跟手层（settleTextDrag）；长章不能给多栏做 transition。
+  // - 漫画：平移 ReaderComic 的舞台（comicStageRef）。舞台两侧摆着上一页/下一页
+  //   （见那边的 carousel 分支），翻页时单元格的 left 偏移与舞台位移在同一次提交里
+  //   相抵，画面看不出切换。
+  const comicStageRef = useRef<HTMLDivElement>(null)
+  const pageDragEnabled = settings.pageMode === 'page' && (contentType === 'text' || comicDragSinglePage)
+
+  const onPageDrag = useCallback(
+    (dx: number) => {
+      const el = contentType === 'image' ? comicStageRef.current : pageDragRef.current
+      if (!el) return
+      el.style.transition = 'none'
+      el.style.transform = `translate3d(${dx}px,0,0)`
+    },
+    [contentType],
+  )
+
+  const onPageDragEnd = useCallback(
+    (dx: number) => {
+      if (contentType === 'image') {
+        const el = comicStageRef.current
+        if (!el) return
+        if (dx <= -DRAG_TURN_DISTANCE) {
+          settleComicDrag(el, 1, dx, goNext)
+          return
+        }
+        if (dx >= DRAG_TURN_DISTANCE) {
+          settleComicDrag(el, -1, dx, goPrev)
+          return
+        }
+        el.style.transition = PAGE_TRANSITION
+        el.style.transform = 'translateX(0px)'
+        return
+      }
+      const el = pageDragRef.current
+      if (!el) return
+      if (dx <= -DRAG_TURN_DISTANCE) {
+        if (pageRef.current < pageCountRef.current - 1) {
+          commitTextPage(pageRef.current + 1, { dragDx: dx })
+        } else {
+          el.style.transition = PAGE_TRANSITION
+          el.style.transform = 'translate3d(0,0,0)'
+          goChapter(1)
+        }
+        return
+      }
+      if (dx >= DRAG_TURN_DISTANCE) {
+        if (pageRef.current > 0) {
+          commitTextPage(pageRef.current - 1, { dragDx: dx })
+        } else {
+          el.style.transition = PAGE_TRANSITION
+          el.style.transform = 'translate3d(0,0,0)'
+          goChapter(-1, true)
+        }
+        return
+      }
+      // 位移不够：回弹，不翻页。
+      el.style.transition = PAGE_TRANSITION
+      el.style.transform = 'translate3d(0,0,0)'
+    },
+    [contentType, goNext, goPrev, commitTextPage, goChapter],
+  )
+
+  const { onTouchStart, onTouchMove, onTouchEnd, onTouchCancel, consumeSwipe } = useHorizontalSwipe({
+    onSwipeRight: goPrev,
+    onSwipeLeft: goNext,
+    minDistance: DRAG_TURN_DISTANCE,
+    onDrag: pageDragEnabled ? onPageDrag : undefined,
+    onDragEnd: pageDragEnabled ? onPageDragEnd : undefined,
+  })
   const handleZoneTap = useCallback(
     (clientX: number, rect: DOMRect) => {
       const x = rect.width > 0 ? (clientX - rect.left) / rect.width : 0.5
@@ -712,6 +1070,7 @@ export default function ReaderViewPage() {
   }, [settings.pageMode, menuOpen, contentType, goPrev, goNext])
 
   const currentChapter = chapterIndex !== null ? chapters[chapterIndex] : null
+  chapterTitleRef.current = currentChapter?.title ?? ''
 
   // 顶栏高度量一次：菜单打开时正文下移，开头几行不被顶栏压住。
   // 用 transform 而不是 padding，避免改变视口高度触发重新分页。
@@ -758,7 +1117,10 @@ export default function ReaderViewPage() {
                 1000,
             ),
       onChange: (v: number) => {
-        if (settings.pageMode === 'page') setPage(v - 1)
+        if (settings.pageMode === 'page') {
+          commitTextPage(v - 1)
+          flushTextPageReactSync()
+        }
         else {
           const el = scrollRef.current
           if (el) el.scrollTop = (v / 1000) * (el.scrollHeight - el.clientHeight)
@@ -811,62 +1173,13 @@ export default function ReaderViewPage() {
     [book],
   )
 
-  // 正文段落块：普通段落按缩进排版，[img] 行渲染成居中图片，段评在段末挂气泡
-  const renderParagraph = (block: ReaderParagraphBlock, key: number) => {
-    const { text, comments } = block
-    if (text.startsWith(IMG_MARK)) {
-      return (
-        <p key={key} style={{ marginBottom: settings.paragraphSpacing, textAlign: 'center' }}>
-          <img
-            src={text.slice(IMG_MARK.length)}
-            alt=""
-            referrerPolicy="no-referrer"
-            style={{ maxWidth: '100%', maxHeight: '70vh', margin: '0 auto', objectFit: 'contain' }}
-          />
-        </p>
-      )
-    }
-    const standalone = text === '' && comments.length > 0
-    return (
-      <p
-        key={key}
-        style={{
-          textIndent: text ? '2em' : undefined,
-          marginBottom: settings.paragraphSpacing,
-          textAlign: standalone && comments.every((c) => c.block) ? 'center' : undefined,
-        }}
-      >
-        {text}
-        {comments.map((c, ci) => (
-          <button
-            key={`${c.line}-${ci}`}
-            type="button"
-            onClick={(e) => {
-              // 滚动容器的分区点击与翻页覆盖层都在上层，不拦住冒泡，
-              // 点气泡会顺带翻页或呼出菜单。
-              e.stopPropagation()
-              void openComment(c)
-            }}
-            title={c.label || '段评'}
-            // 外层正文档关掉了指针事件（见上面的层叠说明），气泡自己开关。
-            className="relative z-10 mx-1 inline-flex items-center gap-0.5 rounded-full border align-middle"
-            style={{
-              borderColor: theme.accent,
-              color: theme.accent,
-              fontSize: Math.max(10, settings.fontSize - 4),
-              lineHeight: 1,
-              padding: '2px 6px',
-              verticalAlign: 'middle',
-              pointerEvents: 'auto',
-            }}
-          >
-            <MessageSquare size={11} />
-            {c.count > 0 && <span>{c.count}</span>}
-          </button>
-        ))}
-      </p>
-    )
-  }
+  // 段评点击：ReaderTextPageBody 要稳定回调，否则 memo 每次都失效。
+  const handleOpenComment = useCallback(
+    (comment: ReaderContentComment) => {
+      void openComment(comment)
+    },
+    [openComment],
+  )
 
   // ── 渲染 ──
   if (error && !book) {
@@ -901,6 +1214,8 @@ export default function ReaderViewPage() {
               page={comicPage}
               imageFit={comicScrollFit}
               spread={comicDoublePage ? (comicSpreads[comicSpreadIndex] ?? null) : null}
+              draggable={comicDragSinglePage}
+              stageRef={comicStageRef}
               onZone={(zone) => {
                 if (zone === 'center') setMenuOpen((v) => !v)
               }}
@@ -926,20 +1241,27 @@ export default function ReaderViewPage() {
               style={menuShiftStyle}
             >
               <div ref={viewportRef} className="relative h-full overflow-hidden">
-                <div
-                  ref={contentRef}
-                  className="h-full"
-                  style={{
-                    columnWidth: `${Math.max(vw, 1)}px`,
-                    columnGap: `${COLUMN_GAP}px`,
-                    columnFill: 'auto',
-                    transform: `translateX(-${page * (vw + COLUMN_GAP)}px)`,
-                    transition: 'transform 220ms ease',
-                    fontSize: settings.fontSize,
-                    lineHeight: settings.lineHeight,
-                  }}
-                >
-                  {blocks.map((b, i) => renderParagraph(b, i))}
+                {/* 跟手层：跟手位移写这里；分页平移由 applyTextPageTransform 写在 contentRef 上。 */}
+                <div ref={pageDragRef} className="h-full">
+                  <div
+                    ref={contentRef}
+                    className="h-full"
+                    style={{
+                      columnWidth: `${Math.max(vw, 1)}px`,
+                      columnGap: `${COLUMN_GAP}px`,
+                      columnFill: 'auto',
+                      fontSize: settings.fontSize,
+                      lineHeight: settings.lineHeight,
+                    }}
+                  >
+                    <ReaderTextPageBody
+                      blocks={blocks}
+                      paragraphSpacing={settings.paragraphSpacing}
+                      fontSize={settings.fontSize}
+                      accent={theme.accent}
+                      onOpenComment={handleOpenComment}
+                    />
+                  </div>
                 </div>
               </div>
             </div>
@@ -963,7 +1285,13 @@ export default function ReaderViewPage() {
               style={{ fontSize: settings.fontSize, lineHeight: settings.lineHeight, ...menuShiftStyle }}
             >
               <div className="py-4">
-                {blocks.map((b, i) => renderParagraph(b, i))}
+                <ReaderTextPageBody
+                  blocks={blocks}
+                  paragraphSpacing={settings.paragraphSpacing}
+                  fontSize={settings.fontSize}
+                  accent={theme.accent}
+                  onOpenComment={handleOpenComment}
+                />
               </div>
             </div>
           )}
@@ -1005,22 +1333,51 @@ export default function ReaderViewPage() {
             原生纵向滚动（手指落在覆盖层上时找不到可滚动的祖先节点），
             所以滚动模式由正文容器的 onClick 分区（见 handleZoneTap）。 */}
         {settings.pageMode === 'page' && (contentType === 'text' || contentType === 'image') && (
-          <div className="absolute inset-0 z-[1] grid grid-cols-[30%_40%_30%]">
-            <button type="button" aria-label="上一页" onClick={goPrev} className="cursor-w-resize" />
+          <div
+            className="absolute inset-0 z-[1] grid grid-cols-[30%_40%_30%]"
+            onTouchStart={onTouchStart}
+            onTouchMove={onTouchMove}
+            onTouchEnd={onTouchEnd}
+            onTouchCancel={onTouchCancel}
+          >
+            <button
+              type="button"
+              aria-label="上一页"
+              onClick={() => {
+                if (consumeSwipe()) return
+                goPrev()
+              }}
+              className="cursor-w-resize"
+            />
             <button
               type="button"
               aria-label="菜单"
-              onClick={() => setMenuOpen((v) => !v)}
+              onClick={() => {
+                if (consumeSwipe()) return
+                setMenuOpen((v) => !v)
+              }}
               className="cursor-default"
             />
-            <button type="button" aria-label="下一页" onClick={goNext} className="cursor-e-resize" />
+            <button
+              type="button"
+              aria-label="下一页"
+              onClick={() => {
+                if (consumeSwipe()) return
+                goNext()
+              }}
+              className="cursor-e-resize"
+            />
           </div>
         )}
       </div>
 
       {/* 页脚页码（翻页模式） */}
       {settings.pageMode === 'page' && contentType === 'text' && content !== null && (
-        <div className="pointer-events-none pb-2 text-center text-2xs opacity-50" style={{ color: theme.text }}>
+        <div
+          ref={pageLabelRef}
+          className="pointer-events-none pb-2 text-center text-2xs opacity-50"
+          style={{ color: theme.text }}
+        >
           {page + 1} / {pageCount} · {currentChapter?.title ?? ''}
         </div>
       )}