feat(epub): complete wxread parity scope

Sources/RDReaderView/EPUBTextRendering/RDEPUBChapterData.swift

@@ -30,8 +30,19 @@ public final class RDEPUBChapterData {
     public var attributedContent: NSAttributedString { chapter.attributedContent }
     /// 分页后的页面列表
     public var pages: [RDEPUBTextPage] { chapter.pages }
+    /// 章节总页数
+    public var pageCount: Int { chapter.pages.count }
     /// fragment ID → 字符偏移量的映射表（用于锚点定位）
     public var fragmentOffsets: [String: Int] { chapter.fragmentOffsets }
+    /// 章节信息快照（供阅读会话/目录面板复用）
+    public var chapterInfo: EPUBChapterInfo {
+        EPUBChapterInfo(spineIndex: spineIndex, title: title, pageCount: pageCount)
+    }
+    /// 章节覆盖的绝对页码范围（闭区间）
+    public var absolutePageRange: ClosedRange<Int>? {
+        guard let firstPage = pages.first, let lastPage = pages.last else { return nil }
+        return firstPage.absolutePageIndex...lastPage.absolutePageIndex
+    }
 
     // MARK: - 页面查询
 
@@ -52,20 +63,36 @@ public final class RDEPUBChapterData {
         chapter.pages.first { $0.absolutePageIndex == absolutePageIndex }
     }
 
+    /// 按章节内页码查找页面（从 1 开始）
+    public func page(atPageNumber pageNumber: Int) -> RDEPUBTextPage? {
+        guard pageNumber > 0, pages.indices.contains(pageNumber - 1) else { return nil }
+        return pages[pageNumber - 1]
+    }
+
     // MARK: - 锚点与位置映射
 
-    /// 将绝对字符索引转换为语义锚点（fileIndex/row/column 三元组）
+    /// 将章节内字符索引转换为语义锚点（fileIndex/row/column 三元组）
     public func anchor(forAbsoluteIndex index: Int) -> RDEPUBTextAnchor {
         indexTable.anchor(forAbsoluteIndex: index, in: chapter)
     }
 
-    /// 将绝对字符范围转换为起止锚点对
+    /// 将全书字符索引转换为语义锚点。
+    public func anchor(forGlobalIndex index: Int) -> RDEPUBTextAnchor? {
+        indexTable.anchor(forGlobalIndex: index)
+    }
+
+    /// 将章节内字符范围转换为起止锚点对
     public func rangeAnchor(for absoluteRange: NSRange) -> RDEPUBTextRangeAnchor {
         let start = anchor(forAbsoluteIndex: absoluteRange.location)
         let end = anchor(forAbsoluteIndex: absoluteRange.location + absoluteRange.length)
         return RDEPUBTextRangeAnchor(start: start, end: end)
     }
 
+    /// 将锚点范围转换为全书字符范围。
+    public func globalRange(for rangeAnchor: RDEPUBTextRangeAnchor) -> NSRange {
+        indexTable.globalRange(for: rangeAnchor)
+    }
+
     /// 从绝对字符范围构建选区对象（用于复制/高亮分享）
     /// - Parameters:
     ///   - absoluteRange: 选区在全书中的字符范围
@@ -102,9 +129,21 @@ public final class RDEPUBChapterData {
         location(for: page.contentRange, bookIdentifier: bookIdentifier)
     }
 
+    /// 根据持久化位置定位所属页面。
+    public func page(for location: RDEPUBLocation) -> RDEPUBTextPage? {
+        guard let range = absoluteRange(for: location) else { return nil }
+        return page(containing: range.location)
+    }
+
+    /// 根据搜索结果定位所属页面。
+    public func page(for searchMatch: RDEPUBSearchMatch) -> RDEPUBTextPage? {
+        guard let range = absoluteRange(for: searchMatch) else { return nil }
+        return page(containing: range.location)
+    }
+
     // MARK: - 位置反向解析（Location → 绝对偏移量）
 
-    /// 将持久化位置还原为章节内的绝对字符范围。
+    /// 将持久化位置还原为章节内的字符范围。
     ///
     /// 解析优先级：
     /// 1. rangeAnchor（锚点定位，最精确）
@@ -112,7 +151,7 @@ public final class RDEPUBChapterData {
     /// 3. navigationProgression（进度百分比回退）
     public func absoluteRange(for location: RDEPUBLocation) -> NSRange? {
         if let rangeAnchor = location.rangeAnchor {
-            return indexTable.absoluteRange(for: rangeAnchor)
+            return indexTable.chapterRange(for: rangeAnchor)
         }
 
         if let fragment = location.fragment,
@@ -128,7 +167,7 @@ public final class RDEPUBChapterData {
     /// 从高亮的持久化位置还原绝对字符范围
     public func absoluteRange(for highlight: RDEPUBHighlight) -> NSRange? {
         if let rangeAnchor = highlight.location.rangeAnchor {
-            return indexTable.absoluteRange(for: rangeAnchor)
+            return indexTable.chapterRange(for: rangeAnchor)
         }
         return RDEPUBTextOffsetRangeInfo.decode(from: highlight.rangeInfo)?.nsRange
     }
@@ -136,7 +175,7 @@ public final class RDEPUBChapterData {
     /// 从搜索结果还原绝对字符范围
     public func absoluteRange(for searchMatch: RDEPUBSearchMatch) -> NSRange? {
         if let rangeAnchor = searchMatch.rangeAnchor {
-            return indexTable.absoluteRange(for: rangeAnchor)
+            return indexTable.chapterRange(for: rangeAnchor)
         }
         if let location = searchMatch.rangeLocation {
             return NSRange(location: location, length: searchMatch.rangeLength)
@@ -144,6 +183,42 @@ public final class RDEPUBChapterData {
         return nil
     }
 
+    /// 将持久化位置还原为全书字符范围。
+    public func globalRange(for location: RDEPUBLocation) -> NSRange? {
+        if let rangeAnchor = location.rangeAnchor {
+            return indexTable.globalRange(for: rangeAnchor)
+        }
+        guard let chapterRange = absoluteRange(for: location),
+              let chapterStart = indexTable.chapterStartOffset(forFileIndex: spineIndex) else {
+            return nil
+        }
+        return NSRange(location: chapterStart + chapterRange.location, length: chapterRange.length)
+    }
+
+    /// 从高亮的持久化位置还原全书字符范围。
+    public func globalRange(for highlight: RDEPUBHighlight) -> NSRange? {
+        if let rangeAnchor = highlight.location.rangeAnchor {
+            return indexTable.globalRange(for: rangeAnchor)
+        }
+        guard let chapterRange = absoluteRange(for: highlight),
+              let chapterStart = indexTable.chapterStartOffset(forFileIndex: spineIndex) else {
+            return nil
+        }
+        return NSRange(location: chapterStart + chapterRange.location, length: chapterRange.length)
+    }
+
+    /// 从搜索结果还原全书字符范围。
+    public func globalRange(for searchMatch: RDEPUBSearchMatch) -> NSRange? {
+        if let rangeAnchor = searchMatch.rangeAnchor {
+            return indexTable.globalRange(for: rangeAnchor)
+        }
+        guard let chapterRange = absoluteRange(for: searchMatch),
+              let chapterStart = indexTable.chapterStartOffset(forFileIndex: spineIndex) else {
+            return nil
+        }
+        return NSRange(location: chapterStart + chapterRange.location, length: chapterRange.length)
+    }
+
     // MARK: - 高亮/搜索结果与页面的交叉查询
 
     /// 获取指定页面上出现的所有高亮
@@ -163,7 +238,6 @@ public final class RDEPUBChapterData {
 
     /// 获取指定页面上出现的所有搜索匹配结果
     public func searchMatches(on page: RDEPUBTextPage, from matches: [RDEPUBSearchMatch]) -> [RDEPUBSearchMatch] {
-        let pageRange = absoluteOffsetRange(for: page)
         return matches.filter { match in
             guard match.href == chapter.href else { return false }
             if let range = absoluteRange(for: match) {
@@ -173,12 +247,54 @@ public final class RDEPUBChapterData {
         }
     }
 
+    /// `searchMatches(on:from:)` 的别名；保持和文档/WXRead 语义一致。
+    public func searchResults(on page: RDEPUBTextPage, from matches: [RDEPUBSearchMatch]) -> [RDEPUBSearchMatch] {
+        searchMatches(on: page, from: matches)
+    }
+
     /// 根据持久化位置获取对应页码（从 1 开始），用于阅读进度跳转
     public func pageNumber(for location: RDEPUBLocation) -> Int? {
-        if let range = absoluteRange(for: location) {
-            return pageNumber(containing: range.location).map { $0 + 1 }
+        guard let page = page(for: location) else { return nil }
+        return page.absolutePageIndex + 1
+    }
+
+    /// 根据搜索结果获取对应页码（从 1 开始）。
+    public func pageNumber(for searchMatch: RDEPUBSearchMatch) -> Int? {
+        guard let page = page(for: searchMatch) else { return nil }
+        return page.absolutePageIndex + 1
+    }
+
+    // MARK: - 目录与章节语义
+
+    /// 判断某个 TOC 条目是否属于当前章节。
+    public func contains(
+        tableOfContentsItem item: EPUBTableOfContentsItem,
+        normalizer: (String) -> String?
+    ) -> Bool {
+        guard let chapterHref = normalizer(href),
+              let itemHref = normalizer(item.href.components(separatedBy: "#").first ?? item.href) else {
+            return false
         }
-        return nil
+        return chapterHref == itemHref
+    }
+
+    /// 过滤出当前章节命中的目录条目。
+    public func tableOfContentsItems(
+        from items: [EPUBTableOfContentsItem],
+        normalizer: (String) -> String?
+    ) -> [EPUBTableOfContentsItem] {
+        items.flatMap { item -> [EPUBTableOfContentsItem] in
+            let descendants = tableOfContentsItems(from: item.children, normalizer: normalizer)
+            return contains(tableOfContentsItem: item, normalizer: normalizer) ? [item] + descendants : descendants
+        }
+    }
+
+    /// 当前章节最合适的目录条目（通常取命中的首个最近条目）。
+    public func primaryTableOfContentsItem(
+        from items: [EPUBTableOfContentsItem],
+        normalizer: (String) -> String?
+    ) -> EPUBTableOfContentsItem? {
+        tableOfContentsItems(from: items, normalizer: normalizer).first
     }
 
     // MARK: - 私有工具方法
@@ -190,12 +306,8 @@ public final class RDEPUBChapterData {
         return lowerBound..<max(upperBound, lowerBound)
     }
 
-    /// 将语义锚点转换为绝对字符偏移量，若索引表无法解析则回退到 chapterOffset
+    /// 将语义锚点转换为章节内字符偏移量，若索引表无法解析则回退到 chapterOffset
     private func absoluteOffset(for anchor: RDEPUBTextAnchor) -> Int {
-        indexTable.absoluteIndex(
-            fileIndex: anchor.fileIndex,
-            row: anchor.row,
-            column: anchor.column
-        ) ?? anchor.chapterOffset
+        indexTable.chapterOffset(for: anchor)
     }
 }