4v5u09Z5a4Yuc/ReadViewSDK
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
110 Commits 2 Branches 6 Tags
e59bad9abf66e2be5023864fbf100c7edca9e061
Commit Graph
57 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
shenlei e59bad9abf PDF 阅读器新增点读热区、试读墙与阅读进度/书签持久化 
宿主的点读书场景需要在 PDF 页面上叠加可点击热区（音频/视频/网页等），并支持
试读限制与阅读进度、书签的本地保存，这些能力此前 RDPDFReaderView 均不提供，
只能由宿主在阅读器之外自行叠加视图，无法跟随 SDK 的缩放、翻页和主题渲染同步。

新增 RDPDFReaderPageInteraction 描述热区（位置、图标、边框/填充样式、点击态、
闪烁与播放边框规则、内嵌视频），由新增的 RDPDFInteractionHotspotView 负责绘制，
SVG 图标经 RDPDFReaderSVGIconLoader（基于 SDWebImage/SDWebImageSVGCoder）异步
解码后回填，避免阻塞主线程；点击事件通过 interactionHandler 回传给宿主，媒体
播放、路由等业务仍留在宿主侧。底部工具栏新增点读提示与连播按钮，状态由宿主驱动。

试读墙对齐 EPUB 侧 RDEPUBReaderTrialPolicy 的设计：以页为限制单位，可读页数在
配置了 trialPolicy 且宿主经 delegate 提供墙视图时生效，原始总页数、缩略图、目录
换算不受影响，只有传给 RDPDFReaderView 的有效页数会追加一页试读墙；翻页、目录
跳转、大纲的上界都统一收敛到可读范围，避免用户绕过热区跳转或朗读高亮跳进未授权页。

阅读进度与书签复用 RDPDFReaderPersistenceStore 已有的标注状态目录，新增
reader-state.json 承载，不需要宿主额外提供数据库表；RDPDFReaderPersistenceStore
同时实现 RDPDFReaderPersistence 协议对接这部分读写。
 2026-08-14 12:13:04 +09:00
shenlei 278072aca0 停止跟踪 Demo 的 CocoaPods 产物，改为本地 pod install 生成 
ReadViewDemo/Pods 此前整目录签入仓库，但白名单式的 .gitignore 只对 RDEpubReaderView、
RDPDFReaderView 的 Local Podspecs/Target Support Files 和 SnapKit 生效，其余第三方 pod
（DTCoreText、DTFoundation、ZIPFoundation，以及本次新增的 SDWebImage、SDWebImageSVGCoder）
反而因为父目录被显式取消忽略而绕过了全局 gitignore 的 Pods 规则，被当作普通文件跟踪，
导致每次 pod install 产生的构建产物、xcconfig、Pods.xcodeproj 都会出现在 diff 里。

改为直接忽略 ReadViewDemo/Pods 与 ReadViewDemo/Podfile.lock 整体，并 git rm --cached
移除已跟踪的文件（工作区文件不受影响）。此后 Demo 工程的依赖状态完全由 Podfile 决定，
拉取仓库后本地执行 pod install 即可重建，不再需要区分哪些 pod 目录该签入、哪些该忽略。
 2026-08-14 12:12:39 +09:00
shenlei 3e60bf1869 修复阅读器资源、朗读与持久化稳定性 
阅读器在多会话朗读、加密 EPUB 资源、并发打开同一本书和多 UserDefaults 容器等场景下，存在旧异步结果覆盖新状态、锁屏控制串会话、大型明文资源被误拒绝、解压半成品被复用及标注跨容器混用的风险；同时高亮、书签、搜索和设置面板的空状态与自动化可访问性入口不完整。\n\n本次为朗读会话引入代次和当前 utterance 校验，远程控制改为仅响应当前会话并按自身 token 清理；加密资源 provider 先判定是否实际返回解密数据，明文大资源继续流式读取；解压缓存串行化以避免并发复用未完成目录。书签与高亮迁移至受保护文件，按 UserDefaults 容器隔离命名空间，保留标准容器旧文件兼容并确保新副本成功落盘后才删除历史数据。\n\n同步调整缓存淘汰、FoundationModels 弱链接、搜索/标注/设置面板交互与 UI 测试，并更新 Pod 生成配置及 API、风险文档。已执行 git diff --check 和 ReadViewDemo Debug Simulator 构建，结果为 BUILD SUCCEEDED。
 2026-07-30 20:52:21 +09:00
shenlei e01cbc169d 修复 EPUB 与 PDF 阅读器朗读交互 
PDF 朗读的逐词回调会在同一页内持续触发高亮，原实现每次都调用翻页入口，使用户在朗读过程中反复看到页面转场。现仅在目标页变化时定位，并对朗读产生的跨页定位禁用动画，保留高亮刷新而不重复翻页。\n\nEPUB/TXT 此前只提供内容源，缺少将朗读进度回写到阅读器的会话层，无法从当前阅读位置开始朗读、随内容跨页及显示临时高亮。新增 EPUB 朗读会话，使用 href 与 UTF-16 偏移恢复位置；文本重排 EPUB 与 TXT 按实际页面定位并高亮，Web EPUB 则按章节安全定位以避免词级回调导致跳页。URL 阅读器同时提供可选会话入口，图片型阅读器保持不可朗读。\n\n已执行 ReadViewDemo 的 Debug Simulator 构建，结果为 BUILD SUCCEEDED。
 2026-07-30 18:33:04 +09:00
shenleiandClaude Opus 5 529663829f 修复退出 EPUB 阅读器后宿主侧滑返回手势被改成阅读器的配置 
阅读器在 viewWillAppear 中无条件把导航控制器的 interactivePopGestureRecognizer
接管为自己的 delegate 并强制开启，退出时却不做任何还原。宿主如果原本关闭了
侧滑返回，或为它设置过自定义 delegate，从阅读器返回后这些配置就被永久改写，
其它页面的返回手势行为随之变化。阅读器自身接管横向翻页，进入期间开启侧滑返回
也会与翻页手势争抢边缘触摸。

改为进入时记录原有的开关状态与 delegate 并直接关闭该手势，退出时按记录值还原。
记录只在首次 viewWillAppear 时进行，避免阅读器内部多次前后台切换把自己写入的
状态当成宿主原值。

该修复原本以本地补丁形式存在于 readoor 项目的 Vendor 副本中，现回流上游，避免
后续同步 SDK 时反复丢失。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-07-30 18:03:43 +09:00
shenleiandClaude Opus 5 d830311894 修复 PDF 仿真翻页模式下翻页后页面全白 
打开普通 PDF 并使用仿真翻页阅读时，除首页外每翻一页都是纯白：没有页面
内容，也没有页面四周的衬底色。横向滚动与竖滑模式不受影响。样张
英汉大词典App需求说明.pdf 上第 2 到第 9 页无一例外。

根因是页面数据回来时找不到对应的视图。UIPageViewController 会通过
viewControllerBefore/After 提前构建相邻页的内容视图，构建时页面描述尚未
就绪，configure 发起异步 readerPage 请求后先返回一张空白页。描述返回后
acceptPageDescriptor 调用 refreshVisiblePage，而它经由
RDPDFReaderView.pageContentView(pageNum:) 定位视图，该方法在仿真翻页下
只检索 nativeCurlPageController.viewControllers，也就是已经上屏的 child。
预建的 child 此时还不在其中，图片因此从未被装配上去；翻页动画结束后又
没有任何路径重新 configure 该视图，白页就固定下来。此前偶尔能看到内容，
是 OCR 完成回调顺带触发了一次刷新，并非稳定行为。

改为按页码刷新该页的全部活动视图：控制器用弱引用表记录已创建的页面视图，
refreshVisiblePage 改名为 refreshPageViews(at:)，除已上屏视图外一并装配
尚未上屏的预建视图，pageContentView 创建时即写入 tag 以便按页码匹配。
翻页落定时在 pageNum 回调中补一次装配，使内存告警清掉页面描述的场景也能
重新发起请求并恢复。另外把 image 为空的页面描述改按无效结果处理，走既有
的重试与失败重载入口，不再缓存出一张永远不会重试的白页。

新增 PDFPageTurnBlankPageTests 作为回归：翻页稳定后截屏统计画面中部深色
像素占比，白页为 0，扉页约 0.002，正文页在 0.01 以上，以 0.0005 为判定
阈值，覆盖仿真翻页正翻、仿真回翻和横向滚动三种路径。

验证：iPhone 17 Pro / iOS 26.4.1 模拟器执行 PDFPageTurnBlankPageTests、
PDFAnnotationTests、PDFDrawingModeTests、PageNavigationTests、
DisplayTypeTests 共 23 条用例，22 条通过。修复前仿真翻页第 2 到 9 页墨迹
占比全为 0.0000，修复后与横向滚动模式逐页吻合。唯一失败的
DisplayTypeTests.testDisplayTypeSwitchMidSession 属 EPUB 设置面板既有问题，
将本次改动还原后同样失败。文档补充了 Demo 因链接 FoundationModels 而必须
使用 iOS 26 及以上模拟器的说明。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-07-30 17:52:29 +09:00
shenleiandClaude Opus 5 735c14c824 隐藏 PDF Demo 阅读器中的 AI 助手入口与 TTS 朗读控件 
PDF Demo 宿主在阅读界面右上角常驻一个 "AI" 按钮，底部常驻一组 TTS 播放
控件。这两处是示例性质的能力入口，当前不希望在阅读界面上出现。

在宿主控制器上引入 showsAIAssistant 与 showsSpeechControls 两个开关，
viewDidLoad 中据此决定是否创建 AI 按钮、是否装配朗读控件，两者都不再被
加入视图层级。底层的 presentAIAssistant、speechSession 及播放、语速控制
逻辑全部保留，把开关置为 true 即可恢复，避免以后重新接入时再写一遍。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-07-30 17:51:57 +09:00
shenlei c61115cab3 更新提交git skill 2026-07-27 14:16:53 +09:00
shenlei 95cead5863 修复 PDF 阅读交互稳定性并统一项目技能管理 
PDF 阅读器在慢速双指缩放、竖向滚动页高异步更新、页面请求超时和绘画橡皮擦等场景中，存在视口跳动、迟到结果被错误丢弃、缓存边界不明确及笔迹显示与持久化不同步的问题；同一本书的标注读取和并发写入也会产生不必要的磁盘访问或覆盖风险。\n\n调整缩放 inset 计算和竖向阅读锚点恢复，避免缩放变换被重复计入、真实页高到达时改变当前阅读位置。页面请求改为带 token 的超时重试机制，可在缓存窗口内接收有效迟到结果并提供失败重试入口；页面大图、OCR、笔迹和描述缓存统一按当前页前后两页收敛，PDF 标识改为完整内容 SHA-256，避免同名或相近文件复用错误阅读状态。\n\n绘画会话内按路径实时重绘，退出会话后使用按图层派生的位图缓存，确保橡皮擦即时作用于已提交笔迹；同时为笔迹持久化增加版本控制、为标注读写增加同步保护和内存快照，降低复用与并发场景下的状态错乱。\n\n将项目技能统一迁入 .agents/skills，并以 .claude/skills 相对软链接供 Claude Code 读取；新增详细 Git 提交技能，自动审查改动、生成中文提交说明并约束安全推送。

验证：所有项目技能通过 quick_validate；执行 xcodebuild -workspace ReadViewDemo/ReadViewDemo.xcworkspace -scheme ReadViewDemo -configuration Debug -sdk iphonesimulator CODE_SIGNING_ALLOWED=NO build，构建成功。
 2026-07-24 14:40:02 +09:00
shenlei 68d9363f0a feat: optimize reader caching and document formats 2026-07-20 17:22:06 +09:00
shenleiandClaude Fable 5 1422461224 将 PDF 成品阅读控制器下沉为 RDPDFReaderView SDK，并修复手机横屏单页连续竖滑 
SDK 化收尾：
- 新增 RDPDFReaderView 本地 pod（阅读容器、成品控制器、划线/注释、画笔、
  目录/设置面板、主题与持久化契约），Demo 精简为 PDFKit 页面提供者 + 持久化宿主
- Podfile/工程接入 RDPDFReaderView 与 SnapKit，示例书改用 PDF 阅读器示例文件

手机横屏单页竖滑修复：
- cell 高度改为宽度适配后的纸张高度（sizeForItemAt + 宿主按页提供纵横比），
  纵向超出一屏的内容由外层 collectionView 连续滚动承接，不再被裁掉
- 页面内部不再开启同向嵌套的兜底竖向拖动，修复外层滚动被吞、无法滚到下一页
- 修复 applyContentSize 先评估拖动开关后写 contentSize 的顺序缺陷
- 页码按视口中心命中 cell 计算，补 didEndDragging 兜底；旋转重锚点与
  transitionToPage 改用真实布局位置
- 横竖屏同为竖滑时也重建 cell 并刷新全部可见页的适配配置
- 横屏单页点击不再跳页，只显隐工具栏；翻页交给连续竖滑

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-15 18:49:44 +09:00
shenleiandClaude Fable 5 a17164d1a9 将 PDF 注释编辑器、笔记列表、目录/设置面板与面板呈现下沉到 SDK 
SDK 新增：
- RDPDFReaderAnnotationEditorViewController：注释输入页（UI 与 EPUB 编辑器一致）
- RDPDFReaderAnnotationListViewController：笔记列表（全部/注释/高亮筛选、滑动删除）
- RDPDFReaderNavigationPanelViewController：目录/书签/缩略图面板容器
- RDPDFReaderSettingsPanelViewController：亮度/翻页方式/主题设置面板
- RDPDFReaderPanelPresenter + 转场/呈现控制器：底部面板统一呈现，
  转场代理生命周期由被呈现控制器持有，宿主无需保存引用
- RDPDFReaderThemeOption：SDK 自有主题模型，面板与编辑器不再依赖 EPUB 主题类型
- UIColor(rdPDFHexString:) 公开，并消除覆盖层内的私有重复实现

Demo 侧：
- 删除 PDFDemoAnnotationUI.swift 整个文件
- 删除 PDFDemoNavigationViewController / PDFDemoSettingsViewController /
  面板转场三个类（约 410 行），改为调用 SDK 组件
- ThemePreset 增加到 RDPDFReaderThemeOption 的映射

无障碍标识全部保留，UI 自动化不受影响。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-15 10:51:51 +09:00
shenleiandClaude Fable 5 1bde945d36 将 PDF 划线/注释交互完整下沉到 SDK 库 
- RDPDFReaderPageView：完整页面视图移入 SDK（缩放画布、文字选择层、
  选区放大镜、无障碍视口），并内置与 EPUB 一致的两套系统编辑菜单：
  选区菜单（复制/划线/注释）、已有划线菜单（复制/注释|删除注释/删除划线）
- RDPDFReaderPageViewDelegate：宿主只通过代理做数据持久化与打开业务界面
- 修复划线命中判定：点击点先归一化再与标注比例坐标比较
- 修复 tappedHighlight 残留导致选区菜单项被错误过滤的问题
- 主题应用改为纯颜色入参，SDK 不依赖 EPUB 主题类型
- RDPDFReaderHighlightOverlayView 恢复为纯绘制层，点击交互统一由页面视图处理
- Demo 删除 PDFDemoPageView（约 290 行），改为实现代理回调

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-15 10:33:43 +09:00
shenleiandClaude Haiku 4.5 5a19cfde14 refactor: move highlight menu logic from Demo to SDK library 
Add RDPDFReaderPageView as base page view class in SDK:
- Handles all highlight menu interactions and display
- Provides RDPDFReaderPageViewDelegate for menu action callbacks
- Unifies with EPUB architecture: RDEPUBTextContentView pattern
- Reduces code duplication for applications using the SDK

Benefits:
- Reusable menu interaction logic across all PDF apps
- Consistent architecture with EPUB reader
- Single responsibility principle (UI in library, persistence in app)
- Backward compatible (existing code continues to work)

Applications now implement RDPDFReaderPageViewDelegate to:
- Respond to highlight menu actions
- Handle data persistence
- Refresh UI after changes

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-07-15 10:19:54 +09:00
shenleiandClaude Haiku 4.5 7c16647306 fix: remove duplicate canPerformAction method and merge with existing implementation 
- Keep single canPerformAction method that handles both text selection menu and highlight menu
- Check tappedHighlight first, then fall back to text selection logic
- Resolves method override conflict

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-07-15 10:16:30 +09:00
shenleiandClaude Haiku 4.5 d56e99a83f add tap-on-highlight menu with copy/annotate/delete actions, matching EPUB behavior 
- Add RDPDFReaderAnnotationMenuAction and RDPDFReaderExistingHighlightMenuAction enums to PDF contracts
- Enable highlight overlay view to detect tap gestures and report tapped highlights
- Implement existing highlight menu in Demo page: copy text, add/edit annotation, delete annotation, delete underline
- Handle menu actions in PDFDemoReaderViewController to persist changes
- Ensure highlight tap detection doesn't interfere with text selection

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-07-15 10:06:02 +09:00
shenleiandClaude Haiku 4.5 fed34da246 unify PDF and EPUB reader: convert highlights to underlines, improve annotation UI, change paging from horizontal to vertical 
- Convert PDF highlights from filled rectangles to underlines matching EPUB style
- Update PDF annotation editor with EPUB-style design: gold sidebar rail, semi-transparent background, improved spacing and shadows, dark mode support
- Change PDF page-curl paging from left-right horizontal to up-down vertical: update gesture recognition and tap regions accordingly

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
 2026-07-15 10:01:23 +09:00
shenlei 72c1f8d89c 扩展顶部工具栏业务按钮能力 2026-07-13 16:16:31 +09:00
shenlei 822949f6cc 清理重复 Podfile 配置 2026-07-13 16:09:45 +09:00
shenlei 6a0a1223b1 完善阅读器主题与批注界面 2026-07-13 13:01:14 +09:00
shenlei adc24d3f36 fix: preserve images in dark reader theme 2026-07-13 12:30:14 +09:00
shenlei d7fcda345d refactor: rename RDReaderView -> RDEpubReaderView, update pod config and docs 
- Rename source module from RDReaderView to RDEpubReaderView
- Move all source files from Sources/RDReaderView/ to Sources/RDEpubReaderView/
- Update podspec: RDReaderView.podspec -> RDEpubReaderView.podspec
- Update Podfile, demo project, and CocoaPods config for new pod name
- Delete old RDReaderView pod support files from ReadViewDemo/Pods
- Add new RDEpubReaderView pod support files
- Update documentation (API ref, architecture, UML, conventions, etc.)
- Add FixedLayoutRotationTests
- Update .gitignore: exclude .DS_Store, manual unpack backups, _ssoft-output
 2026-07-10 19:44:53 +09:00
shenleiandClaude Fable 5 d5a7755702 feat: 支持加密 EPUB、试读墙、工具栏定制与朝向锁定 
- 新增 RDEPUBResourceDataProvider 解密钩子协议 + 访问登记表，收敛章节 HTML/
  图片/内联 CSS/脚注/封面/图片查看器/正文取图等读取点，scheme handler 对加密书
  禁用流式分支；新增 RDEPUBDecryptingImageAttachment 解密 DTCoreText 图片附件；
  RDEPUBReaderDependencies.live(resourceDataProvider:) 便捷注入。明文书零影响。
- 试读墙：configuration.trialPolicy + delegate epubReaderTrialWallView/
  DidReachTrialWall，UI 由宿主提供（RDEPUBReaderController+Trial）。
- 工具栏定制：RDEPUBReaderTop/BottomToolViewProtocol 协议 + dependencies 工厂注入，
  内置栏已 conform，configureTopToolView 改协议类型。
- 朝向锁定：RDEPUBMetadata.orientation（OPF rendition:orientation 主，
  iBooks display-options 兜底）+ RDEPUBReaderController+Orientation 重写支持朝向、
  打开后主动转向。

注：RDEPUBReaderController+LocationResolution / PaginationCoordinator 为本次改动前
即存在的工作区修改，一并纳入。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-10 12:25:17 +09:00
shenlei 83dfa40299 完善搜索定位与内存监测回归验证 
本次提交围绕搜索链路的稳定性、定位恢复体验以及长章节内存优化的验证能力进行了补强。

主要改动：

1. 调整阅读器搜索栏、搜索协调器与定位恢复逻辑，改善搜索结果跳转、状态同步与相关 UI 行为。

2. 补充内存探针接入点与上下文记录，便于跟踪阅读过程中的内存占用变化。

3. 更新 RDURLReaderController、ReaderContext 与工具视图相关实现，使调试与观测链路更完整。

4. 新增 MemoryFootprintTests，并同步更新 DemoReaderState 与 SearchTests，用 UI 测试覆盖搜索与内存相关回归场景。
 2026-07-09 18:46:04 +09:00
shenleiandClaude Fable 5 c4be426299 长章节内存优化 P1：章节级共享显示内容与 layouter，高亮转 overlay 
- 新增 RDEPUBChapterDisplayContentCache（LRU 2，主线程限定，控制器
  持有）：整章显示串构建时一次性注入全章主题色与暗黑图替换，配套
  共享 DTCoreTextLayouter；签名 = 章节内容对象标识 + 主题双色 +
  暗黑图配置，设置/主题变化自动失效重建
- RDEPUBTextContentView.configure 改为引用共享 entry，删除每次翻页
  的整章可变拷贝与按页属性写入
- 高亮/下划线改走 overlay decoration（高亮背景层、下划线前景层），
  移除 applyHighlightsToContent 与 render view 的属性绘制路径，
  高亮增删不再触发整章重建
- 内存警告时清空 display cache；shouldAvoidReaderPageCaching 保持
  保守（P1-4 待真机数据）

验证：编译通过；高亮/批注/选区/翻页/设置 13 项 UI 回归全过。
SearchTests 10 项失败经二分确认为先存回归（5a41066 与 e4e629a 均
复现，最后已知通过为 2026-06-08），与本次改动无关，待单独排查。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-08 16:09:40 +09:00
shenleiandClaude Fable 5 e4e629a06c 长章节内存优化 P0：每页子串改按需构造并新增内存打点 
- RDEPUBTextPage.content 由存储属性改为基于 chapterContent+contentRange
  的计算属性，三处构造点不再生成每页子串，章节缓存窗口内每章少一份
  整章文本常驻副本
- 新增 RDEPUBMemoryProbe（--demo-memory-probe 开启），在章节插入、
  每 20 次翻页、设置失效、转屏完成时输出 phys_footprint
- shouldAvoidReaderPageCaching 补注释，锁定放开前置条件为 P1-1
- 新增实施清单文档 LONG_CHAPTER_MEMORY_OPTIMIZATION_PLAN.md 并勾选 P0

验证：Demo 编译通过；UI 回归 9/9 通过（PageNavigation/
ReaderOpenClose/LargeBookOnDemand）

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-08 15:34:45 +09:00
shenlei 5a41066b66 修复 EPUB 文本分页显示错位并补充分页调试能力 
本次提交围绕 DTCoreText 文本页的分页一致性、交互索引和高亮命中进行了集中修复。

主要改动：

1. 文本页显示改为基于整章 attributed string 的上下文布局，只对当前页 range 进行渲染，避免页面子串重新换行导致的页末断行偏差。

2. 页面布局快照与交互控制器统一改为使用 chapter-absolute 索引，修正点击、选区、菜单锚点与高亮矩形在整章上下文下的定位。

3. 修复跨章节高亮串页问题，并调整文本页高亮命中逻辑：保留 CoreText 层绘制，点击时按高亮真实 rect 精确命中，避免重复绘制和整行误判。

4. 收紧 reader 级页面缓存策略，避免预加载同时持有多份整章显示副本带来的内存放大。

5. 新增分页边界校验器、垂直对齐器和 settings-flip 自动化调试入口，用于复现与诊断页范围/显示度量不一致问题。

6. 放宽 inline attachment 的 avoid-break 处理，并补充相关分页问题调查文档与索引。
 2026-07-08 14:27:36 +09:00
shenleiandClaude Fable 5 d0efe3f2cc 安全区域改为从 key window 动态获取 
- 新增 RDEPUBSafeArea：参考 GKNavigationBarSwift 的 keyWindow 三级查找与临时 window 兜底
- 移除 reflowableContentInsets 中 top/bottom 40 的固定默认值，改按设备真实安全区生成
- 各取安全区处的 ?? .zero 兜底改为回退到 key window 值
- DEBUG 构建下为文本可读区域绘制红色边框，方便查看排版范围

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-06 15:04:22 +09:00
shenleiandClaude Fable 5 ca408c20ab 收紧脚注图的 alt 兜底判定 
原判定 alt 非空即视为脚注图,导致带 alt 的正常插图(如凡人修仙传的
logo)被缩到一个字号大小。改为 alt 长度达到脚注正文量级(≥8 字符)
且原图为小图标(≤50pt)双条件同时成立才走脚注缩放,与 HTML 归一化
层只认 qqreader-footnote class 的口径对齐。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-06 12:16:53 +09:00
shenleiandClaude Fable 5 5ae7823ef8 全量换表前用旧页表回环验证当前位置 
初始 partial 窗口被全书页表接管时,live 页码(窗口坐标)与新表解析
页码(全书坐标)不可比,±1 启发式误判后 preserveLivePage 会把模型
位置钉在全书第 1 页,导致位置错乱并级联阻塞后续全表提交。改为换表
前先用旧表解析 currentLocation:回环等于 live 页说明位置忠实反映
屏幕内容,换表后无条件信任新表解析结果;不等时才退回 ±1 门槛,保留
对 stale 持久化位置的防护。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-06 11:56:22 +09:00
shenleiandClaude Fable 5 bd6e915fbd 邻接窗口淘汰不再清除前瞻预取章节 
scheduleAdjacentChapterPrefetches 的窗口外淘汰会把
maybePrefetchUpcomingChapters 刚预取的后续章节清掉,下一次
prepare 又触发重建,形成"淘汰-重建"循环。淘汰时保留当前章之后
lookahead 范围内的章节,lookahead 数量提为共享常量。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-06 11:56:22 +09:00
shenleiandClaude Fable 5 7132e4952b 章节加载器补充三级缓存命中日志 
loadChapterWithSnapshot 打印内存章节 HIT、并发加载合流、构建来源
(memoryPageCount/diskSummary/fullRender)与构建耗时,便于判断章节
跳转时预加载与缓存的命中情况。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-06 11:34:02 +09:00
shenleiandClaude Fable 5 f796823db8 预加载控制器补充页面视图缓存命中日志 
pageViewForDisplay / prime / takePreloadedView 三条取视图路径打印
HIT/MISS 及视图地址,invalidate 打印被清空的缓存页码,便于排查
翻页时页面视图是否命中缓存。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-06 11:22:09 +09:00
shenleiandClaude Fable 5 47fe2dc450 页表全量接管改为按子集覆盖判定 
fullReplace 从"候选章节数 >= 当前章节数"改为"候选页表必须覆盖当前窗口
的全部章节",避免跳章后 partial map 数量达标但缺少远端已映射章节时,
全量替换丢弃这些条目导致总页数抖动。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
 2026-07-06 11:14:48 +09:00
shenlei 71f4feb12f Ignore local build caches 2026-07-03 16:13:50 +09:00
shenlei 99bdc98895 Fix reader interaction and web resource handling 2026-07-03 16:12:11 +09:00
shenleiandClaude 22e7e44220 feat: chapter runtime refactoring and related updates 
- Refactor chapter runtime: replace window coordinator/snapshot with warmup orchestrator
- Update EPUB core: parser, reading session, JS bridge, navigator layout
- Update reader controller: data source, location resolution, persistence
- Update chapter runtime: data cache, loader, runtime store, disk cache, warmup orchestrator
- Remove deprecated navigation state machine and pagination state
- Update text rendering: book cache, HTML normalizer
- Update UI: text content view, dark image adjuster, text selection controller
- Update settings and reader configuration
- Add CODE_REVIEW.md and AUDIT_FINAL.md documentation
- Update pod dependencies (remove SSAlertSwift, SnapKit)
- Update podspec and pod configuration files

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-26 18:50:07 +09:00
shenleiandClaude b8aa10c535 Add diagnostic logs for total pages not updating investigation 
Add RDEPUBBackgroundTrace.log at key decision points in the
reconciliation pipeline to trace why pageMap updates get rejected:

1. refreshBookPageMapInPlace — logs when a full pageMap update is enqueued
2. evaluateTakeover — logs when keepCurrentWindow is returned due to:
   - jumpSession coverage ratio < 0.8
   - adjacent coverage missing (hasPrev/hasNext)
   - renderSignature mismatch
3. evaluateFullPageMapTakeover — logs when keepCurrentWindow is returned due to:
   - currentSpineIndex not in candidate chapters
   - adjacent coverage missing
4. commitPendingPageMapUpdate — logs when keepCurrentWindow decision is
   applied and pending update is removed from queue

Also fix unused variable warning for currentPageNumber in extendPartial case.

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-25 18:57:16 +08:00
shenleiandClaude 15b15d0e11 Remove all RDEPUBBackgroundTrace.log and bare print diagnostic calls 
Keep only the evaluateFullPageMapTakeover: fullReplace diagnostic log
in RDEPUBPageMapReconciliationCoordinator.swift for future debugging.

Simplified RDEPUBBackgroundTrace to just the log method (removed measure
and debug gating). Removed all [EPUB][...], [ReadViewDemo], and
[EPUB][Pagination] print statements across the project.

Also includes earlier bug fixes:
- Fix stale currentPageNumber in extendPartial commit
- Fix pageCurl rebindVisiblePage during transition
- Fix keepCurrentWindow not removing pending update from queue
- Fix right-aligned text (巫鸿 bug) via avoidPageBreakInside,
  tail merger, and continuation paragraph normalization
- Add text-indent reset for aligned blocks in CSS compatibility layer

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-25 18:25:22 +08:00
shenleiandClaude 8c5059e72f chore: RDEPUBBackgroundTrace 日志默认关闭 
Release 构建下完全静默（isEnabled 固定 false），
Debug 构建下通过 _enabled 开关控制，默认开启。

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-25 17:36:28 +08:00
shenleiandClaude 2fa58b1026 diag: 总页数未更新问题 — 增加Reconciliation诊断日志 + 修复keepCurrentWindow后pending不移除 
1. RDEPUBPageMapReconciliationCoordinator: 在evaluateTakeover、
   evaluateSegmentTakeover、evaluateFullPageMapTakeover的每个返回点
   增加RDEPUBBackgroundTrace日志，记录关键决策参数：
   - currentSpineIndex、candidateChapters/pages、currentChapters/pages
   - hasPrev/hasNext、lastBuildableSpineIndex
   - jumpSession protected coverage ratio
   用于确认fullMap被拒绝的具体原因

2. RDEPUBPresentationRuntime: .keepCurrentWindow分支增加
   removePendingPageMapUpdate(at: index)，防止被拒绝的
   reconcileFullMap update无限期留在pending队列中不被消费。
   之前return false不移除，导致：
   - 后续commitPendingPageMapUpdateIfNeeded重试时条件不变
     仍然keepCurrentWindow，形成无效循环
   - 如果用户不再翻页，总页数永远不更新

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-25 17:33:16 +08:00
shenleiandClaude c555329948 fix: pageCurl翻页后偶尔刷新回章节第一页 
根因：.extendPartial pageMap更新提交时使用了异步扩展开始时捕获的
currentPageNumber/currentLocation，在pageCurl模式下用户可能已经翻了几页，
导致过时值通过transitionToPage把用户拉回旧位置。

修复三点：
1. PresentationRuntime: .extendPartial fallback不再使用捕获的
   currentPageNumber，改用readerView.currentPage实时值
2. ChapterWarmupOrchestrator: 异步加载完成回调中使用实时位置
   (readerView.currentPage + locationCoordinator.currentVisibleLocation())
   而非异步开始时捕获的旧值
3. PresentationRuntime: rebindVisiblePage在pageCurl模式下，
   如果正在翻页动画中(isPageCurlTransitioning)，延迟到动画结束后
   再用实时currentPage执行transitionToPage，避免在pageNum回调栈
   内同步触发transitionToPage导致重入

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-25 16:52:38 +08:00
shenleiandClaude d7f28c3f10 fix: 修复右对齐短文本显示不完整及多项功能改进 
右对齐文本显示修复（如"巫鸿"只显示"鸿"的问题）:
- RDEPUBChapterTailNormalizer: 短尾页合并时检查 avoidPageBreakInside 语义，
  避免将带有此标记的短文本（如 right-info 署名）错误合并回上一页
- RDEPUBTextContentView: 续段归一化时跳过右对齐/居中对齐的段落，
  防止错误修改 firstLineHeadIndent 导致首字不可见
- RDEPUBCSSCompatibilityLayer: 为含 text-align:right/center 的 CSS 块
  自动注入 text-indent:0 !important，确保右对齐/居中文本无首行缩进
- RDEPUBTextRendererSupport: 排版属性归一化时将右对齐/居中段落的
  firstLineHeadIndent 重置为 0

图片查看器及脚注点击功能:
- 新增 RDEPUBImageViewController 和 RDEPUBImageViewerCoordinator，
  支持从 WebView 和 TextPage 两种模式查看图片
- epub-bridge.js: 检测图片和脚注图片的点击事件，脚注图片显示弹窗
- RDEPUBJavaScriptBridge: 新增 imageDidTap/footnoteDidTap 桥接消息
- RDEPUBWebView: 新增图片和脚注点击的 delegate 方法
- RDEPUBAttachmentNormalizer: 改进脚注检测，优先使用 alt 文本判断
- RDEPUBPaginationModels: 新增 .footnote 附件类型
- RDEPUBPageLayoutSnapshot: 运行时动态解析附件类型，脚注优先级高于图片

位置解析改进:
- RDEPUBReaderController+LocationResolution: 利用 rangeInfo 提升页码定位精度

其他:
- RDEPUBTextBookCache: schema 版本升级至 13
- RDEPUBReaderTheme: 主题更新
- Pod 项目文件更新

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-25 15:39:58 +08:00
shenleiandClaude d15f20b097 feat: 交互协调器拆分、附件提示、暗色图片适配、选区放大镜及文档清理 
- 拆分 ContentDelegates/TextContentView 为独立协调器（InteractionCoordinator、LocationResolution、ExternalLinks、AttachmentTooltip）
- 新增 RDEPUBAttachmentTooltipView/OverlayView 附件气泡提示
- 新增 RDEPUBDarkImageAdjuster 暗色模式图片亮度适配
- 新增 RDEPUBSelectionLoupeView 选区放大镜
- 新增 MetadataParseWorker/CancellationController 元数据解析取消机制
- 重构 PresentationRuntime/PaginationCoordinator 精简职责
- 优化 ChapterLoader/WarmupOrchestrator 异步章节加载
- CFI 模块微调与 NoteModels 更新
- 清理冗余文档，更新架构/UML/业务逻辑文档

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-24 17:47:24 +08:00
shenlei c65c190b71 feat: EPUB阅读器搜索、注释、CFI模块及大书远距跳转优化 
- 实现EPUB阅读器搜索功能及选中注释功能
- 优化CFI模块，修复代码审查发现的11个问题
- 实现大书远距目录跳转与后台补全优化方案
- 优化设置面板与章节运行时联动
- 重构及大量改进优化
 2026-06-22 20:26:34 +08:00
shenleiandClaude f50495ad91 fix: CFI module — 11 issues from code review 
Phase 1 (correctness):
- #1: rawValue changed from stored to computed property, eliminating stale cache risk
- #2: tokenSamples/textMarker unified to UTF-16 offsets, fixing emoji/CJK positioning
- #3: makeOffsetCFI now accepts optional contentPath parameter

Phase 2 (robustness):
- #4: Resolver uses fixed index access instead of last(where:) for manifest/spine steps
- #5: HTML comments and CDATA stripped before regex matching
- #6: Text assertion parser handles backslash escapes (\[ \] \)
- #7: Token matching uses prefix/suffix with length ratio constraints
- #8: makeOffsetRangeCFI validates startOffset <= endOffset

Phase 3 (code quality):
- #9: Shared internal nilIfEmpty extension in RDEPUBCFIUtilities.swift
- #10: RDEPUBCFIMap has markerByPath index dictionary for O(1) lookup
- #11: parseRange unified to use try (not try?) for parent parsing

Review fixes:
- Documented init(rawValue:) parameter is ignored (computed property)
- Fixed escape unescaping to handle \\ → \ correctly
- Lowered token minLength threshold from 4 to 2

Co-Authored-By: Claude <noreply@anthropic.com>
 2026-06-18 13:25:17 +08:00
shenleiandClaude Opus 4.7 6ed3fcb071 feat: 设置面板与章节运行时联动优化 
- 设置页打开时仅重新计算当前章节预览，关闭后触发完整补全
- 新增 preview 加载优先级，支持设置页内当前章预览
- 添加设置页防抖机制，合并连续字号/行距变更
- 支持下滑手势关闭设置页，通过 presentation delegate 通知运行时
- 重新分页时跳过导航和尺寸校验，避免状态冲突
- currentTextPageSize 线程安全优化，后台线程使用缓存尺寸
- 更新 CocoaPods 依赖

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-17 09:47:50 +08:00
shenleiandClaude Opus 4.7 c64460988a feat: 实现大书远距目录跳转与后台补全优化方案 
Phase 1: 稳定性优先
- 新增 RDEPUBJumpSession 保护机制，防止远距跳转后翻页串章
- 升级页图接管条件，增加 JumpSession 保护区检查
- 窗口扩展改为基于当前权威窗口方向

Phase 2: 补全优先级重排
- 新增 RDEPUBBackgroundPriorityPolicy 策略配置
- 实现 hot/warm/cold zone 优先级排序
- 添加失败重试机制（指数退避，最多3次）

Phase 3: 分段覆盖与最终收敛
- 新增 RDEPUBBackgroundCoverageStore 分段存储
- 新增 RDEPUBPageMapReconciliationCoordinator 页图接管仲裁
- 实现 LRU 淘汰和内存警告处理

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-15 16:28:11 +08:00
shenleiandClaude Opus 4.7 e976ceebd5 chore: add .artifacts/ to .gitignore 
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-15 08:38:09 +08:00
shenleiandClaude Opus 4.7 ed390da147 feat: unify reader chrome state management 
- Add RDEPUBReaderUIState struct for centralized UI state model
- Refactor RDEPUBReaderChromeCoordinator with makeUIState() and applyUIState()
- Remove direct UI updates from RDEPUBReaderAnnotationCoordinator
- Consolidate updateBookmarkChrome() into updateReaderChrome()
- Update RDEPUBReaderContext, Runtime, and LocationCoordinator
- Add reader problem fix development checklist documentation

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-12 17:51:08 +08:00
shenlei d15187b730 Reorganize docs and update reader search flows 2026-06-10 08:22:07 +08:00
shenleiandClaude Opus 4.7 0e7c0577e3 feat: add in-reader search and restructure documentation 
- Add RDEPUBReaderSearchBarView with animated show/hide, keyword
  navigation, and match counting integrated into the reader controller
- Restructure docs: replace scattered design docs with consolidated
  BUSINESS_LOGIC.md and UML_CLASS_DIAGRAMS.md; update ARCHITECTURE.md
- Add SearchTests and FanrenParseTimeTest; enhance LargeBookOnDemandTests
- Add scripts/run_ui_regression.sh and summarize_ui_results.py for
  automated UI test execution and reporting

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-05 17:34:50 +08:00
shenlei feb05eaf87 feat: complete large-book pagination runtime and UI coverage 2026-06-03 17:47:16 +08:00
shenleiandClaude Opus 4.7 9801af05d3 test: 增强 UI 测试基础设施与阅读器自动化测试 
- 新增 BookmarkTests/PageNavigationTests/TableOfContentsTests 等阅读器功能测试
- 扩展 AccessibilityIdentifiers 支持更多 UI 元素定位
- XCUIApplication+Launch: 增加启动参数支持（reset state、自定义书籍）
- ReaderAnnotationTests: 完善标注测试覆盖
- ViewController: 支持 --demo-reset-state 参数清理持久化状态
- 新增凡人修仙传测试样本

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-02 21:17:04 +08:00
shenleiandClaude Opus 4.7 c76beed03c feat(reader): 实现大书快速进入与增量分页路径 
- PaginationCoordinator: 新增 textReflowable 快速进入路径，支持增量章节构建
  与 staged 合并策略，避免整书一次性构建的主线程阻塞
- TextBookBuilder: 重构为支持单章构建与增量合并模式
- ChapterPageCounter: 优化分页计数逻辑，支持章节级分页缓存
- PageFrameFactory: 新增 CoreText 页面帧工厂，提升排版性能
- ReaderContext/ReaderRuntime: 适配增量分页状态管理

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-02 21:16:57 +08:00
shenleiandClaude Opus 4.7 488350d956 docs: 大书优化方案文档与架构分析更新 
新增大书优化实施方案（内存与主线程、快速进入阅读器）和 WXRead 内存策略分析文档，
更新架构对比分析文档，完善章节级缓存运行时、串行加载、轻量磁盘摘要等设计细节。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-02 21:16:50 +08:00
shenleiandClaude Opus 4.7 70133e4e6e refactor(reader): 重构高亮选区绘制架构，对齐 WXRead 实现方案 
- 移除 RDEPUBSelectableTextView，改用原生 UITextView
- 新增 NSAttributedString 自定义属性（com.rdreader.highlight/underline）注入高亮
- RDEPUBTextPageRenderView 统一绘制高亮背景、文字和选区
- RDEPUBTextSelectionController 精简，选区矩形传递给 RenderView 绘制
- 新增高亮选区复刻 WXRead 实现方案文档
- UI 测试适配新架构

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-01 20:57:27 +08:00