// RDEPUBTextPaginationInterfaces.swift
// EPUB 分页接口定义，包括断页决策、章节数页和页面帧构建协议。

import Foundation
import UIKit

// MARK: - 分页接口定义

/// 单次断页决策，记录断页位置、原因及诊断信息。
struct RDEPUBPageBreakDecision {
    /// 本页在富文本中的字符范围
    var range: NSRange
    /// 断页原因
    var reason: RDEPUBTextPageBreakReason
    /// 分页过程中的诊断日志
    var diagnostics: [String]
}

/// 章节页数计算接口，将富文本按页面尺寸拆分为断页决策序列。
protocol RDEPUBChapterPageCounting {
    /// 计算章节中每页的断页位置。
    /// - Parameters:
    ///   - attributedString: 章节富文本
    ///   - pageSize: 页面尺寸
    ///   - config: 排版配置
    ///   - fragmentOffsets: fragment 锚点偏移映射
    /// - Returns: 断页决策数组，每个元素对应一页
    func pageRanges(
        for attributedString: NSAttributedString,
        pageSize: CGSize,
        config: RDEPUBTextLayoutConfig,
        fragmentOffsets: [String: Int]
    ) -> [RDEPUBPageBreakDecision]
}

/// 页面帧构建接口，将富文本转换为可渲染的页面帧数组。
protocol RDEPUBPageFrameBuilding {
    /// 将富文本构建为页面帧数组。
    /// - Parameters:
    ///   - attributedString: 待分页的富文本
    ///   - pageSize: 页面尺寸
    ///   - config: 排版配置
    ///   - fragmentOffsets: fragment 锚点偏移映射
    /// - Returns: 页面帧数组
    func makeFrames(
        attributedString: NSAttributedString,
        pageSize: CGSize,
        config: RDEPUBTextLayoutConfig,
        fragmentOffsets: [String: Int]
    ) -> [RDEPUBTextLayoutFrame]
}