import Foundation

/// CoreText 分页引擎产生的单帧（单页）布局数据。
///
/// 由 `RDEPUBTextLayouter` 在分页过程中生成，记录了该页的内容范围、分页原因、
/// 附件信息和语义标记。`RDEPUBTextBookBuilder` 会将 `RDEPUBTextLayoutFrame` 转换为
/// `RDEPUBTextPage`，并纳入最终的 `RDEPUBTextBook` 模型。
struct RDEPUBTextLayoutFrame: Equatable {
    /// 该帧在章节富文本中的字符范围
    var contentRange: NSRange
    /// 分页原因（语义边界、附件边界、帧限制等）
    var breakReason: RDEPUBTextPageBreakReason
    /// 所属 HTML 块级元素的范围（用于调试）
    var blockRange: NSRange?
    /// 帧内附件的字符范围列表
    var attachmentRanges: [NSRange]
    /// 帧内附件类型列表（图片、通用附件等）
    var attachmentKinds: [RDEPUBTextAttachmentKind]
    /// 帧内包含的 HTML 块级元素类型列表（段落、列表、表格等）
    var blockKinds: [RDEPUBTextBlockKind]
    /// 帧内语义提示列表（避免分页、保持与下一段同页等）
    var semanticHints: [RDEPUBTextSemanticHint]
    /// 帧内附件的布局方式（行内、基线、居中）
    var attachmentPlacements: [RDEPUBTextAttachmentPlacement]
    /// 帧尾部最近的 fragment ID（用于恢复阅读位置）
    var trailingFragmentID: String?
    /// 诊断日志列表（分页原因详情、范围信息等）
    var diagnostics: [String]

    /// 将布局帧数据转换为页元数据模型
    var metadata: RDEPUBTextPageMetadata {
        RDEPUBTextPageMetadata(
            breakReason: breakReason,
            blockRange: blockRange,
            attachmentRanges: attachmentRanges,
            attachmentKinds: attachmentKinds,
            blockKinds: blockKinds,
            semanticHints: semanticHints,
            attachmentPlacements: attachmentPlacements,
            trailingFragmentID: trailingFragmentID,
            diagnostics: diagnostics
        )
    }
}