PDF 阅读器新增点读热区、试读墙与阅读进度/书签持久化

宿主的点读书场景需要在 PDF 页面上叠加可点击热区（音频/视频/网页等），并支持
试读限制与阅读进度、书签的本地保存，这些能力此前 RDPDFReaderView 均不提供，
只能由宿主在阅读器之外自行叠加视图，无法跟随 SDK 的缩放、翻页和主题渲染同步。

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

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

阅读进度与书签复用 RDPDFReaderPersistenceStore 已有的标注状态目录，新增
reader-state.json 承载，不需要宿主额外提供数据库表；RDPDFReaderPersistenceStore
同时实现 RDPDFReaderPersistence 协议对接这部分读写。

Sources/RDPDFReaderView/RDPDFReaderView.podspec

@@ -11,7 +11,10 @@ Pod::Spec.new do |s|
   s.license       = "MIT"
   s.source_files  = "{Sources,ReaderView}/**/*.swift"
   s.dependency    "SnapKit", "~> 5.7"
-  s.frameworks    = "Vision", "CoreImage", "PDFKit"
+  # 点读热区的 SVG 图标与 GIF 背景图依赖 SDWebImage 解码链。
+  s.dependency    "SDWebImageSVGCoder", "~> 1.8"
+  s.dependency    "SDWebImage", "~> 5.17"
+  s.frameworks    = "Vision", "CoreImage", "PDFKit", "AVKit"
   s.requires_arc  = true
 
   s.subspec "Speech" do |speech|

Sources/RDPDFReaderView/README.md

@@ -56,3 +56,7 @@ navigationController?.pushViewController(RDPDFReaderDebugViewController(), anima
 3. OCR 也不可用时，文字层会提供区域框选；区域标注只显示“高亮、注释”，不会错误地提供复制。
 
 高亮与注释统一使用 `RDPDFReaderAnnotation`，坐标同样是相对图片的 `0...1` 比例，缩放、旋转或重新渲染页面后仍能对齐。使用 `RDPDFReaderPersistenceStore` 保存时，请传入宿主稳定的书籍 ID（可附账号和内容版本）对应的目录，并对 `addAnnotation`、`updateAnnotation`、`deleteAnnotation` 的 `throws` 结果做错误提示；文件损坏或版本不兼容时 SDK 会拒绝覆盖原数据。
+
+## 点读热区
+
+宿主可在 `RDPDFReaderPageDescriptor` 中传入 `interactions`，SDK 负责绘制 SVG 图标、背景图与播放反馈；点击事件通过 `RDPDFReaderViewController.interactionHandler` 回传，媒体播放、网页或路由仍由宿主处理。页面资源异步补齐后，调用 `reloadPageContent(at:)` 刷新指定页；播放状态可通过 `setActiveInteraction(identifier:)` 更新。

Sources/RDPDFReaderView/ReaderView/RDPDFReaderView+Paging.swift

@@ -28,6 +28,15 @@ extension RDPDFReaderView {
     }
 
     func configureInteraction(for view: UIView) {
+        // 试读墙页是普通 UIView，不需要 RDPDFReaderPageInteractable 带的
+        // 缩放/文本选中能力，只需要点击→显隐工具条，单独走一条更轻量的路径。
+        if let wall = view as? RDPDFTrialWallContainerView {
+            wall.contentTapHandler = { [weak self, weak view] point in
+                guard let self, let view else { return }
+                self.handleContentTap(view.convert(point, to: self))
+            }
+            return
+        }
         guard let page = view as? RDPDFReaderPageInteractable else { return }
         // 所有阅读模式统一由 ReaderView 决定何时进入独立放大层；页面本身不再
         // 各自接管 pinch/double-tap，避免横屏左右页出现两套缩放坐标。

Sources/RDPDFReaderView/Sources/RDPDFInteractionHotspotView.swift

@@ -0,0 +1,383 @@
+import UIKit
+import SDWebImage
+import AVKit
+
+/// 单个点读热区的渲染视图。
+///
+/// 绘制规则逐条对齐旧版 OC 阅读器：
+/// - 样式层（边框 + 填充）：`RBCoreMediaLinkPaper`。填充与边框各自用 0~100 的
+///   opacity，线宽极细；静止态**恒为隐藏**，只留图标/背景图——这是新点读书的
+///   默认表现，边框并不常显。`flickerCount > 0` 时进入页面会先闪烁 N×2 次再回到
+///   隐藏；`flickerCount <= 0` 时没有这段闪烁过程，直接保持隐藏（工具栏"点读
+///   提示"按钮同理，`flickerCount <= 0` 的热区点击无反应）。
+/// - SVG 图标：`RBCoreMediaIconController` 的 bgIcon 分支。边长 = `min(w, h) × iconRate`，
+///   在热区内居中、aspectFit，且**不随热区旋转**。
+/// - 背景图：同文件的 bgImg 分支。铺满热区、aspectFit，**整体随热区旋转**。
+/// - 嵌入视频（`ShowEmbedVideo`）：`RBCoreVideoViewController` 的行内播放器分支，
+///   走完全独立的渲染/命中路径，不画边框/填充/图标，见 `setupEmbedVideoPoster`。
+///   播放前是不透明黑色背景 + 居中播放按钮，对齐 `RBCoreVideoView.xib` 里
+///   `videoPlayView`（`darkTextColor`）+ `videoCoverImageView`（纯黑 `alpha=1`，
+///   未加载到封面图时的默认表现）+ 固定 60×60 的 `videoPlay.png` 播放按钮。
+final class RDPDFInteractionHotspotView: UIView {
+
+    var onTap: (() -> Void)?
+
+    private let interaction: RDPDFReaderPageInteraction
+    private(set) var isActive: Bool
+    /// 供宿主按 identifier 定位热区，切换激活态时只更新受影响的这一个视图。
+    var interactionIdentifier: String { interaction.identifier }
+    /// 边框与填充所在的层。OC 用一整块 CALayer 画所有 link，这里按热区拆分，
+    /// 便于单独控制闪烁与激活态。
+    private let styleView = UIView()
+    /// 点击瞬时反馈层，对齐 OC `RBCoreAudioHoverPaper`：150ms 后自动移除。
+    private let hoverFlashView = UIView()
+    /// `SDAnimatedImageView` 对静态图与 GIF 表现一致，帧数 > 1 时自动播放动图，
+    /// 对齐 OC bgImg 分支的 `SDImageFormatGIF` 判断（`sd_imageWithGIFData:` 走动图路径）。
+    private let backgroundImageView = SDAnimatedImageView()
+    private let iconImageView = UIImageView()
+    private var flickerTimer: Timer?
+    private var remainingFlickerToggles = 0
+
+    /// `ShowEmbedVideo` 行内播放器的黑色背景层，对齐 OC `videoPlayView`/
+    /// `videoCoverImageView` 未加载封面图时的纯黑不透明表现；不接收触摸，
+    /// 只有播放按钮需要响应点击。
+    private let embedVideoBackdropView = UIView()
+    /// 居中播放按钮，点击前不加载播放器，对齐 OC `RBCoreVideoViewController` 的
+    /// 「居中播放按钮，点击才开始播放」（非自动播放）；固定 60×60，不随热区放大。
+    private let embedVideoPlayButton = UIButton(type: .custom)
+    private var embedPlayerViewController: AVPlayerViewController?
+    private var isEmbedVideo: Bool { interaction.embedVideoURL != nil }
+
+    /// - Parameter skipEntranceFlicker: 宿主重建同一个热区（比如资源异步就绪后
+    ///   `configureInteractions` 整页重建）但这不是用户第一次看到这一页时传 `true`，
+    ///   跳过入场闪烁、直接进入闪烁本该结束后的终态，避免每次重建都重新闪一轮。
+    init(interaction: RDPDFReaderPageInteraction, isActive: Bool, skipEntranceFlicker: Bool = false) {
+        self.interaction = interaction
+        self.isActive = isActive
+        super.init(frame: .zero)
+        backgroundColor = .clear
+        // 图标可能大于热区（iconRate > 1），与 OC 一致不裁剪
+        clipsToBounds = false
+
+        if interaction.embedVideoURL != nil {
+            // 嵌入视频是独立的行内播放器，不画边框/填充/图标，也不接入通用点击手势
+            // （原生播放器控件需要正常的子视图命中链路，见 hitTest 里的分支）。
+            setupEmbedVideoPoster()
+            return
+        }
+
+        styleView.isUserInteractionEnabled = false
+        addSubview(styleView)
+
+        hoverFlashView.isUserInteractionEnabled = false
+        hoverFlashView.layer.cornerRadius = 5
+        hoverFlashView.clipsToBounds = true
+        hoverFlashView.isHidden = true
+        addSubview(hoverFlashView)
+
+        backgroundImageView.contentMode = .scaleAspectFit
+        backgroundImageView.isUserInteractionEnabled = false
+        addSubview(backgroundImageView)
+
+        iconImageView.contentMode = .scaleAspectFit
+        iconImageView.isUserInteractionEnabled = false
+        addSubview(iconImageView)
+
+        applyStyle(skipEntranceFlicker: skipEntranceFlicker)
+        loadBackgroundImage()
+
+        addGestureRecognizer(UITapGestureRecognizer(target: self, action: #selector(handleTap)))
+    }
+
+    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+    deinit {
+        flickerTimer?.invalidate()
+        if let embedPlayerViewController {
+            embedPlayerViewController.player?.pause()
+            embedPlayerViewController.willMove(toParent: nil)
+            embedPlayerViewController.view.removeFromSuperview()
+            embedPlayerViewController.removeFromParent()
+        }
+    }
+
+    // MARK: - 嵌入视频
+
+    private func setupEmbedVideoPoster() {
+        embedVideoBackdropView.backgroundColor = .black
+        embedVideoBackdropView.isUserInteractionEnabled = false
+        addSubview(embedVideoBackdropView)
+
+        // 有封面图（宿主已按 bgImgInfo.bgImgUrl 优先、customData.embedBgCover.imgUrl
+        // 兜底解析好本地路径，对齐 OC 只认前者的现状；后者是本端在前者为空时的
+        // 额外兜底）时铺在黑色背景之上，对齐 OC `videoCoverImageView`：铺满、aspectFit；
+        // 没有封面图时维持纯黑背景兜底（OC 该控件未加载到封面图时同样是纯黑，见
+        // `RBCoreVideoView.xib` 的 `videoCoverImageView` 默认背景色）。复用既有的
+        // backgroundImageView/loadBackgroundImage，与普通热区背景图走同一套逻辑。
+        backgroundImageView.contentMode = .scaleAspectFit
+        backgroundImageView.isUserInteractionEnabled = false
+        addSubview(backgroundImageView)
+        loadBackgroundImage()
+
+        // 复用 OC 的 videoPlay.png 播放按钮图（readoor/BookView/PDF/Core/Resources），
+        // 找不到（比如资源改名/未随主 App target 打包）时退化成系统图标，不留空按钮。
+        embedVideoPlayButton.setImage(UIImage(named: "videoPlay") ?? UIImage(systemName: "play.fill"), for: .normal)
+        embedVideoPlayButton.tintColor = .white
+        embedVideoPlayButton.addTarget(self, action: #selector(handleEmbedVideoTap), for: .touchUpInside)
+        addSubview(embedVideoPlayButton)
+    }
+
+    /// 点击海报播放按钮：懒建播放器、接管到最近的宿主 UIViewController（沿责任链
+    /// 查找，避免整条组件树都要透传一个 VC 引用），原生 `AVPlayerViewController`
+    /// 自带播放/暂停/进度条控件。开始播放即通过现有 `onTap` 管线回调一次，让
+    /// ViewModel 按 `EventNone` 分支暂停其它音频（对齐 OC「点击嵌入视频播放－－
+    /// 停止其他所有音频」），之后播放器自身的手势/控件接管，不再触发这个方法。
+    @objc private func handleEmbedVideoTap() {
+        guard embedPlayerViewController == nil,
+              let url = interaction.embedVideoURL,
+              let hostViewController = nearestViewController() else { return }
+        let playerViewController = AVPlayerViewController()
+        playerViewController.player = AVPlayer(url: url)
+        playerViewController.view.frame = bounds
+        playerViewController.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        hostViewController.addChild(playerViewController)
+        addSubview(playerViewController.view)
+        playerViewController.didMove(toParent: hostViewController)
+        embedPlayerViewController = playerViewController
+        embedVideoBackdropView.isHidden = true
+        backgroundImageView.isHidden = true
+        embedVideoPlayButton.isHidden = true
+        playerViewController.player?.play()
+        onTap?()
+    }
+
+    private func nearestViewController() -> UIViewController? {
+        var responder: UIResponder? = self
+        while let current = responder {
+            if let viewController = current as? UIViewController { return viewController }
+            responder = current.next
+        }
+        return nil
+    }
+
+    // MARK: - 样式
+
+    /// 仅在视图创建时调用一次：应用边框/填充色，并在非激活态且配置了闪烁次数时
+    /// 播放一轮"进入页面"闪烁（对齐 OC `flashLink` 首次入页表现）。激活态切换
+    /// 之后走 `setActive(_:)`，不再重复这套入场逻辑。
+    /// - Parameter skipEntranceFlicker: 宿主明确告知这不是用户第一次看到这个热区
+    ///   （比如背景图/图标异步下载完成后触发的整页重建）时传 `true`，直接落到闪烁
+    ///   本该结束后的终态（`isStyleHiddenAtRest`），不重新播放这轮入场闪烁。
+    private func applyStyle(skipEntranceFlicker: Bool = false) {
+        applyBorderAndFillColors()
+        if isActive {
+            applyActivePlayNotice()
+        } else if interaction.flickerCount > 0 && !skipEntranceFlicker {
+            // flickerCount > 0：初始隐藏 → 闪烁 N×2 次 → 回到隐藏（对齐 OC isNew==2 的表现）
+            styleView.isHidden = true
+            startFlicker(times: interaction.flickerCount * 2)
+        } else {
+            styleView.isHidden = isStyleHiddenAtRest
+        }
+    }
+
+    private func applyBorderAndFillColors() {
+        if let fillColor = interaction.fillColorHex, interaction.fillOpacity > 0 {
+            styleView.backgroundColor = UIColor.pdfReaderColor(
+                hex: fillColor,
+                alpha: CGFloat(interaction.fillOpacity) / 100
+            )
+        } else {
+            styleView.backgroundColor = .clear
+        }
+
+        let activeBorderHex = isActive ? Self.strictHexOnly(interaction.activeBorderColorHex) : nil
+        let borderHex = activeBorderHex ?? interaction.borderColorHex
+        if let borderHex {
+            styleView.layer.borderColor = UIColor.pdfReaderColor(
+                hex: borderHex,
+                alpha: CGFloat(interaction.borderOpacity) / 100
+            ).cgColor
+            styleView.layer.borderWidth = 1 / UIScreen.main.scale
+        } else {
+            styleView.layer.borderWidth = 0
+        }
+    }
+
+    /// 播放边框：isNew==2 只画 playBorderColor 边框（宽度 iPad 3pt / iPhone 2pt，
+    /// 对齐 OC `showMediaPaper:`）；playNoticeEnable == false 时完全不显示；
+    /// noticeStatus == "bright" 长亮到非激活，"flicker"（默认）显示
+    /// 0.7s 后用 0.3s 动画淡出。非激活态的常规边框走 `applyBorderAndFillColors`
+    /// 的发丝线宽度，不受这里影响。
+    private func applyActivePlayNotice() {
+        guard interaction.playNoticeEnable else {
+            styleView.isHidden = true
+            return
+        }
+        styleView.layer.borderWidth = UIDevice.current.userInterfaceIdiom == .pad ? 3 : 2
+        styleView.isHidden = false
+        styleView.alpha = 1
+        if interaction.noticeStatus != "bright" {
+            UIView.animate(withDuration: 0.3, delay: 0.7, options: [], animations: { [weak self] in
+                self?.styleView.alpha = 0
+            })
+        }
+    }
+
+    /// 宿主播放状态切换时调用：只原地更新这一个热区的边框/播放提示，
+    /// 不重建视图、不重触发入场闪烁（修复此前 `configureInteractions` 整页
+    /// 重建导致点击一个 link 后全页热区一起重新闪烁的问题，对齐 OC
+    /// `setActiveInteraction` 只影响单个热区常亮/播放边框的语义）。
+    func setActive(_ active: Bool) {
+        guard isActive != active else { return }
+        isActive = active
+        flickerTimer?.invalidate()
+        flickerTimer = nil
+        styleView.layer.removeAllAnimations()
+        applyBorderAndFillColors()
+        if active {
+            applyActivePlayNotice()
+        } else {
+            styleView.alpha = 1
+            styleView.isHidden = isStyleHiddenAtRest
+        }
+    }
+
+    /// 点击瞬时填充闪烁：150ms 后自动移除（对齐 OC `showHoverFlash:`）。
+    private func playHoverFlash() {
+        guard let hoverHex = Self.strictHexOnly(interaction.hoverColorHex) else { return }
+        hoverFlashView.backgroundColor = UIColor.pdfReaderColor(hex: hoverHex)
+        hoverFlashView.isHidden = false
+        DispatchQueue.main.asyncAfter(deadline: .now() + 0.15) { [weak self] in
+            self?.hoverFlashView.isHidden = true
+        }
+    }
+
+    /// 边框/填充的静止态恒为隐藏，与 `flickerCount` 是否配置无关——对齐 OC
+    /// `flashLink`（`RBCoreMediaLinkPaper.m`）：`isNew==2` 时无论 `linkBlink` 是否
+    /// 为 0，初始都 `hidden=YES`；`linkBlink>0` 时闪烁次数固定是 `linkBlink×2`
+    /// （偶数），闪完必然翻回 `hidden=YES`。`flickerCount` 只决定"是否经历一段
+    /// 临时的闪烁过程"，不决定"最终是否隐藏"。
+    private var isStyleHiddenAtRest: Bool { true }
+
+    private func startFlicker(times: Int) {
+        remainingFlickerToggles = times
+        flickerTimer?.invalidate()
+        // OC 的闪烁间隔固定 0.5s（RBCoreMediaLinkPaper.blinkTime）
+        flickerTimer = Timer.scheduledTimer(withTimeInterval: 0.5, repeats: true) { [weak self] timer in
+            guard let self else {
+                timer.invalidate()
+                return
+            }
+            self.styleView.isHidden.toggle()
+            self.remainingFlickerToggles -= 1
+            if self.remainingFlickerToggles < 1 {
+                timer.invalidate()
+                self.flickerTimer = nil
+                self.styleView.isHidden = self.isStyleHiddenAtRest
+            }
+        }
+    }
+
+    /// 工具栏"点读提示"按钮触发：重新闪一轮热区，对齐 OC 的
+    /// `RBCoreToolbarController.linkFlashButton` →`RBCoreMediaLinkPaper.flashLink`。
+    /// 正在播放的热区保持常亮，不参与闪烁，避免丢失当前朗读位置；`flickerCount<=0`
+    /// 的热区对齐 OC `linkBlink==0` 时 timer 从不启动，点击无任何反应（不做"保证
+    /// 总有反馈"的兜底闪烁）。
+    func flash() {
+        guard !isActive, interaction.flickerCount > 0 else { return }
+        // 与 OC 一致：从隐藏开始，偶数次切换后回到常驻状态
+        styleView.isHidden = true
+        startFlicker(times: interaction.flickerCount * 2)
+    }
+
+    /// 对齐 OC `colorFromLinkStrKey:`（`RBCoreBookDataVariables.m:271-302`）：
+    /// `hoverColor`/`playBorderColor` 只认 `#RRGGBB`/`#RRGGBBAA`，不支持
+    /// `rgba(...)`——与 `borderColor`/`bgColor` 走的 `parseColor:`（三种格式都
+    /// 支持）是两套不对称的实现，这里严格复刻这个不对称，不统一放宽到都支持
+    /// rgba。`UIColor.pdfReaderColor(hex:alpha:)` 本身不做这层限制（border/fill
+    /// 仍需要它支持三种格式），因此校验放在这两个消费点，不改公共颜色解析方法。
+    private static func strictHexOnly(_ hex: String?) -> String? {
+        guard let hex, hex.hasPrefix("#"), hex.count == 7 || hex.count == 9 else { return nil }
+        return hex
+    }
+
+    private func loadBackgroundImage() {
+        guard let path = interaction.backgroundImagePath else { return }
+        backgroundImageView.image = SDAnimatedImage(contentsOfFile: path) ?? UIImage(contentsOfFile: path)
+    }
+
+    // MARK: - 布局
+
+    /// 由父视图在设置完 bounds/center 后调用：应用旋转并摆放图标与背景图。
+    func applyRotationAndLayout() {
+        let size = bounds.size
+        // 背景图与样式层随热区旋转；SVG 图标不旋转（对齐 OC）
+        transform = interaction.rotation == 0
+            ? .identity
+            : CGAffineTransform(rotationAngle: interaction.rotation * .pi / 180)
+
+        if isEmbedVideo {
+            embedVideoBackdropView.frame = CGRect(origin: .zero, size: size)
+            backgroundImageView.frame = CGRect(origin: .zero, size: size)
+            // 对齐 OC viewDidLayoutSubviews：按钮边长 = min(热区最小边, 60pt)，不随热区放大无限变大。
+            let buttonSide = min(min(size.width, size.height), 60)
+            embedVideoPlayButton.bounds = CGRect(x: 0, y: 0, width: buttonSide, height: buttonSide)
+            embedVideoPlayButton.center = CGPoint(x: size.width / 2, y: size.height / 2)
+            embedPlayerViewController?.view.frame = CGRect(origin: .zero, size: size)
+            return
+        }
+
+        styleView.frame = CGRect(origin: .zero, size: size)
+        hoverFlashView.frame = CGRect(origin: .zero, size: size)
+        backgroundImageView.frame = CGRect(origin: .zero, size: size)
+
+        // 图标反向旋转抵消父视图的旋转，等价于 OC 里 icon 容器 transform = identity
+        iconImageView.transform = interaction.rotation == 0
+            ? .identity
+            : CGAffineTransform(rotationAngle: -interaction.rotation * .pi / 180)
+
+        let side = min(size.width, size.height) * max(interaction.iconRate, 0)
+        iconImageView.bounds = CGRect(x: 0, y: 0, width: side, height: side)
+        iconImageView.center = CGPoint(x: size.width / 2, y: size.height / 2)
+
+        loadIconIfNeeded(side: side)
+    }
+
+    private var loadedIconSide: CGFloat = 0
+
+    private func loadIconIfNeeded(side: CGFloat) {
+        guard let iconURL = interaction.iconURL, side > 0 else { return }
+        // 尺寸变化（旋转、缩放后重新布局）时才重新光栅化，避免重复请求
+        guard abs(side - loadedIconSide) > 0.5 else { return }
+        loadedIconSide = side
+        RDPDFReaderSVGIconLoader.shared.load(
+            url: iconURL,
+            localPath: interaction.iconLocalPath,
+            colorHex: interaction.iconColorHex,
+            size: CGSize(width: side, height: side)
+        ) { [weak iconImageView] image in
+            iconImageView?.image = image
+        }
+    }
+
+    @objc private func handleTap() {
+        playHoverFlash()
+        onTap?()
+    }
+
+    // MARK: - 命中判定
+
+    /// 命中矩形按未旋转的外接矩形（AABB）判定，不把 `angle` 计入，对齐 OC
+    /// `RBCoreMediaContentView` 的现存行为（命中矩形是 AABB，旋转热区的点击判定
+    /// 仍按未旋转的外接矩形）。`frame` 在非 identity transform 下即为该外接矩形。
+    /// 嵌入视频例外：播放按钮/原生播放器控件需要正常的子视图命中链路，不能像
+    /// 普通热区那样整块粗暴命中到 `self`，否则按钮和播放器手势都收不到触摸。
+    override func hitTest(_ point: CGPoint, with event: UIEvent?) -> UIView? {
+        guard isUserInteractionEnabled, !isHidden, alpha > 0.01 else { return nil }
+        if isEmbedVideo { return super.hitTest(point, with: event) }
+        guard let superview else { return super.hitTest(point, with: event) }
+        let pointInSuperview = convert(point, to: superview)
+        return frame.contains(pointInSuperview) ? self : nil
+    }
+}

Sources/RDPDFReaderView/Sources/RDPDFReaderChromeViews.swift

@@ -93,6 +93,12 @@ public final class RDPDFReaderKitBottomToolView: UIView {
     public var onShowAnnotations: (() -> Void)?
     public var onStartDrawing: (() -> Void)?
     public var onShowSettings: (() -> Void)?
+    /// 点读提示：让当前页热区重新闪烁一轮
+    public var onFlashInteractions: (() -> Void)?
+    /// 连播开关：对齐 OC 的 loop 按钮（`isShowLoopPlayerBtnState:` 的 loop 规则）。
+    /// 3.0 课件不产生 `ShowEmbedImage`，因此 OC 的 img/loop 互斥规则里 img 恒为
+    /// false，本端只保留 loop 一支。
+    public var onToggleSequentialPlay: (() -> Void)?
 
     private let stackView: UIStackView = {
         let view = UIStackView()
@@ -102,6 +108,8 @@ public final class RDPDFReaderKitBottomToolView: UIView {
         return view
     }()
     private let catalogButton = UIButton(type: .system)
+    private let interactionFlashButton = UIButton(type: .system)
+    private let loopButton = UIButton(type: .system)
     private let annotationsButton = UIButton(type: .system)
     private let drawingButton = UIButton(type: .system)
     private let settingsButton = UIButton(type: .system)
@@ -115,6 +123,9 @@ public final class RDPDFReaderKitBottomToolView: UIView {
         addSubview(separatorLine)
         separatorLine.backgroundColor = UIColor(white: 0, alpha: 0.12)
         stackView.addArrangedSubview(catalogButton)
+        // 与 OC 工具栏一致：点读提示按钮紧跟目录按钮，非点读书时整项隐藏
+        stackView.addArrangedSubview(interactionFlashButton)
+        stackView.addArrangedSubview(loopButton)
         stackView.addArrangedSubview(annotationsButton)
         stackView.addArrangedSubview(drawingButton)
         stackView.addArrangedSubview(settingsButton)
@@ -128,16 +139,26 @@ public final class RDPDFReaderKitBottomToolView: UIView {
             make.height.equalTo(0.5)
         }
         configure(catalogButton, image: "list.bullet")
+        configure(interactionFlashButton, image: "hand.tap")
+        configure(loopButton, image: "repeat")
         configure(annotationsButton, image: "note.text")
         configure(drawingButton, image: "pencil.tip")
         configure(settingsButton, image: "gearshape")
         catalogButton.accessibilityIdentifier = "epub.reader.toc"
+        interactionFlashButton.accessibilityIdentifier = "pdf.reader.interactionFlash"
+        interactionFlashButton.accessibilityLabel = "点读提示"
+        interactionFlashButton.isHidden = true
+        loopButton.accessibilityIdentifier = "pdf.reader.loop"
+        loopButton.accessibilityLabel = "连续播放"
+        loopButton.isHidden = true
         annotationsButton.accessibilityIdentifier = "pdf.reader.annotations"
         annotationsButton.accessibilityLabel = "笔记"
         drawingButton.accessibilityIdentifier = "pdf.reader.drawing"
         drawingButton.accessibilityLabel = "画笔"
         settingsButton.accessibilityIdentifier = "epub.reader.settings"
         catalogButton.addTarget(self, action: #selector(catalogAction), for: .touchUpInside)
+        interactionFlashButton.addTarget(self, action: #selector(interactionFlashAction), for: .touchUpInside)
+        loopButton.addTarget(self, action: #selector(loopAction), for: .touchUpInside)
         annotationsButton.addTarget(self, action: #selector(annotationsAction), for: .touchUpInside)
         drawingButton.addTarget(self, action: #selector(drawingAction), for: .touchUpInside)
         settingsButton.addTarget(self, action: #selector(settingsAction), for: .touchUpInside)
@@ -145,13 +166,30 @@ public final class RDPDFReaderKitBottomToolView: UIView {
 
     public required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
 
+    /// 只有确认含点读热区的书才展示"点读提示"按钮（对齐 OC 的
+    /// `isNew == 2 && multimediaMtime > 0` 判断）。
+    public func setInteractionFlashHidden(_ hidden: Bool) {
+        interactionFlashButton.isHidden = hidden
+    }
+
+    /// loop 按钮显隐：当前页存在 autoPlay 音频热区时才显示（对齐 OC
+    /// `isShowLoopPlayerBtnState:` 的 loop 规则；img 分支 3.0 恒不适用，见类注释）。
+    public func setLoopButtonHidden(_ hidden: Bool) {
+        loopButton.isHidden = hidden
+    }
+
+    /// loop 按钮图标：连播中显示为高亮的 `repeat.circle.fill`。
+    public func setLoopButtonActive(_ active: Bool) {
+        loopButton.setImage(UIImage(systemName: active ? "repeat.circle.fill" : "repeat"), for: .normal)
+    }
+
     public func apply(
         backgroundColor: UIColor,
         tintColor: UIColor,
         separatorColor: UIColor
     ) {
         self.backgroundColor = backgroundColor
-        [catalogButton, annotationsButton, drawingButton, settingsButton].forEach { $0.tintColor = tintColor }
+        [catalogButton, interactionFlashButton, loopButton, annotationsButton, drawingButton, settingsButton].forEach { $0.tintColor = tintColor }
         separatorLine.backgroundColor = separatorColor
     }
 
@@ -162,6 +200,8 @@ public final class RDPDFReaderKitBottomToolView: UIView {
     }
 
     @objc private func catalogAction() { onShowTableOfContents?() }
+    @objc private func interactionFlashAction() { onFlashInteractions?() }
+    @objc private func loopAction() { onToggleSequentialPlay?() }
     @objc private func annotationsAction() { onShowAnnotations?() }
     @objc private func drawingAction() { onStartDrawing?() }
     @objc private func settingsAction() { onShowSettings?() }

Sources/RDPDFReaderView/Sources/RDPDFReaderContracts.swift

@@ -21,17 +21,110 @@ public struct RDPDFReaderPageDescriptor {
     /// 宿主已解析的文本区域。坐标使用页面图片左上角为原点的 0...1 比例；
     /// `nil` 表示宿主没有提供文本数据，SDK 可按需使用 OCR 作为兜底。
     public let textRuns: [RDPDFReaderTextRun]?
+    public let interactions: [RDPDFReaderPageInteraction]
 
     public init(index: Int, image: UIImage?) {
         self.index = index
         self.image = image
         textRuns = nil
+        interactions = []
     }
 
     public init(index: Int, image: UIImage?, textRuns: [RDPDFReaderTextRun]?) {
         self.index = index
         self.image = image
         self.textRuns = textRuns
+        interactions = []
+    }
+
+    public init(index: Int, image: UIImage?, textRuns: [RDPDFReaderTextRun]?, interactions: [RDPDFReaderPageInteraction]) {
+        self.index = index
+        self.image = image
+        self.textRuns = textRuns
+        self.interactions = interactions
+    }
+}
+
+/// 点读书的页面互动热区。坐标位于页面内容坐标系，因此会随 SDK 的缩放、拖动同步移动。
+public struct RDPDFReaderPageInteraction: Equatable {
+    public let identifier: String
+    public let normalizedRect: CGRect
+    public let rotation: CGFloat
+    public let eventType: Int
+    public let iconName: String?
+    public let iconURL: URL?
+    /// 宿主已下载到本地的 SVG 文件路径；存在则渲染层直接解码，不发起网络请求。
+    public let iconLocalPath: String?
+    public let iconColorHex: String?
+    public let iconRate: CGFloat
+    /// 由宿主解析后的热区样式。SDK 不依赖业务类型，仅负责绘制。
+    public let borderColorHex: String?
+    public let fillColorHex: String?
+    public let activeBorderColorHex: String?
+    /// 已下载的背景图本地路径；为 nil 时 SDK 使用样式填充作为回退。
+    public let backgroundImagePath: String?
+    /// 边框不透明度 0~100（对齐 OC 的 link_border_opacity）
+    public let borderOpacity: Int
+    /// 填充不透明度 0~100（对齐 OC 的 link_fill_opacity）
+    public let fillOpacity: Int
+    /// 进入页面时边框/填充的闪烁次数；> 0 时闪烁结束后隐藏样式层，只保留图标/背景图。
+    /// 0 表示不闪烁、样式层常显（旧格式书籍的表现）。
+    public let flickerCount: Int
+    /// 点击瞬时填充色（对齐 OC `showHoverFlash:` 的 hoverColor），150ms 后自动移除。
+    public let hoverColorHex: String?
+    /// 播放边框总开关；为 false 时 `isActive` 完全不显示边框（对齐 OC playNoticeEnable）。
+    public let playNoticeEnable: Bool
+    /// 播放边框表现：`"bright"` 长亮到非激活；`"flicker"`（含空值默认）显示 0.7s 后
+    /// 用 0.3s 动画淡出（对齐 OC `noticeStatus`）。
+    public let noticeStatus: String
+    /// 嵌入视频热区（OC `ShowEmbedVideo`）可播放的媒体地址（本地文件优先，否则宿主
+    /// 已解析好的在线地址）；非嵌入视频类型或资源都不可用时为 nil。这类热区是独立
+    /// 的行内播放器，不接入通用 `eventType` 点击分发（`eventType` 本身恒为 0），
+    /// 渲染层据此跳过边框/填充/图标，只画播放器。
+    public let embedVideoURL: URL?
+
+    public init(
+        identifier: String,
+        normalizedRect: CGRect,
+        rotation: CGFloat = 0,
+        eventType: Int,
+        iconName: String? = nil,
+        iconURL: URL? = nil,
+        iconLocalPath: String? = nil,
+        iconColorHex: String? = nil,
+        iconRate: CGFloat = 1,
+        borderColorHex: String? = nil,
+        fillColorHex: String? = nil,
+        activeBorderColorHex: String? = nil,
+        backgroundImagePath: String? = nil,
+        borderOpacity: Int = 100,
+        fillOpacity: Int = 0,
+        flickerCount: Int = 0,
+        hoverColorHex: String? = nil,
+        playNoticeEnable: Bool = true,
+        noticeStatus: String = "flicker",
+        embedVideoURL: URL? = nil
+    ) {
+        self.identifier = identifier
+        self.normalizedRect = normalizedRect
+        self.rotation = rotation
+        self.eventType = eventType
+        self.iconName = iconName
+        self.iconURL = iconURL
+        self.iconLocalPath = iconLocalPath
+        self.iconColorHex = iconColorHex
+        self.iconRate = iconRate
+        self.borderColorHex = borderColorHex
+        self.fillColorHex = fillColorHex
+        self.activeBorderColorHex = activeBorderColorHex
+        self.backgroundImagePath = backgroundImagePath
+        self.borderOpacity = borderOpacity
+        self.fillOpacity = fillOpacity
+        self.flickerCount = flickerCount
+        self.hoverColorHex = hoverColorHex
+        self.playNoticeEnable = playNoticeEnable
+        self.noticeStatus = noticeStatus
+        self.embedVideoURL = embedVideoURL
     }
 }
 

Sources/RDPDFReaderView/Sources/RDPDFReaderPageView.swift

@@ -27,11 +27,13 @@ public protocol RDPDFReaderPageViewDelegate: AnyObject {
         didRequestHighlightMenuAction action: RDPDFReaderExistingHighlightMenuAction,
         highlight: RDPDFReaderAnnotation
     )
+    func pageView(_ pageView: RDPDFReaderPageView, didTap interaction: RDPDFReaderPageInteraction)
 }
 
 public extension RDPDFReaderPageViewDelegate {
     func pageView(_ pageView: RDPDFReaderPageView, didChangeSelection selection: RDPDFReaderImageTextSelection?) {}
     func pageView(_ pageView: RDPDFReaderPageView, didCopyText text: String) {}
+    func pageView(_ pageView: RDPDFReaderPageView, didTap interaction: RDPDFReaderPageInteraction) {}
 }
 
 /// PDF 页面视图：组合缩放画布、文字选择层和选区放大镜，
@@ -45,7 +47,15 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
 
     public weak var delegate: RDPDFReaderPageViewDelegate?
 
-    public var image: UIImage? { didSet { zoomView.image = image } }
+    public var image: UIImage? {
+        didSet {
+            zoomView.image = image
+            // contentView 的尺寸按图片比例重新计算（aspectFit 后往往比整页视图矮），
+            // 热区/文字/画笔叠加层都以它为坐标系，必须重新布局，
+            // 否则热区仍按上一次的尺寸摆放，出现整体拉伸并溢出内容区。
+            setNeedsLayout()
+        }
+    }
 
     /// 当前页索引，来自 `configureTextLayer`。
     public var pageIndex: Int { textLayer.pageIndex }
@@ -58,6 +68,17 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
     private let zoomView = RDPDFZoomablePageView()
     private let textLayer = RDPDFReaderImageTextLayerView()
     private let drawingCanvas = RDPDFReaderDrawingCanvasView()
+    private let interactionOverlay = UIView()
+    private var pageInteractions: [RDPDFReaderPageInteraction] = []
+    private var activeInteractionIdentifier: String?
+    /// 已经在本 page view 实例上播放过入场闪烁的热区标识。`configureInteractions`
+    /// 会因为附件资源（背景图/图标）异步下载完成而被反复调用，每次都整页重建热区
+    /// 视图；如果每次重建都让 `flickerCount > 0` 的热区重新走一遍入场闪烁，表现就是
+    /// 页面反复闪烁（对齐 `setActiveInteraction` 上面的注释：同类问题之前已经在"点击
+    /// 单个 link 后全页重新闪烁"这个场景上处理过一次）。页码变化时清空，配合下面的
+    /// `flickerTrackedPageIndex`，避免 page view 被复用装配到不同页时状态串页。
+    private var flickeredInteractionIdentifiers: Set<String> = []
+    private var flickerTrackedPageIndex: Int?
     private let contentAccessibilityView = UIView()
     private let selectionLoupe = RDPDFReaderSelectionLoupeView()
     private let pageLoadFailureButton = UIButton(type: .system)
@@ -84,6 +105,7 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
             // 退出编辑只关闭触摸，不隐藏画布；否则已持久化的笔迹会和工具栏一起消失。
             drawingCanvas.isHidden = false
             drawingCanvas.isUserInteractionEnabled = isDrawingMode
+            interactionOverlay.isUserInteractionEnabled = !isDrawingMode
             zoomView.isDrawingMode = isDrawingMode
         }
     }
@@ -150,6 +172,59 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
         updateAccessibilityViewport()
     }
 
+    public func configureInteractions(_ interactions: [RDPDFReaderPageInteraction]) {
+        pageInteractions = interactions
+        // page view 被复用装配到不同页时，上一页记录的"已闪过"状态不能带到这一页。
+        if flickerTrackedPageIndex != pageIndex {
+            flickerTrackedPageIndex = pageIndex
+            flickeredInteractionIdentifiers.removeAll()
+        }
+        interactionOverlay.subviews.forEach { $0.removeFromSuperview() }
+        for interaction in interactions {
+            // 同一个热区标识如果之前已经在这一页播放过入场闪烁，这次重建只是因为
+            // 资源异步就绪触发的 configureInteractions，不是用户第一次看到这一页，
+            // 不需要再闪一轮。
+            let skipEntranceFlicker = flickeredInteractionIdentifiers.contains(interaction.identifier)
+            let hotspot = RDPDFInteractionHotspotView(
+                interaction: interaction,
+                isActive: interaction.identifier == activeInteractionIdentifier,
+                skipEntranceFlicker: skipEntranceFlicker
+            )
+            flickeredInteractionIdentifiers.insert(interaction.identifier)
+            hotspot.accessibilityIdentifier = "pdf.interaction.\(interaction.identifier)"
+            hotspot.onTap = { [weak self] in
+                guard let self, !self.isDrawingMode else { return }
+                self.delegate?.pageView(self, didTap: interaction)
+            }
+            interactionOverlay.addSubview(hotspot)
+        }
+        // 配置时 contentView 可能还没按新图片完成适配，先按当前尺寸摆一次，
+        // 再请求一次布局，等 contentView 定型后以真实内容区重新计算。
+        layoutInteractionButtons()
+        setNeedsLayout()
+    }
+
+    /// 让本页所有点读热区重新闪烁一轮，用于工具栏的"点读提示"按钮。
+    public func flashInteractions() {
+        interactionOverlay.subviews.forEach { ($0 as? RDPDFInteractionHotspotView)?.flash() }
+    }
+
+    /// 宿主同步点读媒体的下载/播放状态。状态只影响视觉，不参与持久化。
+    /// 只原地切换受影响的一到两个热区，不整页重建——否则每个 `RDPDFInteractionHotspotView`
+    /// 都会在 `init` 里重新走一遍入场闪烁，导致点击一个 link 后全页热区一起闪烁。
+    public func setActiveInteraction(identifier: String?) {
+        guard activeInteractionIdentifier != identifier else { return }
+        let previousIdentifier = activeInteractionIdentifier
+        activeInteractionIdentifier = identifier
+        for case let hotspot as RDPDFInteractionHotspotView in interactionOverlay.subviews {
+            if hotspot.interactionIdentifier == previousIdentifier {
+                hotspot.setActive(false)
+            } else if hotspot.interactionIdentifier == identifier {
+                hotspot.setActive(true)
+            }
+        }
+    }
+
     /// Shows a non-persistent highlight while the speech engine reads text.
     public func setSpeechHighlightRects(_ rects: [CGRect]) {
         textLayer.speechHighlightRects = rects
@@ -237,6 +312,10 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
         }
         zoomView.viewportChanged = { [weak self] _, _ in self?.updateAccessibilityViewport() }
         addSubview(zoomView)
+        interactionOverlay.frame = zoomView.contentView.bounds
+        interactionOverlay.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        interactionOverlay.backgroundColor = .clear
+        zoomView.contentView.addSubview(interactionOverlay)
 
         textLayer.frame = zoomView.contentView.bounds
         textLayer.autoresizingMask = [.flexibleWidth, .flexibleHeight]
@@ -258,6 +337,7 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
         drawingCanvas.isHidden = true
         drawingCanvas.isUserInteractionEnabled = false
         zoomView.contentView.addSubview(drawingCanvas)
+        zoomView.contentView.bringSubviewToFront(interactionOverlay)
 
         contentAccessibilityView.frame = bounds
         contentAccessibilityView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
@@ -296,12 +376,32 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
         zoomView.layoutIfNeeded()
         textLayer.frame = zoomView.contentView.bounds
         drawingCanvas.frame = zoomView.contentView.bounds
+        interactionOverlay.frame = zoomView.contentView.bounds
+        layoutInteractionButtons()
         pageLoadFailureButton.sizeToFit()
         pageLoadFailureButton.bounds.size.width += 32
         pageLoadFailureButton.bounds.size.height += 24
         pageLoadFailureButton.center = CGPoint(x: bounds.midX, y: bounds.midY)
     }
 
+    private func layoutInteractionButtons() {
+        let bounds = interactionOverlay.bounds
+        for (index, interaction) in pageInteractions.enumerated() where index < interactionOverlay.subviews.count {
+            let hotspot = interactionOverlay.subviews[index]
+            // 先复位 transform 再摆 frame：带旋转的视图直接改 frame 会把尺寸算错
+            hotspot.transform = .identity
+            hotspot.bounds.size = CGSize(
+                width: bounds.width * interaction.normalizedRect.width,
+                height: bounds.height * interaction.normalizedRect.height
+            )
+            hotspot.center = CGPoint(
+                x: bounds.width * interaction.normalizedRect.midX,
+                y: bounds.height * interaction.normalizedRect.midY
+            )
+            (hotspot as? RDPDFInteractionHotspotView)?.applyRotationAndLayout()
+        }
+    }
+
     // MARK: - 点击分发
 
     @objc private func handleTap(_ gesture: UITapGestureRecognizer) {
@@ -495,3 +595,41 @@ public final class RDPDFReaderPageView: UIView, RDPDFReaderPageInteractable, UIG
         )
     }
 }
+
+extension UIColor {
+    /// 解析点读书样式颜色：兼容 `#RRGGBB` / `#RRGGBBAA` / `rgba(r,g,b,a)` 三种格式，
+    /// 规则对齐 OC 版 `parseColor:outColor:outOpacity:`。8 位 hex 或 rgba 自带的 alpha
+    /// 优先于外部传入的 `alpha`；纯 6 位 hex 没有内嵌 alpha 时才使用 `alpha`（用于
+    /// border/fill 这类 alpha 已在入库时拆到独立 opacity 字段的颜色）。
+    static func pdfReaderColor(hex: String, alpha: CGFloat = 1) -> UIColor {
+        var value = hex.trimmingCharacters(in: .whitespacesAndNewlines)
+        // `#` 前缀是可选的，不是"识别为 hex 格式"的必要条件——`RDPDFLoadBookUseCase.parseColor`
+        // 把 border/fill 颜色拆出 6 位 hex 时会去掉 `#`（opacity 单独存进 borderOpacity/
+        // fillOpacity），历史 bug：这里之前要求必须带 `#` 才走 hex 分支，导致所有不带 `#`
+        // 的 border/fill 颜色全部落到最后的系统蓝兜底——点读热区闪烁/常显的边框和填充色
+        // 全都显示成蓝色，而不是样式表配置的颜色。
+        if value.hasPrefix("#") { value.removeFirst() }
+        if value.count >= 6, let rgb = UInt32(String(value.prefix(6)), radix: 16) {
+            var resolvedAlpha = alpha
+            if value.count >= 8, let alphaVal = UInt8(String(value.dropFirst(6).prefix(2)), radix: 16) {
+                resolvedAlpha = CGFloat(alphaVal) / 255
+            }
+            return UIColor(
+                red: CGFloat((rgb >> 16) & 0xFF) / 255,
+                green: CGFloat((rgb >> 8) & 0xFF) / 255,
+                blue: CGFloat(rgb & 0xFF) / 255,
+                alpha: resolvedAlpha
+            )
+        }
+        if value.hasPrefix("rgba("), value.hasSuffix(")") {
+            let inner = String(value.dropFirst(5).dropLast())
+            let parts = inner.components(separatedBy: ",").map { $0.trimmingCharacters(in: .whitespaces) }
+            if parts.count >= 4,
+               let r = Double(parts[0]), let g = Double(parts[1]), let b = Double(parts[2]),
+               let a = Double(parts[3]) {
+                return UIColor(red: r / 255, green: g / 255, blue: b / 255, alpha: a)
+            }
+        }
+        return systemBlue.withAlphaComponent(alpha)
+    }
+}

Sources/RDPDFReaderView/Sources/RDPDFReaderPersistenceStore.swift

@@ -32,12 +32,19 @@ public enum RDPDFReaderAnnotationPersistenceError: LocalizedError {
 }
 
 /// 阅读 SDK 的本地状态库：管理标注与笔迹文件，不依赖宿主数据库或文件管理器。
-public final class RDPDFReaderPersistenceStore: RDPDFReaderAnnotationPersisting {
+public final class RDPDFReaderPersistenceStore: RDPDFReaderAnnotationPersisting, RDPDFReaderPersistence {
     private struct AnnotationDocument: Codable {
         let version: Int
         let annotations: [RDPDFReaderAnnotation]
     }
 
+    /// 阅读位置与书签和标注共用同一个 SDK 状态目录。宿主只需要提供书籍对应的目录，
+    /// 不必为了这些通用阅读状态再维护数据库表。
+    private struct ReaderStateDocument: Codable {
+        var readingPages: [String: Int] = [:]
+        var bookmarks: [String: [Int]] = [:]
+    }
+
     private static let annotationDocumentVersion = 1
     /// 同一进程内的多个阅读器可能指向同一本书；将本地状态文件的读写串行化，
     /// 避免原子替换过程中出现竞争或读取半完成文件。
@@ -46,12 +53,50 @@ public final class RDPDFReaderPersistenceStore: RDPDFReaderAnnotationPersisting
     private let drawingsURL: URL
     private let highlightsURL: URL
     private let annotationsURL: URL
+    private let readerStateURL: URL
 
     public init(rootURL: URL) {
         self.rootURL = rootURL
         drawingsURL = rootURL.appendingPathComponent("drawings", isDirectory: true)
         highlightsURL = rootURL.appendingPathComponent("highlights.json")
         annotationsURL = rootURL.appendingPathComponent("annotations.json")
+        readerStateURL = rootURL.appendingPathComponent("reader-state.json")
+    }
+
+    // MARK: - RDPDFReaderPersistence
+
+    public func restoreReadingPage(for bookIdentifier: String) -> Int? {
+        Self.annotationPersistenceLock.lock()
+        defer { Self.annotationPersistenceLock.unlock() }
+        return loadReaderStateLocked().readingPages[bookIdentifier]
+    }
+
+    public func saveReadingPage(_ pageIndex: Int, for bookIdentifier: String) {
+        guard pageIndex >= 0 else { return }
+        Self.annotationPersistenceLock.lock()
+        defer { Self.annotationPersistenceLock.unlock() }
+        var state = loadReaderStateLocked()
+        state.readingPages[bookIdentifier] = pageIndex
+        saveReaderStateLocked(state)
+    }
+
+    public func loadBookmarks(for bookIdentifier: String) -> [RDPDFReaderBookmark] {
+        Self.annotationPersistenceLock.lock()
+        defer { Self.annotationPersistenceLock.unlock() }
+        return (loadReaderStateLocked().bookmarks[bookIdentifier] ?? [])
+            .sorted()
+            .map { RDPDFReaderBookmark(pageIndex: $0, title: "第 \($0 + 1) 页") }
+    }
+
+    public func setBookmark(_ isBookmarked: Bool, pageIndex: Int, for bookIdentifier: String) {
+        guard pageIndex >= 0 else { return }
+        Self.annotationPersistenceLock.lock()
+        defer { Self.annotationPersistenceLock.unlock() }
+        var state = loadReaderStateLocked()
+        var pages = Set(state.bookmarks[bookIdentifier] ?? [])
+        if isBookmarked { pages.insert(pageIndex) } else { pages.remove(pageIndex) }
+        state.bookmarks[bookIdentifier] = pages.sorted()
+        saveReaderStateLocked(state)
     }
 
     public func drawingPaths(pageNo: Int) -> [RDPDFReaderDrawingPath] {
@@ -302,6 +347,19 @@ public final class RDPDFReaderPersistenceStore: RDPDFReaderAnnotationPersisting
         }
     }
 
+    private func loadReaderStateLocked() -> ReaderStateDocument {
+        guard let data = try? Data(contentsOf: readerStateURL),
+              let document = try? JSONDecoder().decode(ReaderStateDocument.self, from: data) else {
+            return ReaderStateDocument()
+        }
+        return document
+    }
+
+    private func saveReaderStateLocked(_ state: ReaderStateDocument) {
+        guard let data = try? JSONEncoder().encode(state) else { return }
+        write(data, to: readerStateURL)
+    }
+
     private func saveAnnotationsLocked(_ annotations: [RDPDFReaderAnnotation]) throws {
         let document = AnnotationDocument(version: Self.annotationDocumentVersion, annotations: annotations)
         let data: Data

Sources/RDPDFReaderView/Sources/RDPDFReaderSVGIconLoader.swift

@@ -0,0 +1,101 @@
+import UIKit
+import SDWebImageSVGCoder
+
+/// OC 版 SVGIconRenderer 的 Swift 对应：优先读取宿主已下载的本地文件解码，未就绪
+/// 时回退网络拉取，再按目标尺寸光栅化 + alpha mask 着色。解码统一走共享串行队列，
+/// 避免 `SDImageSVGCoder` 并发调用返回 nil（对齐 OC 的 `decodeQueue`）。
+///
+/// 重试策略：只读资源最多重试 1 次（项目网络重试策略上限，见 AGENTS.md「网络重试
+/// 必须保守且显式」），未完全对齐 OC 侧的 3 次重试——这是刻意的、优先服从项目策略
+/// 的偏差，而非疏漏。
+/// `public`：宿主需要在附件解析完成后主动预热全书/相邻页图标缓存
+/// （对齐 OC 的三级图标预缓存），因此该加载器本身也要跨模块可见。
+public final class RDPDFReaderSVGIconLoader {
+    public static let shared = RDPDFReaderSVGIconLoader()
+    private let cache = NSCache<NSString, UIImage>()
+    private let decodeQueue = DispatchQueue(label: "com.readoor.pdf.svgicon.decode")
+
+    private init() {
+        // 对齐 OC `RBCoreSVGIconRenderer` 的缓存上限，避免长书本、多热区场景下
+        // 无限增长——只能靠系统内存压力被动回收（`RBCoreSVGIconRenderer.m:36-37`）。
+        cache.totalCostLimit = 10 * 1024 * 1024
+        cache.countLimit = 200
+    }
+
+    /// - Parameter localPath: 宿主已下载到本地的文件路径；存在则直接解码，不发起网络请求。
+    public func load(url: URL, localPath: String? = nil, colorHex: String?, size: CGSize, completion: @escaping (UIImage?) -> Void) {
+        let key = "\(url.absoluteString)|\(colorHex ?? "")|\(Int(size.width))" as NSString
+        if let image = cache.object(forKey: key) { completion(image); return }
+
+        if let localPath {
+            // 文件读取也丢进解码队列，避免在调用方线程（通常是主线程的布局阶段）做同步 I/O。
+            decodeQueue.async { [weak self] in
+                guard let self else { DispatchQueue.main.async { completion(nil) }; return }
+                if let data = FileManager.default.contents(atPath: localPath) {
+                    self.decodeOnQueue(data: data, key: key, colorHex: colorHex, size: size, completion: completion)
+                } else {
+                    DispatchQueue.main.async {
+                        self.fetchAndDecode(url: url, key: key, colorHex: colorHex, size: size, retriesLeft: 1, completion: completion)
+                    }
+                }
+            }
+            return
+        }
+        fetchAndDecode(url: url, key: key, colorHex: colorHex, size: size, retriesLeft: 1, completion: completion)
+    }
+
+    private func fetchAndDecode(url: URL, key: NSString, colorHex: String?, size: CGSize, retriesLeft: Int, completion: @escaping (UIImage?) -> Void) {
+        URLSession.shared.dataTask(with: url) { [weak self] data, _, _ in
+            guard let self else { DispatchQueue.main.async { completion(nil) }; return }
+            guard let data else {
+                guard retriesLeft > 0 else { DispatchQueue.main.async { completion(nil) }; return }
+                // 间隔 2s 对齐 OC 的重试节奏，次数按项目策略压到 1 次。
+                DispatchQueue.main.asyncAfter(deadline: .now() + 2) {
+                    self.fetchAndDecode(url: url, key: key, colorHex: colorHex, size: size, retriesLeft: retriesLeft - 1, completion: completion)
+                }
+                return
+            }
+            self.decode(data: data, key: key, colorHex: colorHex, size: size, completion: completion)
+        }.resume()
+    }
+
+    private func decode(data: Data, key: NSString, colorHex: String?, size: CGSize, completion: @escaping (UIImage?) -> Void) {
+        decodeQueue.async { [weak self] in
+            self?.decodeOnQueue(data: data, key: key, colorHex: colorHex, size: size, completion: completion)
+        }
+    }
+
+    /// 调用方必须已经在 `decodeQueue` 上，避免 `SDImageSVGCoder` 被并发调用返回 nil。
+    private func decodeOnQueue(data: Data, key: NSString, colorHex: String?, size: CGSize, completion: @escaping (UIImage?) -> Void) {
+        let options: [SDImageCoderOption: Any] = [
+            .decodeThumbnailPixelSize: NSValue(cgSize: size),
+            .decodePreserveAspectRatio: true
+        ]
+        let decoded = SDImageSVGCoder.shared.decodedImage(with: data, options: options)
+        let image = decoded.flatMap { tinted($0, hex: colorHex) }
+        if let image {
+            // cost 按位图内存粗估（宽 × 高 × 4 字节 × scale²），让 totalCostLimit 真正生效。
+            let cost = Int(image.size.width * image.size.height * 4 * image.scale * image.scale)
+            cache.setObject(image, forKey: key, cost: max(cost, 1))
+        }
+        DispatchQueue.main.async { completion(image) }
+    }
+
+    private func tinted(_ image: UIImage, hex: String?) -> UIImage {
+        guard let hex, let color = UIColor.pdfReaderColorOrNil(hex: hex) else { return image }
+        let renderer = UIGraphicsImageRenderer(size: image.size)
+        return renderer.image { _ in
+            color.setFill()
+            image.draw(in: CGRect(origin: .zero, size: image.size), blendMode: .normal, alpha: 1)
+            UIRectFillUsingBlendMode(CGRect(origin: .zero, size: image.size), .sourceIn)
+        }
+    }
+}
+
+private extension UIColor {
+    static func pdfReaderColorOrNil(hex: String) -> UIColor? {
+        var value = hex.hasPrefix("#") ? String(hex.dropFirst()) : hex
+        guard value.count >= 6, let number = UInt32(String(value.prefix(6)), radix: 16) else { return nil }
+        return UIColor(red: CGFloat((number >> 16) & 255) / 255, green: CGFloat((number >> 8) & 255) / 255, blue: CGFloat(number & 255) / 255, alpha: 1)
+    }
+}

Sources/RDPDFReaderView/Sources/RDPDFReaderTrial.swift

@@ -0,0 +1,132 @@
+import UIKit
+
+/// PDF 试读策略。
+///
+/// 与 EPUB 的 `RDEPUBReaderTrialPolicy` 对齐，只是限制单位从"章节"换成"页"：
+/// PDF 是固定版式，页码本身就是稳定的切分单位，不需要 pageMap 换算。
+public struct RDPDFReaderTrialPolicy: Equatable {
+
+    /// 可读页数（可读页为 0..<readablePageCount）。
+    /// nil 或 <= 0 表示整本可读，试读墙追加在全书末尾。
+    public var readablePageCount: Int?
+
+    public init(readablePageCount: Int? = nil) {
+        self.readablePageCount = readablePageCount
+    }
+}
+
+/// 试读墙支持。
+///
+/// 设计与 EPUB 一致：`book.totalPages` 仍是原始总页数（缩略图、目录、页码换算都不受影响），
+/// 只有交给 `RDPDFReaderView` 的有效页数在启用试读墙时 +1；墙页固定位于最后一个可读页之后。
+extension RDPDFReaderViewController {
+
+    /// 试读墙视图（首次访问经 delegate 获取并缓存）
+    var trialWallView: UIView? {
+        if let cached = cachedTrialWallView {
+            return cached
+        }
+        guard configuration.trialPolicy != nil else { return nil }
+        let view = delegate?.pdfReaderTrialWallView(self)
+        cachedTrialWallView = view
+        return view
+    }
+
+    /// 是否启用试读墙：配置了试读策略且宿主提供了墙视图
+    var isTrialWallEnabled: Bool {
+        configuration.trialPolicy != nil && trialWallView != nil
+    }
+
+    /// 原始可读内容页数（不含试读墙页）
+    var readableContentPageCount: Int {
+        guard let policy = configuration.trialPolicy,
+              let readablePageCount = policy.readablePageCount,
+              readablePageCount > 0 else {
+            return book.totalPages
+        }
+        return min(readablePageCount, book.totalPages)
+    }
+
+    /// 试读墙页的绝对索引（0-based）；未启用时为 nil
+    var trialWallPageIndex: Int? {
+        guard isTrialWallEnabled else { return nil }
+        // 全书可读时墙页追加在末尾；按页限制时紧跟最后一个可读页
+        return readableContentPageCount
+    }
+
+    /// 供 RDPDFReaderView 使用的有效页数：启用试读墙时为可读页数 + 1（墙页）
+    var effectivePageCount: Int {
+        guard isTrialWallEnabled else { return book.totalPages }
+        return readableContentPageCount + 1
+    }
+
+    /// 该页是否为试读墙页
+    func isTrialWallPage(_ pageIndex: Int) -> Bool {
+        trialWallPageIndex == pageIndex
+    }
+
+    /// 构建试读墙页承载视图（铺满一页）
+    func makeTrialWallPageView(reusableView: UIView?) -> UIView {
+        let container = (reusableView as? RDPDFTrialWallContainerView) ?? RDPDFTrialWallContainerView()
+        container.setWallView(trialWallView)
+        return container
+    }
+}
+
+/// 试读墙页容器：让宿主墙视图铺满整页。
+///
+/// 宿主只提供一份墙 View，而翻页容器会预建多个页视图；这里在每次装配时把墙 View
+/// 重新挂回当前容器，避免被相邻预建页"抢走"后出现空白墙页。
+final class RDPDFTrialWallContainerView: UIView, UIGestureRecognizerDelegate {
+
+    private weak var wallView: UIView?
+
+    /// 墙页点击回调，语义对齐 `RDPDFReaderPageView.readerContentTapHandler`：
+    /// 空白区域点击应该跟普通内容页一样能显隐工具条，只是墙页是普通 UIView、
+    /// 没有实现 `RDPDFReaderPageInteractable`，接不上那条协议驱动的手势链路，
+    /// 所以单独在这里自带一个轻量点击手势。
+    var contentTapHandler: ((CGPoint) -> Void)?
+
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        let tap = UITapGestureRecognizer(target: self, action: #selector(handleTap(_:)))
+        tap.delegate = self
+        addGestureRecognizer(tap)
+    }
+
+    required init?(coder: NSCoder) { fatalError("init(coder:) has not been implemented") }
+
+    func setWallView(_ view: UIView?) {
+        // 即使 View 对象相同，只要它已被其他复用容器接管，也必须重新挂回当前页。
+        if wallView === view, view?.superview === self {
+            return
+        }
+        wallView?.removeFromSuperview()
+        guard let view else { return }
+        view.translatesAutoresizingMaskIntoConstraints = false
+        addSubview(view)
+        NSLayoutConstraint.activate([
+            view.leadingAnchor.constraint(equalTo: leadingAnchor),
+            view.trailingAnchor.constraint(equalTo: trailingAnchor),
+            view.topAnchor.constraint(equalTo: topAnchor),
+            view.bottomAnchor.constraint(equalTo: bottomAnchor)
+        ])
+        wallView = view
+    }
+
+    @objc private func handleTap(_ gesture: UITapGestureRecognizer) {
+        contentTapHandler?(gesture.location(in: self))
+    }
+
+    /// 墙视图内部的按钮（登录/购买入口）要保留自己的点击语义，不能被这里的
+    /// 点击手势吞掉。沿 touch.view 往上找到 self 之间只要经过任意 `UIControl`
+    /// 就放行给它自己处理，比只排除某一个具体按钮更通用，不受墙视图内部结构变化影响。
+    func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer, shouldReceive touch: UITouch) -> Bool {
+        var view = touch.view
+        while let current = view, current !== self {
+            if current is UIControl { return false }
+            view = current.superview
+        }
+        return true
+    }
+}

Sources/RDPDFReaderView/Sources/RDPDFReaderViewController.swift

@@ -30,11 +30,15 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
         public var ocrMemoryCacheRadius: Int?
         /// 宿主或内置 Provider 提供页面后，可在此进行反色或其它主题渲染。
         public var pageImageTransform: ((UIImage, RDPDFReaderThemeOption) -> UIImage)?
+        /// 试读策略。非 nil 且宿主经 delegate 提供了墙视图时启用试读墙。
+        public var trialPolicy: RDPDFReaderTrialPolicy?
 
         public init() {}
     }
 
     public weak var delegate: RDPDFReaderViewControllerDelegate?
+    /// 点读书热区由 SDK 命中，媒体/网页/路由等业务仍由宿主处理。
+    public var interactionHandler: ((RDPDFReaderPageInteraction, Int) -> Void)?
     public let pageProvider: RDPDFReaderPageProvider
     public weak var persistence: RDPDFReaderPersistence?
     public let annotationPersistence: RDPDFReaderAnnotationPersisting?
@@ -42,10 +46,63 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
 
     public var currentPageIndex: Int { max(0, readerView.currentPage) }
 
+    /// 宿主提供的试读墙视图，只取一次并复用（见 RDPDFReaderTrial.swift）
+    var cachedTrialWallView: UIView?
+
+    /// 设置当前正在下载或播放的点读热区；SDK 仅负责视觉反馈，业务播放仍留给宿主。
+    public func setActiveInteraction(identifier: String?) {
+        visiblePageViews().forEach { $0.setActiveInteraction(identifier: identifier) }
+    }
+
+    /// 底部工具栏是否展示"点读提示"按钮。宿主确认本书含点读热区后置 true，
+    /// 对齐 OC 工具栏 `linkFlashButton` 的显示条件。
+    public var showsInteractionFlashButton = false {
+        didSet {
+            guard showsInteractionFlashButton != oldValue else { return }
+            bottomToolbar?.setInteractionFlashHidden(!showsInteractionFlashButton)
+        }
+    }
+
+    /// 让当前可见页的点读热区重新闪烁一轮，帮助用户定位可点击区域。
+    public func flashInteractions() {
+        visiblePageViews().forEach { $0.flashInteractions() }
+    }
+
+    /// 连播按钮点击回调；由宿主接管连播的启停逻辑（跨页音频状态机在业务层）。
+    public var onToggleSequentialPlay: (() -> Void)?
+
+    /// loop 按钮是否展示：当前页存在 autoPlay 音频热区时宿主置 true，对齐 OC
+    /// `isShowLoopPlayerBtnState:` 的 loop 规则（3.0 数据不产生 `ShowEmbedImage`，
+    /// img 分支恒不适用，见 `RDPDFReaderKitBottomToolView` 注释）。
+    public var showsLoopButton = false {
+        didSet {
+            guard showsLoopButton != oldValue else { return }
+            bottomToolbar?.setLoopButtonHidden(!showsLoopButton)
+        }
+    }
+
+    /// loop 按钮图标状态：是否正在连播。
+    public var isLoopActive = false {
+        didSet {
+            guard isLoopActive != oldValue else { return }
+            bottomToolbar?.setLoopButtonActive(isLoopActive)
+        }
+    }
+
+    /// 宿主异步补齐了互动附件后使指定页失效并重新请求；不重置阅读位置或笔迹状态。
+    public func reloadPageContent(at pageIndex: Int) {
+        guard pageIndex >= 0, pageIndex < book.totalPages else { return }
+        clearPageDescriptorRequest(for: pageIndex)
+        pageDescriptors.removeValue(forKey: pageIndex)
+        pageLoadFailedPages.remove(pageIndex)
+        pageDescriptorRequestAttempts[pageIndex] = 0
+        refreshPageViews(at: pageIndex)
+    }
+
     private let readerView = RDPDFReaderView()
     private let recognizer: RDPDFReaderImageTextRecognizer
     private let ocrDiskCache: RDPDFReaderTextRunDiskCache?
-    private var book: RDPDFReaderBookDescriptor
+    private(set) var book: RDPDFReaderBookDescriptor
     private var currentTheme: RDPDFReaderThemeOption
     private var pageDescriptors: [Int: RDPDFReaderPageDescriptor] = [:]
     /// 已创建但不一定在屏幕上的页面视图。UIPageViewController 与 UICollectionView
@@ -165,7 +222,7 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
         view.addSubview(readerView)
         readerView.reloadData()
         applyDisplayTypeForCurrentInterface()
-        if let page = persistence?.restoreReadingPage(for: book.identifier), page >= 0, page < book.totalPages {
+        if let page = persistence?.restoreReadingPage(for: book.identifier), page >= 0, page < readableContentPageCount {
             readerView.transitionToPage(pageNum: page, animated: false)
         }
         bookmarks = Set(persistence?.loadBookmarks(for: book.identifier).map(\.pageIndex) ?? [])
@@ -218,7 +275,8 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
     }
 
     public func goToPage(_ pageIndex: Int, animated: Bool = false) {
-        guard pageIndex >= 0, pageIndex < book.totalPages else { return }
+        // 试读时上界收敛到可读页；否则点读热区跳页/目录可跳进未授权页
+        guard pageIndex >= 0, pageIndex < readableContentPageCount else { return }
         readerView.transitionToPage(pageNum: pageIndex, animated: animated)
     }
 
@@ -269,11 +327,7 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
     public func showSpeechHighlight(pageIndex: Int, normalizedRects: [CGRect], animated: Bool = true) {
         guard pageIndex >= 0, pageIndex < book.totalPages else { return }
         speechHighlight = normalizedRects.isEmpty ? nil : (pageIndex, normalizedRects)
-        // `willSpeakRangeOfSpeechString` 会在同一句内多次回调。相同页面只需刷新
-        // 临时高亮，重复调用翻页入口会让仿真翻页在朗读过程中不断播放转场动画。
-        if currentPageIndex != pageIndex {
-            goToPage(pageIndex, animated: animated)
-        }
+        goToPage(pageIndex, animated: animated)
         refreshPageViews(at: pageIndex)
     }
 
@@ -295,9 +349,12 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
         updateDrawingInteractionState()
     }
 
-    public func pageCountOfReaderView(readerView: RDPDFReaderView) -> Int { book.totalPages }
+    public func pageCountOfReaderView(readerView: RDPDFReaderView) -> Int { effectivePageCount }
 
     public func pageContentView(readerView: RDPDFReaderView, pageNum: Int) -> UIView {
+        if isTrialWallPage(pageNum) {
+            return makeTrialWallPageView(reusableView: nil)
+        }
         let page = RDPDFReaderPageView()
         page.delegate = self
         // ReaderView 会在返回后再写一次 tag；这里提前写入，异步页面数据返回时
@@ -326,6 +383,12 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
         toolbar.onShowAnnotations = { [weak self] in self?.showAnnotations() }
         toolbar.onStartDrawing = { [weak self] in self?.setDrawingMode(true) }
         toolbar.onShowSettings = { [weak self] in self?.showSettings() }
+        toolbar.onFlashInteractions = { [weak self] in self?.flashInteractions() }
+        toolbar.onToggleSequentialPlay = { [weak self] in self?.onToggleSequentialPlay?() }
+        // 工具栏是懒创建的：重建后要按当前状态重新决定各按钮是否可见/图标状态
+        toolbar.setInteractionFlashHidden(!showsInteractionFlashButton)
+        toolbar.setLoopButtonHidden(!showsLoopButton)
+        toolbar.setLoopButtonActive(isLoopActive)
         bottomToolbar = toolbar
         applyChromeTheme()
         return toolbar
@@ -333,6 +396,14 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
 
     public func pageNum(readerView: RDPDFReaderView, pageNum: Int) {
         guard pageNum >= 0 else { return }
+        if isTrialWallPage(pageNum) {
+            // 墙页不是内容页：不做 OCR、不写阅读进度、不参与书签
+            title = book.title
+            topToolbar?.setTitle(book.title)
+            topToolbar?.setBookmarkSelected(false)
+            delegate?.pdfReaderDidReachTrialWall(self)
+            return
+        }
         // OCR 队列是串行的。快速翻页后取消过期任务，避免停留页排在大量离开页之后。
         cancelOutstandingOCRRequests()
         // 翻到的页可能是提前构建的视图：它在离屏期间收到过页面数据，也可能因内存
@@ -357,7 +428,7 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
             around: pageNum,
             radius: configuration.pageDescriptorCacheRadius
         )
-        title = "PDF · \(pageNum + 1) / \(book.totalPages)"
+        title = "PDF · \(pageNum + 1) / \(readableContentPageCount)"
         topToolbar?.setTitle(title ?? book.title)
         topToolbar?.setBookmarkSelected(bookmarks.contains(pageNum))
         persistence?.saveReadingPage(pageNum, for: book.identifier)
@@ -438,6 +509,7 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
         let runs = descriptor?.textRuns ?? ocrRuns[index] ?? []
         let source: RDPDFReaderAnnotationSource = descriptor?.textRuns != nil ? .text : (configuration.enablesOCR ? .ocr : configuration.missingTextSource)
         page.configureTextLayer(pageIndex: index, textRuns: runs, textSource: source, annotations: annotations(for: index))
+        page.configureInteractions(descriptor?.interactions ?? [])
         page.setSpeechHighlightRects(speechHighlight?.pageIndex == index ? speechHighlight?.rects ?? [] : [])
         page.isDrawingSessionActive = isDrawingMode
         page.isDrawingMode = isDrawingMode && currentDrawingTool != nil
@@ -650,13 +722,15 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
             return
         }
         let outline = (pageProvider as? RDPDFReaderOutlineProviding)?.readerOutlineItems()
-            ?? (0..<book.totalPages).map { .init(title: "第 \($0 + 1) 页", pageIndex: $0) }
+            ?? (0..<readableContentPageCount).map { .init(title: "第 \($0 + 1) 页", pageIndex: $0) }
         presentNavigation(outline: outline)
     }
 
     private func presentNavigation(outline: [RDPDFReaderOutlineItem]) {
         let marks = bookmarks.sorted().map { RDPDFReaderBookmark(pageIndex: $0, title: "第 \($0 + 1) 页") }
-        let panel = RDPDFReaderNavigationPanelViewController(outlineItems: outline, bookmarks: marks, totalPages: book.totalPages, thumbnailProvider: { [weak self] index, size, completion in
+        // 试读时目录、缩略图与页码都收敛到可读范围，避免用户跳进未授权页
+        let readableOutline = outline.filter { $0.pageIndex < readableContentPageCount }
+        let panel = RDPDFReaderNavigationPanelViewController(outlineItems: readableOutline, bookmarks: marks, totalPages: readableContentPageCount, thumbnailProvider: { [weak self] index, size, completion in
             guard let self else {
                 DispatchQueue.main.async { completion(nil) }
                 return
@@ -881,6 +955,9 @@ public final class RDPDFReaderViewController: UIViewController, RDPDFReaderDataS
     public func pageView(_ pageView: RDPDFReaderPageView, didCopyText text: String) {
         delegate?.pdfReaderViewController(self, didCopyText: text)
     }
+    public func pageView(_ pageView: RDPDFReaderPageView, didTap interaction: RDPDFReaderPageInteraction) {
+        interactionHandler?(interaction, pageView.pageIndex)
+    }
     public func pageView(_ pageView: RDPDFReaderPageView, didRequestHighlight selection: RDPDFReaderImageTextSelection, color: String) { add(selection, page: pageView.pageIndex, color: color, note: nil) }
     public func pageView(_ pageView: RDPDFReaderPageView, didRequestAnnotation selection: RDPDFReaderImageTextSelection) { presentEditor(selection: selection, page: pageView.pageIndex) }
     public func pageView(_ pageView: RDPDFReaderPageView, didOpenAnnotation annotation: RDPDFReaderAnnotation) { presentEditor(annotation: annotation) }
@@ -920,6 +997,14 @@ public protocol RDPDFReaderViewControllerDelegate: AnyObject {
     func pdfReaderViewController(_ controller: RDPDFReaderViewController, didFailAnnotationPersistence error: Error)
     /// 用户通过选区菜单复制文字后回调；宿主可在此做提示或埋点。
     func pdfReaderViewController(_ controller: RDPDFReaderViewController, didCopyText text: String)
+
+    /// 提供试读墙视图（configuration.trialPolicy 非 nil 时生效）。
+    /// 返回非 nil 时，阅读器在最后一个可读页之后追加一页展示该视图；返回 nil 则不追加试读墙。
+    /// 视图上的购买 / 登录按钮由宿主自行处理（授权成功后可重建阅读器切换到全本）。
+    func pdfReaderTrialWallView(_ controller: RDPDFReaderViewController) -> UIView?
+
+    /// 用户翻到试读墙页时回调（宿主可在此触发购买引导 / 埋点等）。
+    func pdfReaderDidReachTrialWall(_ controller: RDPDFReaderViewController)
 }
 
 public extension RDPDFReaderViewControllerDelegate {
@@ -927,4 +1012,6 @@ public extension RDPDFReaderViewControllerDelegate {
     func pdfReaderViewController(_ controller: RDPDFReaderViewController, didChangePage pageIndex: Int) {}
     func pdfReaderViewController(_ controller: RDPDFReaderViewController, didFailAnnotationPersistence error: Error) {}
     func pdfReaderViewController(_ controller: RDPDFReaderViewController, didCopyText text: String) {}
+    func pdfReaderTrialWallView(_ controller: RDPDFReaderViewController) -> UIView? { nil }
+    func pdfReaderDidReachTrialWall(_ controller: RDPDFReaderViewController) {}
 }