rpdfium_doc/

annotation.rs

// Derived from PDFium's cpdf_annot.h/cpp
// Original: Copyright 2014 The PDFium Authors
// Licensed under BSD-3-Clause / Apache-2.0
// See pdfium-upstream/LICENSE for the original license.

//! PDF annotation types and parsing — `CPDF_Annot` (ISO 32000-2 section 12.5).
//!
//! A single annotation: its type, rectangle, contents, appearance, and
//! subtype-specific fields. List-level parsing (`parse_annotations`) and
//! popup parent lookup (`find_parent_annotation`) are in [`crate::annot_list`].

use rpdfium_core::{Name, PdfSource};
use rpdfium_parser::{Object, ObjectId, ObjectStore};

use crate::aaction::{AActionType, AdditionalActions, parse_additional_actions};
use crate::action::{Action, parse_action};
use crate::annotation_appearance::{AnnotationAppearance, extract_appearance};
use crate::ap_settings::{MkDict, parse_mk_dict};
use crate::default_appearance::parse_default_appearance;
use crate::destination::{Destination, parse_destination};
use crate::error::{DocError, DocResult};
use crate::file_spec::{FileSpec, parse_file_spec};
use crate::form_field::{ChoiceOption, FormFieldFlags, FormFieldType};

/// PDF object type tag for annotation dictionary values.
///
/// Corresponds to the `FPDF_OBJECT_TYPE` enum in the upstream PDFium public API
/// (`public/fpdf_annot.h`, `FPDFAnnot_GetValueType()`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PdfValueType {
    /// The key is absent from the annotation dictionary.
    Unknown = 0,
    /// The value is a boolean.
    Boolean = 1,
    /// The value is an integer or real number.
    Number = 2,
    /// The value is a PDF string.
    String = 3,
    /// The value is a PDF name.
    Name = 4,
    /// The value is an array.
    Array = 5,
    /// The value is a dictionary.
    Dictionary = 6,
    /// The value is a stream.
    Stream = 7,
    /// The value is the PDF null object.
    Null = 8,
    /// The value is an indirect reference.
    Reference = 9,
}

/// Annotation appearance mode — selects which `/AP` sub-stream to use.
///
/// Corresponds to `FPDF_ANNOT_APPEARANCEMODE` in the upstream PDFium API
/// (`public/fpdf_annot.h`, `FPDFAnnot_GetAP()` / `FPDFAnnot_SetAP()`).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AppearanceMode {
    /// Normal appearance (`/AP /N`).
    Normal,
    /// Rollover appearance (`/AP /R`).
    Rollover,
    /// Down (mouse-press) appearance (`/AP /D`).
    Down,
}

/// Subtype-specific annotation data.
///
/// Contains fields that are only relevant to specific annotation subtypes,
/// such as `/QuadPoints` for markup annotations, `/L` for line annotations, etc.
#[derive(Debug, Clone, Default)]
pub struct AnnotationSubtypeData {
    /// QuadPoints for Highlight, Underline, Squiggly, StrikeOut, Link annotations.
    /// Each group of 8 values defines a quadrilateral: [x1,y1, x2,y2, x3,y3, x4,y4].
    pub quad_points: Option<Vec<f32>>,
    /// Line endpoints for Line annotations: [x1, y1, x2, y2].
    pub line_points: Option<[f32; 4]>,
    /// Leader line length for Line annotations.
    pub leader_line_length: Option<f32>,
    /// Vertices for Polygon and PolyLine annotations.
    pub vertices: Option<Vec<f32>>,
    /// Ink strokes for Ink annotations.
    /// Each inner Vec represents one stroke as a sequence of [x, y] pairs.
    pub ink_list: Option<Vec<Vec<f32>>>,
    /// Default appearance string for FreeText annotations.
    pub default_appearance: Option<String>,
    /// Stamp name (icon) for Stamp annotations.
    pub stamp_name: Option<String>,
}

/// A PDF annotation parsed from a page's `/Annots` array.
#[derive(Debug, Clone)]
pub struct Annotation {
    /// The type of annotation.
    pub subtype: AnnotationType,
    /// Annotation rectangle in user space: `[x1, y1, x2, y2]`.
    pub rect: [f32; 4],
    /// Contents of the annotation (the `/Contents` key).
    pub contents: Option<String>,
    /// Annotation flags (bit field from `/F`).
    pub flags: AnnotationFlags,
    /// Unique name of the annotation (from `/NM`).
    pub name: Option<String>,
    /// Appearance streams (from `/AP`).
    pub appearance: Option<AnnotationAppearance>,
    /// Color array (from `/C`).
    pub color: Option<Vec<f32>>,
    /// Border specification.
    pub border: Option<AnnotationBorder>,
    /// Associated action (from `/A`).
    pub action: Option<Action>,
    /// Destination (from `/Dest`).
    pub destination: Option<Destination>,
    /// Subtype-specific fields parsed from the annotation dictionary.
    pub subtype_data: AnnotationSubtypeData,
    /// Widget appearance characteristics (`/MK`).
    pub mk: Option<MkDict>,
    /// File specification for FileAttachment annotations (`/FS`).
    pub file_spec: Option<FileSpec>,
    /// Parent annotation reference for Popup annotations (`/Parent`).
    pub parent_ref: Option<ObjectId>,
    /// This annotation's own object ID (from the indirect reference).
    pub object_id: Option<ObjectId>,
    /// Open state for Text/Popup annotations (`/Open`).
    pub open: Option<bool>,
    /// Decoded bytes of the normal appearance stream (`/AP /N`), if present.
    ///
    /// Populated during parsing. Corresponds to `FPDFAnnot_GetAP()` with
    /// `FPDF_ANNOT_APPEARANCEMODE_NORMAL`.
    pub ap_n_bytes: Option<Vec<u8>>,
    /// Decoded bytes of the rollover appearance stream (`/AP /R`), if present.
    ///
    /// Populated during parsing. Corresponds to `FPDFAnnot_GetAP()` with
    /// `FPDF_ANNOT_APPEARANCEMODE_ROLLOVER`.
    pub ap_r_bytes: Option<Vec<u8>>,
    /// Decoded bytes of the down appearance stream (`/AP /D`), if present.
    ///
    /// Populated during parsing. Corresponds to `FPDFAnnot_GetAP()` with
    /// `FPDF_ANNOT_APPEARANCEMODE_DOWN`.
    pub ap_d_bytes: Option<Vec<u8>>,
    /// Object ID of the annotation referenced by `/IRT` ("In Reply To"), if any.
    ///
    /// Present on annotations that are replies to another annotation.
    /// Corresponds to `FPDFAnnot_GetLinkedAnnot()`.
    pub irt_ref: Option<ObjectId>,
    /// Partial field name from `/T`.
    ///
    /// For widget annotations this is the form field name; for other annotation
    /// types it serves as the annotation title / author label.
    /// Corresponds to `FPDFAnnot_GetFormFieldName()`.
    pub field_name: Option<String>,
    /// Alternate (user-visible) field name from `/TU`.
    ///
    /// Only meaningful for widget annotations.
    /// Corresponds to `FPDFAnnot_GetFormFieldAlternateName()`.
    pub alternate_name: Option<String>,
    /// Current field value as a string from `/V`.
    ///
    /// For text fields this is the text value; for choice fields it is the
    /// selected option string; for check-box / radio-button fields it is the
    /// appearance state name.
    /// Corresponds to `FPDFAnnot_GetFormFieldValue()`.
    pub field_value: Option<String>,
    /// Form field flags from `/Ff` — only meaningful for widget (form field) annotations.
    ///
    /// Contains the field-specific flags such as read-only, required, multiline,
    /// password, etc.
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldFlags()`.
    pub form_field_flags: Option<FormFieldFlags>,
    /// Additional actions for Widget annotations (`/AA`).
    ///
    /// Contains event-triggered JavaScript actions for form field widgets.
    /// Populated during parsing for Widget annotations.
    /// Corresponds to `FPDFAnnot_GetFormAdditionalActionJavaScript()`.
    pub additional_actions: Option<AdditionalActions>,
    /// Form field type from `/FT` (Widget annotations).
    ///
    /// `Some(Text | Button | Choice | Signature)` when the annotation
    /// dictionary carries an `/FT` key directly; `None` for non-widget
    /// annotations or when `/FT` is inherited from the parent field.
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldType()`.
    pub form_field_type: Option<FormFieldType>,
    /// Choice-field options parsed from `/Opt` (Widget annotations with `/FT Ch`).
    ///
    /// Each entry has an `export_value` (submitted to server) and a
    /// `display_value` (shown to user).  `None` for non-choice annotations.
    ///
    /// Corresponds to `FPDFAnnot_GetOptionCount()` / `FPDFAnnot_GetOptionLabel()`.
    pub options: Option<Vec<ChoiceOption>>,
}

/// Annotation subtypes defined by the PDF specification.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AnnotationType {
    /// Text (sticky note) annotation.
    Text,
    /// Link annotation.
    Link,
    /// Free text annotation.
    FreeText,
    /// Line annotation.
    Line,
    /// Square annotation.
    Square,
    /// Circle annotation.
    Circle,
    /// Polygon annotation.
    Polygon,
    /// Polyline annotation.
    PolyLine,
    /// Highlight markup annotation.
    Highlight,
    /// Underline markup annotation.
    Underline,
    /// Squiggly underline markup annotation.
    Squiggly,
    /// Strikeout markup annotation.
    StrikeOut,
    /// Stamp annotation.
    Stamp,
    /// Caret annotation.
    Caret,
    /// Ink annotation.
    Ink,
    /// Popup annotation.
    Popup,
    /// File attachment annotation.
    FileAttachment,
    /// Sound annotation.
    Sound,
    /// Widget annotation (form field).
    Widget,
    /// Movie annotation.
    Movie,
    /// Screen annotation.
    Screen,
    /// Printer's mark annotation.
    PrinterMark,
    /// Trap network annotation.
    TrapNet,
    /// Watermark annotation.
    Watermark,
    /// 3D annotation.
    ThreeD,
    /// Rich media annotation.
    RichMedia,
    /// XFA widget annotation.
    XFAWidget,
    /// Redaction annotation.
    Redact,
    /// Unrecognized annotation subtype.
    Other,
}

impl AnnotationType {
    /// Returns `true` if this annotation subtype supports appearance stream (AP)
    /// object manipulation via `FPDFAnnot_AppendObject` etc.
    ///
    /// The supported subtypes are: Stamp, FreeText, Ink, Square, Circle, Polygon,
    /// PolyLine, Line, Highlight, Underline, Squiggly, StrikeOut.
    ///
    /// Corresponds to `FPDFAnnot_IsObjectSupportedSubtype()`.
    pub fn supports_ap_objects(&self) -> bool {
        matches!(
            self,
            AnnotationType::Stamp
                | AnnotationType::FreeText
                | AnnotationType::Ink
                | AnnotationType::Square
                | AnnotationType::Circle
                | AnnotationType::Polygon
                | AnnotationType::PolyLine
                | AnnotationType::Line
                | AnnotationType::Highlight
                | AnnotationType::Underline
                | AnnotationType::Squiggly
                | AnnotationType::StrikeOut
        )
    }

    /// ADR-019 alias for [`Self::supports_ap_objects()`].
    ///
    /// Corresponds to `FPDFAnnot_IsObjectSupportedSubtype()`.
    #[inline]
    pub fn annot_is_object_supported_subtype(&self) -> bool {
        self.supports_ap_objects()
    }

    /// Deprecated: use [`annot_is_object_supported_subtype()`](Self::annot_is_object_supported_subtype) instead.
    #[deprecated(
        since = "0.1.0",
        note = "use annot_is_object_supported_subtype() instead"
    )]
    #[inline]
    pub fn is_object_supported_subtype(&self) -> bool {
        self.supports_ap_objects()
    }

    /// Deprecated: use [`annot_is_object_supported_subtype()`](Self::annot_is_object_supported_subtype) instead.
    #[deprecated(
        since = "0.1.0",
        note = "use annot_is_object_supported_subtype() instead"
    )]
    #[inline]
    pub fn is_ap_object_supported(&self) -> bool {
        self.supports_ap_objects()
    }

    /// Returns whether this annotation subtype is currently supported for creation.
    ///
    /// Currently supported subtypes: circle, fileattachment, freetext, highlight,
    /// ink, link, popup, square, squiggly, stamp, strikeout, text, underline.
    ///
    /// Corresponds to `FPDFAnnot_IsSupportedSubtype`.
    pub fn is_supported_for_creation(&self) -> bool {
        matches!(
            self,
            AnnotationType::Circle
                | AnnotationType::FileAttachment
                | AnnotationType::FreeText
                | AnnotationType::Highlight
                | AnnotationType::Ink
                | AnnotationType::Link
                | AnnotationType::Popup
                | AnnotationType::Square
                | AnnotationType::Squiggly
                | AnnotationType::Stamp
                | AnnotationType::StrikeOut
                | AnnotationType::Text
                | AnnotationType::Underline
        )
    }

    /// ADR-019 alias for [`Self::is_supported_for_creation()`].
    ///
    /// Corresponds to `FPDFAnnot_IsSupportedSubtype`.
    #[inline]
    pub fn annot_is_supported_subtype(&self) -> bool {
        self.is_supported_for_creation()
    }

    /// Deprecated: use [`annot_is_supported_subtype()`](Self::annot_is_supported_subtype) instead.
    #[deprecated(since = "0.1.0", note = "use annot_is_supported_subtype() instead")]
    #[inline]
    pub fn is_supported_subtype(&self) -> bool {
        self.is_supported_for_creation()
    }

    /// Parse an annotation subtype from a PDF name string.
    pub fn from_name(name: &str) -> Self {
        match name {
            "Text" => Self::Text,
            "Link" => Self::Link,
            "FreeText" => Self::FreeText,
            "Line" => Self::Line,
            "Square" => Self::Square,
            "Circle" => Self::Circle,
            "Polygon" => Self::Polygon,
            "PolyLine" => Self::PolyLine,
            "Highlight" => Self::Highlight,
            "Underline" => Self::Underline,
            "Squiggly" => Self::Squiggly,
            "StrikeOut" => Self::StrikeOut,
            "Stamp" => Self::Stamp,
            "Caret" => Self::Caret,
            "Ink" => Self::Ink,
            "Popup" => Self::Popup,
            "FileAttachment" => Self::FileAttachment,
            "Sound" => Self::Sound,
            "Widget" => Self::Widget,
            "Movie" => Self::Movie,
            "Screen" => Self::Screen,
            "PrinterMark" => Self::PrinterMark,
            "TrapNet" => Self::TrapNet,
            "Watermark" => Self::Watermark,
            "3D" => Self::ThreeD,
            "RichMedia" => Self::RichMedia,
            "XFAWidget" => Self::XFAWidget,
            "Redact" => Self::Redact,
            _ => Self::Other,
        }
    }

    /// Returns the PDF subtype name string for this annotation type.
    /// Inverse of `from_name()`. Corresponds to upstream `AnnotSubtypeToString()`.
    pub fn to_name(&self) -> &'static str {
        match self {
            Self::Text => "Text",
            Self::Link => "Link",
            Self::FreeText => "FreeText",
            Self::Line => "Line",
            Self::Square => "Square",
            Self::Circle => "Circle",
            Self::Polygon => "Polygon",
            Self::PolyLine => "PolyLine",
            Self::Highlight => "Highlight",
            Self::Underline => "Underline",
            Self::Squiggly => "Squiggly",
            Self::StrikeOut => "StrikeOut",
            Self::Stamp => "Stamp",
            Self::Caret => "Caret",
            Self::Ink => "Ink",
            Self::Popup => "Popup",
            Self::FileAttachment => "FileAttachment",
            Self::Sound => "Sound",
            Self::Widget => "Widget",
            Self::Movie => "Movie",
            Self::Screen => "Screen",
            Self::PrinterMark => "PrinterMark",
            Self::TrapNet => "TrapNet",
            Self::Watermark => "Watermark",
            Self::ThreeD => "3D",
            Self::RichMedia => "RichMedia",
            Self::XFAWidget => "XFAWidget",
            Self::Redact => "Redact",
            Self::Other => "Unknown",
        }
    }
}

/// Annotation flags (ISO 32000-2 section 12.5.3, Table 165).
///
/// The flags are stored as a 32-bit integer where each bit has a specific
/// meaning defined by the specification.
#[derive(Debug, Clone, Copy, Default)]
pub struct AnnotationFlags(u32);

impl AnnotationFlags {
    /// Create flags from a raw integer value.
    pub fn from_bits(bits: u32) -> Self {
        Self(bits)
    }

    /// Get the raw bits.
    pub fn bits(&self) -> u32 {
        self.0
    }

    /// Bit 1: If set, do not display the annotation if it does not belong to
    /// one of the standard annotation types.
    pub fn invisible(&self) -> bool {
        self.0 & 1 != 0
    }

    /// Bit 2: If set, do not display or print the annotation.
    pub fn hidden(&self) -> bool {
        self.0 & 2 != 0
    }

    /// Bit 3: If set, print the annotation when the page is printed.
    pub fn print(&self) -> bool {
        self.0 & 4 != 0
    }

    /// Bit 4: If set, do not scale the annotation's appearance to match the
    /// magnification of the page.
    pub fn no_zoom(&self) -> bool {
        self.0 & 8 != 0
    }

    /// Bit 5: If set, do not rotate the annotation's appearance to match the
    /// rotation of the page.
    pub fn no_rotate(&self) -> bool {
        self.0 & 16 != 0
    }

    /// Bit 6: If set, do not display the annotation on the screen.
    pub fn no_view(&self) -> bool {
        self.0 & 32 != 0
    }

    /// Bit 7: If set, the annotation is read-only.
    pub fn read_only(&self) -> bool {
        self.0 & 64 != 0
    }

    /// Bit 8: If set, do not allow the annotation to be deleted or modified.
    pub fn locked(&self) -> bool {
        self.0 & 128 != 0
    }

    /// Bit 9: If set, invert the NoView flag when the cursor enters/exits the
    /// annotation's bounding box.
    pub fn toggle_no_view(&self) -> bool {
        self.0 & 256 != 0
    }

    /// Bit 10: If set, the annotation's contents cannot be changed while the
    /// annotation is locked.
    pub fn locked_contents(&self) -> bool {
        self.0 & 512 != 0
    }

    /// Returns true if the annotation should be visible for screen display.
    pub fn is_visible(&self) -> bool {
        !self.hidden() && !self.no_view()
    }
}

/// Annotation border specification.
#[derive(Debug, Clone)]
pub struct AnnotationBorder {
    /// Border width in points.
    pub width: f32,
    /// Border style.
    pub style: BorderStyle,
}

impl Default for AnnotationBorder {
    fn default() -> Self {
        Self {
            width: 1.0,
            style: BorderStyle::Solid,
        }
    }
}

/// Border styles for annotations.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BorderStyle {
    /// Solid line.
    Solid,
    /// Dashed line.
    Dashed,
    /// Beveled (raised) border.
    Beveled,
    /// Inset (sunken) border.
    Inset,
    /// Underline only.
    Underline,
}

impl BorderStyle {
    /// Parse a border style from a PDF name string.
    pub fn from_name(name: &str) -> Self {
        match name {
            "S" => Self::Solid,
            "D" => Self::Dashed,
            "B" => Self::Beveled,
            "I" => Self::Inset,
            "U" => Self::Underline,
            _ => Self::Solid,
        }
    }
}

/// Parse a single annotation from its dictionary.
pub(crate) fn parse_single_annotation<S: PdfSource>(
    obj: &Object,
    store: &ObjectStore<S>,
    object_id: Option<ObjectId>,
) -> DocResult<Annotation> {
    let dict = obj.as_dict().ok_or(DocError::UnexpectedType)?;

    // /Subtype (required)
    let subtype = dict
        .get(&Name::subtype())
        .and_then(|o| {
            store
                .deep_resolve(o)
                .ok()
                .and_then(|r| r.as_name().map(|n| n.as_str().into_owned()))
        })
        .map(|s| AnnotationType::from_name(&s))
        .unwrap_or(AnnotationType::Other);

    // /Rect (required)
    let rect = parse_rect(dict, store)?;

    // /Contents (optional)
    let contents = dict.get(&Name::contents()).and_then(|o| {
        store
            .deep_resolve(o)
            .ok()
            .and_then(|r| r.as_string().map(|s| s.to_string_lossy()))
    });

    // /F (optional flags)
    let flags = dict
        .get(&Name::f())
        .and_then(|o| store.deep_resolve(o).ok().and_then(|r| r.as_i64()))
        .map(|v| AnnotationFlags::from_bits(v as u32))
        .unwrap_or_default();

    // /NM (optional unique name)
    let name = dict.get(&Name::nm()).and_then(|o| {
        store
            .deep_resolve(o)
            .ok()
            .and_then(|r| r.as_string().map(|s| s.to_string_lossy()))
    });

    // /AP (optional appearance)
    let appearance = dict
        .get(&Name::ap())
        .and_then(|o| extract_appearance(o, store).ok());

    // /C (optional color)
    let color = dict
        .get(&Name::c())
        .and_then(|o| store.deep_resolve(o).ok())
        .and_then(parse_color_array);

    // /Border or /BS (optional border)
    let border = parse_border(dict, store);

    // /A (optional action)
    let action = dict
        .get(&Name::a())
        .and_then(|o| parse_action(o, store).ok());

    // /Dest (optional destination)
    let destination = dict
        .get(&Name::dest())
        .and_then(|o| parse_destination(o, store).ok());

    // Subtype-specific fields
    let subtype_data = parse_subtype_data(dict, store, subtype);

    // /MK — widget appearance characteristics
    let mk = parse_mk_dict(dict, store);

    // /FS — file specification for FileAttachment annotations
    let file_spec = if subtype == AnnotationType::FileAttachment {
        dict.get(&Name::fs())
            .and_then(|o| parse_file_spec(o, store))
    } else {
        None
    };

    // /Parent — for popup annotations pointing to their parent
    let parent_ref = if subtype == AnnotationType::Popup {
        dict.get(&Name::parent()).and_then(|o| o.as_reference())
    } else {
        None
    };

    // /Open — open state for Text and Popup annotations
    let open = dict.get(&Name::open()).and_then(|o| o.as_bool());

    // /AP decoded stream bytes — extract Normal, Rollover, Down streams
    let (ap_n_bytes, ap_r_bytes, ap_d_bytes) = extract_ap_stream_bytes(dict, store, object_id);

    // /IRT — "In Reply To" indirect reference to another annotation
    let irt_ref = dict.get(&Name::irt()).and_then(|o| o.as_reference());

    // /T — partial field name (form field name or annotation title)
    let field_name = dict.get(&Name::t()).and_then(|o| {
        store
            .deep_resolve(o)
            .ok()
            .and_then(|r| r.as_string().map(|s| s.to_string_lossy()))
    });

    // /TU — alternate (user-visible) field name
    let alternate_name = dict.get(&Name::tu()).and_then(|o| {
        store
            .deep_resolve(o)
            .ok()
            .and_then(|r| r.as_string().map(|s| s.to_string_lossy()))
    });

    // /V — current field value (string or name)
    let field_value = dict.get(&Name::v()).and_then(|o| {
        store.deep_resolve(o).ok().and_then(|r| {
            if let Some(s) = r.as_string() {
                Some(s.to_string_lossy())
            } else {
                r.as_name().map(|n| n.as_str().into_owned())
            }
        })
    });

    // /Ff — form field flags (widget annotations only, but parse for all)
    let form_field_flags = dict
        .get(&Name::ff())
        .and_then(|o| store.deep_resolve(o).ok().and_then(|r| r.as_i64()))
        .map(|v| FormFieldFlags::from_bits(v as u32));

    // /AA — additional actions (widget annotations only)
    let additional_actions = if subtype == AnnotationType::Widget {
        dict.get(&Name::aa())
            .and_then(|o| parse_additional_actions(o, store).ok())
    } else {
        None
    };

    // /FT — form field type (widget annotations; may also be on parent dict)
    let form_field_type = dict.get(&Name::ft()).and_then(|o| {
        store.deep_resolve(o).ok().and_then(|r| {
            r.as_name().map(|n| match n.as_str().as_ref() {
                "Tx" => FormFieldType::Text,
                "Btn" => FormFieldType::Button,
                "Ch" => FormFieldType::Choice,
                "Sig" => FormFieldType::Signature,
                _ => FormFieldType::Text,
            })
        })
    });

    // /Opt — choice-field options (widget annotations with /FT Ch)
    let options = if subtype == AnnotationType::Widget {
        let opts = parse_choice_options(dict, store);
        if opts.is_empty() { None } else { Some(opts) }
    } else {
        None
    };

    Ok(Annotation {
        subtype,
        rect,
        contents,
        flags,
        name,
        appearance,
        color,
        border,
        action,
        destination,
        subtype_data,
        mk,
        file_spec,
        parent_ref,
        object_id,
        open,
        ap_n_bytes,
        ap_r_bytes,
        ap_d_bytes,
        irt_ref,
        field_name,
        alternate_name,
        field_value,
        form_field_flags,
        additional_actions,
        form_field_type,
        options,
    })
}

impl Annotation {
    /// Set the annotation rectangle.
    ///
    /// Updates the in-memory rectangle. To persist the change to a PDF file,
    /// use `EditDocument::update_annotation` in rpdfium-edit.
    pub fn set_rect(&mut self, rect: [f32; 4]) -> DocResult<()> {
        self.rect = rect;
        Ok(())
    }

    /// ADR-019 alias for [`Self::set_rect()`].
    ///
    /// Corresponds to `FPDFAnnot_SetRect()`.
    #[inline]
    pub fn annot_set_rect(&mut self, rect: [f32; 4]) -> DocResult<()> {
        self.set_rect(rect)
    }

    /// Set the open/closed state for Text (sticky-note) and Popup annotations.
    ///
    /// Updates the in-memory open state. To persist the change to a PDF file,
    /// use `EditDocument::update_annotation` in rpdfium-edit.
    pub fn set_open_state(&mut self, open: bool) -> DocResult<()> {
        self.open = Some(open);
        Ok(())
    }

    /// Returns the quad points for markup annotations (Highlight, Underline, Squiggly,
    /// StrikeOut, Link, Polygon, PolyLine).
    ///
    /// Each group of 8 values defines a quadrilateral: `[x1,y1, x2,y2, x3,y3, x4,y4]`.
    ///
    /// Corresponds to upstream `CPDF_Annot::GetQuadPoints()`.
    pub fn quad_points(&self) -> Option<&[f32]> {
        self.subtype_data.quad_points.as_deref()
    }

    /// ADR-019 alias for [`quad_points()`](Self::quad_points).
    ///
    /// Corresponds to upstream `CPDF_Annot::GetQuadPoints()`.
    #[inline]
    pub fn annot_get_quad_points(&self) -> Option<&[f32]> {
        self.quad_points()
    }

    /// Deprecated: use [`annot_get_quad_points()`](Self::annot_get_quad_points) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_quad_points() instead")]
    #[inline]
    pub fn get_quad_points(&self) -> Option<&[f32]> {
        self.quad_points()
    }

    // -----------------------------------------------------------------------
    // ADR-019 getter API — primary name + #[inline] alias get_*
    // Corresponds to FPDFAnnot_* read functions in fpdf_annot.h
    // -----------------------------------------------------------------------

    /// Returns the annotation subtype.
    ///
    /// Corresponds to `FPDFAnnot_GetSubtype()`.
    pub fn subtype(&self) -> AnnotationType {
        self.subtype
    }

    /// ADR-019 alias for [`Self::subtype()`].
    ///
    /// Corresponds to `FPDFAnnot_GetSubtype()`.
    #[inline]
    pub fn annot_get_subtype(&self) -> AnnotationType {
        self.subtype()
    }

    /// Deprecated: use [`annot_get_subtype()`](Self::annot_get_subtype) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_subtype() instead")]
    #[inline]
    pub fn get_subtype(&self) -> AnnotationType {
        self.subtype()
    }

    /// Returns the annotation rectangle `[x1, y1, x2, y2]`.
    ///
    /// Corresponds to `FPDFAnnot_GetRect()`.
    pub fn rect(&self) -> [f32; 4] {
        self.rect
    }

    /// ADR-019 alias for [`Self::rect()`].
    ///
    /// Corresponds to `FPDFAnnot_GetRect()`.
    #[inline]
    pub fn annot_get_rect(&self) -> [f32; 4] {
        self.rect()
    }

    /// Deprecated: use [`annot_get_rect()`](Self::annot_get_rect) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_rect() instead")]
    #[inline]
    pub fn get_rect(&self) -> [f32; 4] {
        self.rect()
    }

    /// Returns the annotation flags.
    ///
    /// Corresponds to `FPDFAnnot_GetFlags()`.
    pub fn flags(&self) -> AnnotationFlags {
        self.flags
    }

    /// ADR-019 alias for [`Self::flags()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFlags()`.
    #[inline]
    pub fn annot_get_flags(&self) -> AnnotationFlags {
        self.flags()
    }

    /// Deprecated: use [`annot_get_flags()`](Self::annot_get_flags) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_flags() instead")]
    #[inline]
    pub fn get_flags(&self) -> AnnotationFlags {
        self.flags()
    }

    /// Returns `true` if this annotation subtype supports attachment (quad) points.
    ///
    /// Attachment points are supported by Highlight, Underline, Squiggly, StrikeOut,
    /// and Link annotations.
    ///
    /// Corresponds to `FPDFAnnot_HasAttachmentPoints()`.
    pub fn has_attachment_points(&self) -> bool {
        matches!(
            self.subtype,
            AnnotationType::Highlight
                | AnnotationType::Underline
                | AnnotationType::Squiggly
                | AnnotationType::StrikeOut
                | AnnotationType::Link
        )
    }

    /// ADR-019 alias for [`Self::has_attachment_points()`].
    ///
    /// Corresponds to `FPDFAnnot_HasAttachmentPoints()`.
    #[inline]
    pub fn annot_has_attachment_points(&self) -> bool {
        self.has_attachment_points()
    }

    /// Returns the number of attachment point groups (quadrilaterals).
    ///
    /// Each group is 8 floats `[x1,y1, x2,y2, x3,y3, x4,y4]`.
    ///
    /// Corresponds to `FPDFAnnot_CountAttachmentPoints()`.
    pub fn attachment_point_count(&self) -> usize {
        self.subtype_data
            .quad_points
            .as_ref()
            .map_or(0, |v| v.len() / 8)
    }

    /// ADR-019 alias for [`Self::attachment_point_count()`].
    ///
    /// Corresponds to `FPDFAnnot_CountAttachmentPoints()`.
    #[inline]
    pub fn annot_count_attachment_points(&self) -> usize {
        self.attachment_point_count()
    }

    /// Deprecated: use [`annot_count_attachment_points()`](Self::annot_count_attachment_points) instead.
    #[deprecated(since = "0.1.0", note = "use annot_count_attachment_points() instead")]
    #[inline]
    pub fn count_attachment_points(&self) -> usize {
        self.attachment_point_count()
    }

    /// Returns the `index`-th attachment point group as 8 floats,
    /// or `None` if the index is out of bounds.
    ///
    /// Corresponds to `FPDFAnnot_GetAttachmentPoints()`.
    pub fn attachment_points(&self, index: usize) -> Option<[f32; 8]> {
        let flat = self.subtype_data.quad_points.as_ref()?;
        let start = index * 8;
        if start + 8 > flat.len() {
            return None;
        }
        let s = &flat[start..start + 8];
        Some([s[0], s[1], s[2], s[3], s[4], s[5], s[6], s[7]])
    }

    /// ADR-019 alias for [`Self::attachment_points()`].
    ///
    /// Corresponds to `FPDFAnnot_GetAttachmentPoints()`.
    #[inline]
    pub fn annot_get_attachment_points(&self, index: usize) -> Option<[f32; 8]> {
        self.attachment_points(index)
    }

    /// Deprecated: use [`annot_get_attachment_points()`](Self::annot_get_attachment_points) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_attachment_points() instead")]
    #[inline]
    pub fn get_attachment_points(&self, index: usize) -> Option<[f32; 8]> {
        self.attachment_points(index)
    }

    /// Returns the vertex array for Polygon and PolyLine annotations as a flat
    /// `[x, y, x, y, …]` slice, or `None` if absent.
    ///
    /// Corresponds to `FPDFAnnot_GetVertices()`.
    pub fn vertices(&self) -> Option<&[f32]> {
        self.subtype_data.vertices.as_deref()
    }

    /// ADR-019 alias for [`Self::vertices()`].
    ///
    /// Corresponds to `FPDFAnnot_GetVertices()`.
    #[inline]
    pub fn annot_get_vertices(&self) -> Option<&[f32]> {
        self.vertices()
    }

    /// Deprecated: use [`annot_get_vertices()`](Self::annot_get_vertices) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_vertices() instead")]
    #[inline]
    pub fn get_vertices(&self) -> Option<&[f32]> {
        self.vertices()
    }

    /// Returns the number of ink strokes for Ink annotations.
    ///
    /// Corresponds to `FPDFAnnot_GetInkListCount()`.
    pub fn ink_list_count(&self) -> usize {
        self.subtype_data.ink_list.as_ref().map_or(0, |v| v.len())
    }

    /// ADR-019 alias for [`Self::ink_list_count()`].
    ///
    /// Corresponds to `FPDFAnnot_GetInkListCount()`.
    #[inline]
    pub fn annot_get_ink_list_count(&self) -> usize {
        self.ink_list_count()
    }

    /// Deprecated: use [`annot_get_ink_list_count()`](Self::annot_get_ink_list_count) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_ink_list_count() instead")]
    #[inline]
    pub fn get_ink_list_count(&self) -> usize {
        self.ink_list_count()
    }

    /// Returns the `index`-th ink stroke as a flat `[x, y, x, y, …]` slice, or `None`.
    ///
    /// Corresponds to `FPDFAnnot_GetInkListPath()`.
    pub fn ink_list_path(&self, index: usize) -> Option<&[f32]> {
        self.subtype_data
            .ink_list
            .as_ref()?
            .get(index)
            .map(|v| v.as_slice())
    }

    /// ADR-019 alias for [`Self::ink_list_path()`].
    ///
    /// Corresponds to `FPDFAnnot_GetInkListPath()`.
    #[inline]
    pub fn annot_get_ink_list_path(&self, index: usize) -> Option<&[f32]> {
        self.ink_list_path(index)
    }

    /// Deprecated: use [`annot_get_ink_list_path()`](Self::annot_get_ink_list_path) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_ink_list_path() instead")]
    #[inline]
    pub fn get_ink_list_path(&self, index: usize) -> Option<&[f32]> {
        self.ink_list_path(index)
    }

    /// Returns the line endpoints for a Line annotation as two `[x, y]` pairs:
    /// `([x1, y1], [x2, y2])`, or `None` if absent.
    ///
    /// Corresponds to `FPDFAnnot_GetLine()`.
    pub fn line_endpoints(&self) -> Option<([f32; 2], [f32; 2])> {
        let pts = self.subtype_data.line_points?;
        Some(([pts[0], pts[1]], [pts[2], pts[3]]))
    }

    /// ADR-019 alias for [`Self::line_endpoints()`].
    ///
    /// Corresponds to `FPDFAnnot_GetLine()`.
    #[inline]
    pub fn annot_get_line(&self) -> Option<([f32; 2], [f32; 2])> {
        self.line_endpoints()
    }

    /// Deprecated: use [`annot_get_line()`](Self::annot_get_line) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_line() instead")]
    #[inline]
    pub fn get_line(&self) -> Option<([f32; 2], [f32; 2])> {
        self.line_endpoints()
    }

    /// Deprecated: use [`annot_get_line()`](Self::annot_get_line) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_line() instead")]
    #[inline]
    pub fn get_line_endpoints(&self) -> Option<([f32; 2], [f32; 2])> {
        self.line_endpoints()
    }

    /// Returns the border specification as `(horizontal_radius, vertical_radius, width)`.
    ///
    /// Because `AnnotationBorder` only stores `width` (the `/Border` h/v radii are
    /// not retained), the returned tuple is always `(0.0, 0.0, width)`.
    ///
    /// Corresponds to `FPDFAnnot_GetBorder()`.
    pub fn border_style(&self) -> Option<(f32, f32, f32)> {
        self.border.as_ref().map(|b| (0.0_f32, 0.0_f32, b.width))
    }

    /// ADR-019 alias for [`Self::border_style()`].
    ///
    /// Corresponds to `FPDFAnnot_GetBorder()`.
    #[inline]
    pub fn annot_get_border(&self) -> Option<(f32, f32, f32)> {
        self.border_style()
    }

    /// Deprecated: use [`annot_get_border()`](Self::annot_get_border) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_border() instead")]
    #[inline]
    pub fn get_border(&self) -> Option<(f32, f32, f32)> {
        self.border_style()
    }

    /// Deprecated: use [`annot_get_border()`](Self::annot_get_border) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_border() instead")]
    #[inline]
    pub fn get_border_style(&self) -> Option<(f32, f32, f32)> {
        self.border_style()
    }

    /// Returns the annotation color as `(red, green, blue, alpha)` in 0–255 range.
    ///
    /// Converts from the PDF `/C` array (0.0–1.0 floats):
    /// - 1 component → gray (R=G=B=gray, A=255)
    /// - 3 components → RGB, A=255
    /// - 4 components → CMYK converted to RGB (approximate), A=255
    /// - other → `None`
    ///
    /// Corresponds to `FPDFAnnot_GetColor()`.
    pub fn color_rgba(&self) -> Option<(u8, u8, u8, u8)> {
        let c = self.color.as_ref()?;
        let to_u8 = |f: f32| (f.clamp(0.0, 1.0) * 255.0).round() as u8;
        match c.len() {
            1 => {
                let gray = to_u8(c[0]);
                Some((gray, gray, gray, 255))
            }
            3 => Some((to_u8(c[0]), to_u8(c[1]), to_u8(c[2]), 255)),
            4 => {
                // Approximate CMYK → RGB: R = (1−C)*(1−K), etc.
                let k = c[3].clamp(0.0, 1.0);
                let r = to_u8((1.0 - c[0].clamp(0.0, 1.0)) * (1.0 - k));
                let g = to_u8((1.0 - c[1].clamp(0.0, 1.0)) * (1.0 - k));
                let b = to_u8((1.0 - c[2].clamp(0.0, 1.0)) * (1.0 - k));
                Some((r, g, b, 255))
            }
            _ => None,
        }
    }

    /// ADR-019 alias for [`Self::color_rgba()`].
    ///
    /// Corresponds to `FPDFAnnot_GetColor()`.
    #[inline]
    pub fn annot_get_color(&self) -> Option<(u8, u8, u8, u8)> {
        self.color_rgba()
    }

    /// Deprecated: use [`annot_get_color()`](Self::annot_get_color) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_color() instead")]
    #[inline]
    pub fn get_color(&self) -> Option<(u8, u8, u8, u8)> {
        self.color_rgba()
    }

    /// Deprecated: use [`annot_get_color()`](Self::annot_get_color) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_color() instead")]
    #[inline]
    pub fn get_color_rgba(&self) -> Option<(u8, u8, u8, u8)> {
        self.color_rgba()
    }

    /// Returns the string value for a well-known annotation key.
    ///
    /// Supported keys: `"Contents"`, `"NM"` (annotation name/label),
    /// `"T"` (partial field name), `"TU"` (alternate field name),
    /// `"V"` (current field value).
    ///
    /// Corresponds to `FPDFAnnot_GetStringValue()`.
    pub fn string_value(&self, key: &str) -> Option<&str> {
        match key {
            "Contents" => self.contents.as_deref(),
            "NM" => self.name.as_deref(),
            "T" => self.field_name.as_deref(),
            "TU" => self.alternate_name.as_deref(),
            "V" => self.field_value.as_deref(),
            _ => None,
        }
    }

    /// ADR-019 alias for [`Self::string_value()`].
    ///
    /// Corresponds to `FPDFAnnot_GetStringValue()`.
    #[inline]
    pub fn annot_get_string_value(&self, key: &str) -> Option<&str> {
        self.string_value(key)
    }

    /// Deprecated: use [`annot_get_string_value()`](Self::annot_get_string_value) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_string_value() instead")]
    #[inline]
    pub fn get_string_value(&self, key: &str) -> Option<&str> {
        self.string_value(key)
    }

    /// Returns the partial field name (`/T` key).
    ///
    /// For widget annotations this is the form field name; for other annotation
    /// types it serves as the annotation title / author label.
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldName()`.
    pub fn field_name(&self) -> Option<&str> {
        self.field_name.as_deref()
    }

    /// ADR-019 alias for [`Self::field_name()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldName()`.
    #[inline]
    pub fn annot_get_form_field_name(&self) -> Option<&str> {
        self.field_name()
    }

    /// Deprecated: use [`annot_get_form_field_name()`](Self::annot_get_form_field_name) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_form_field_name() instead")]
    #[inline]
    pub fn get_form_field_name(&self) -> Option<&str> {
        self.field_name()
    }

    /// Deprecated: use [`annot_get_form_field_name()`](Self::annot_get_form_field_name) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_form_field_name() instead")]
    #[inline]
    pub fn get_field_name(&self) -> Option<&str> {
        self.field_name()
    }

    /// Returns the alternate (user-visible) field name (`/TU` key).
    ///
    /// Only meaningful for widget annotations.
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldAlternateName()`.
    pub fn alternate_field_name(&self) -> Option<&str> {
        self.alternate_name.as_deref()
    }

    /// ADR-019 alias for [`Self::alternate_field_name()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldAlternateName()`.
    #[inline]
    pub fn annot_get_form_field_alternate_name(&self) -> Option<&str> {
        self.alternate_field_name()
    }

    /// Deprecated: use [`annot_get_form_field_alternate_name()`](Self::annot_get_form_field_alternate_name) instead.
    #[deprecated(
        since = "0.1.0",
        note = "use annot_get_form_field_alternate_name() instead"
    )]
    #[inline]
    pub fn get_form_field_alternate_name(&self) -> Option<&str> {
        self.alternate_field_name()
    }

    /// Deprecated: use [`annot_get_form_field_alternate_name()`](Self::annot_get_form_field_alternate_name) instead.
    #[deprecated(
        since = "0.1.0",
        note = "use annot_get_form_field_alternate_name() instead"
    )]
    #[inline]
    pub fn get_alternate_field_name(&self) -> Option<&str> {
        self.alternate_field_name()
    }

    /// Returns the current field value as a string (`/V` key).
    ///
    /// For text fields this is the text value; for choice fields it is the
    /// selected option string; for check-box / radio-button fields it is the
    /// appearance state name.
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldValue()`.
    pub fn field_value_str(&self) -> Option<&str> {
        self.field_value.as_deref()
    }

    /// ADR-019 alias for [`Self::field_value_str()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldValue()`.
    #[inline]
    pub fn annot_get_form_field_value(&self) -> Option<&str> {
        self.field_value_str()
    }

    /// Deprecated: use [`annot_get_form_field_value()`](Self::annot_get_form_field_value) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_form_field_value() instead")]
    #[inline]
    pub fn get_form_field_value(&self) -> Option<&str> {
        self.field_value_str()
    }

    /// Deprecated: use [`annot_get_form_field_value()`](Self::annot_get_form_field_value) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_form_field_value() instead")]
    #[inline]
    pub fn get_field_value(&self) -> Option<&str> {
        self.field_value_str()
    }

    /// Returns `true` if this annotation has a non-`None` value for the given key.
    ///
    /// Corresponds to `FPDFAnnot_HasKey()`.
    pub fn has_key(&self, key: &str) -> bool {
        self.string_value(key).is_some()
    }

    /// ADR-019 alias for [`Self::has_key()`].
    ///
    /// Corresponds to `FPDFAnnot_HasKey()`.
    #[inline]
    pub fn annot_has_key(&self, key: &str) -> bool {
        self.has_key(key)
    }

    /// Returns the numeric value for a well-known annotation key, or `None`.
    ///
    /// Currently supports: `"F"` (flags as u32), `"Border-Width"` (border width in points).
    ///
    /// Corresponds to `FPDFAnnot_GetNumberValue()`.
    pub fn number_value(&self, key: &str) -> Option<f32> {
        match key {
            "F" => Some(self.flags.bits() as f32),
            "Border-Width" => self.border.as_ref().map(|b| b.width),
            _ => None,
        }
    }

    /// ADR-019 alias for [`Self::number_value()`].
    ///
    /// Corresponds to `FPDFAnnot_GetNumberValue()`.
    #[inline]
    pub fn annot_get_number_value(&self, key: &str) -> Option<f32> {
        self.number_value(key)
    }

    /// Deprecated: use [`annot_get_number_value()`](Self::annot_get_number_value) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_number_value() instead")]
    #[inline]
    pub fn get_number_value(&self, key: &str) -> Option<f32> {
        self.number_value(key)
    }

    // -----------------------------------------------------------------------
    // Gap fixes: value_type, appearance_stream_bytes, linked_annot_ref
    // -----------------------------------------------------------------------

    /// Returns the PDF object type of the value stored under `key` in the
    /// annotation's logical field set.
    ///
    /// Keys inspected: `"Contents"`, `"NM"` (String), `"F"` (Number),
    /// `"Subtype"` (Name), `"AP"` (Dictionary), `"Rect"` (Array),
    /// `"C"` (Array), `"Vertices"` (Array), `"QuadPoints"` (Array),
    /// `"InkList"` (Array), `"IRT"` (Reference).
    ///
    /// Returns [`PdfValueType::Unknown`] if the key is not recognised or the
    /// corresponding field is `None`.
    ///
    /// Corresponds to `FPDFAnnot_GetValueType()`.
    pub fn value_type(&self, key: &str) -> PdfValueType {
        match key {
            "Contents" => {
                if self.contents.is_some() {
                    PdfValueType::String
                } else {
                    PdfValueType::Unknown
                }
            }
            "NM" => {
                if self.name.is_some() {
                    PdfValueType::String
                } else {
                    PdfValueType::Unknown
                }
            }
            "F" => PdfValueType::Number,
            "Subtype" => PdfValueType::Name,
            "AP" => {
                if self.appearance.is_some() {
                    PdfValueType::Dictionary
                } else {
                    PdfValueType::Unknown
                }
            }
            "Rect" => PdfValueType::Array,
            "C" => {
                if self.color.is_some() {
                    PdfValueType::Array
                } else {
                    PdfValueType::Unknown
                }
            }
            "Vertices" => {
                if self.subtype_data.vertices.is_some() {
                    PdfValueType::Array
                } else {
                    PdfValueType::Unknown
                }
            }
            "QuadPoints" => {
                if self.subtype_data.quad_points.is_some() {
                    PdfValueType::Array
                } else {
                    PdfValueType::Unknown
                }
            }
            "InkList" => {
                if self.subtype_data.ink_list.is_some() {
                    PdfValueType::Array
                } else {
                    PdfValueType::Unknown
                }
            }
            "IRT" => {
                if self.irt_ref.is_some() {
                    PdfValueType::Reference
                } else {
                    PdfValueType::Unknown
                }
            }
            _ => PdfValueType::Unknown,
        }
    }

    /// ADR-019 alias for [`Self::value_type()`].
    ///
    /// Corresponds to `FPDFAnnot_GetValueType()`.
    #[inline]
    pub fn annot_get_value_type(&self, key: &str) -> PdfValueType {
        self.value_type(key)
    }

    /// Deprecated: use [`annot_get_value_type()`](Self::annot_get_value_type) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_value_type() instead")]
    #[inline]
    pub fn get_value_type(&self, key: &str) -> PdfValueType {
        self.value_type(key)
    }

    /// Returns the decoded content bytes of the annotation's appearance stream
    /// for the given `mode`, or `None` if no appearance stream is available for
    /// that mode.
    ///
    /// The bytes are the decoded (post-filter) PDF content stream data from
    /// the `/AP /N` (Normal), `/AP /R` (Rollover), or `/AP /D` (Down)
    /// sub-entry.
    ///
    /// Corresponds to `FPDFAnnot_GetAP()`.
    pub fn appearance_stream_bytes(&self, mode: AppearanceMode) -> Option<&[u8]> {
        match mode {
            AppearanceMode::Normal => self.ap_n_bytes.as_deref(),
            AppearanceMode::Rollover => self.ap_r_bytes.as_deref(),
            AppearanceMode::Down => self.ap_d_bytes.as_deref(),
        }
    }

    /// ADR-019 alias for [`Self::appearance_stream_bytes()`].
    ///
    /// Corresponds to `FPDFAnnot_GetAP()`.
    #[inline]
    pub fn annot_get_ap(&self, mode: AppearanceMode) -> Option<&[u8]> {
        self.appearance_stream_bytes(mode)
    }

    /// Deprecated: use [`annot_get_ap()`](Self::annot_get_ap) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_ap() instead")]
    #[inline]
    pub fn get_ap(&self, mode: AppearanceMode) -> Option<&[u8]> {
        self.appearance_stream_bytes(mode)
    }

    /// Deprecated: use [`annot_get_ap()`](Self::annot_get_ap) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_ap() instead")]
    #[inline]
    pub fn get_appearance_stream_bytes(&self, mode: AppearanceMode) -> Option<&[u8]> {
        self.appearance_stream_bytes(mode)
    }

    /// Set the appearance stream for the given mode.
    ///
    /// # Not Supported
    ///
    /// AP stream mutation is not yet supported (requires Form XObject creation).
    /// This stub is provided for API completeness per ADR-017.
    ///
    /// Corresponds to `FPDFAnnot_SetAP()`.
    pub fn set_appearance_stream_bytes(
        &mut self,
        _mode: AppearanceMode,
        _data: &[u8],
    ) -> DocResult<()> {
        Err(DocError::NotSupported(
            "set_appearance_stream_bytes: AP stream mutation not yet supported".into(),
        ))
    }

    /// ADR-019 alias for [`Self::set_appearance_stream_bytes()`].
    ///
    /// Corresponds to `FPDFAnnot_SetAP()`.
    #[inline]
    pub fn annot_set_ap(&mut self, mode: AppearanceMode, data: &[u8]) -> DocResult<()> {
        self.set_appearance_stream_bytes(mode, data)
    }

    /// Deprecated: use [`annot_set_ap()`](Self::annot_set_ap) instead.
    #[deprecated(since = "0.1.0", note = "use annot_set_ap() instead")]
    #[inline]
    pub fn set_ap(&mut self, mode: AppearanceMode, data: &[u8]) -> DocResult<()> {
        self.set_appearance_stream_bytes(mode, data)
    }

    /// Returns the `ObjectId` of the annotation referenced by `/IRT`
    /// ("In Reply To"), if any.
    ///
    /// The `/IRT` entry is present on annotations that are replies to another
    /// annotation (e.g., a reply thread in a comment workflow). The returned
    /// `ObjectId` identifies the parent annotation object.
    ///
    /// Corresponds to `FPDFAnnot_GetLinkedAnnot()`.
    pub fn linked_annot_ref(&self) -> Option<ObjectId> {
        self.irt_ref
    }

    /// ADR-019 alias for [`Self::linked_annot_ref()`].
    ///
    /// Corresponds to `FPDFAnnot_GetLinkedAnnot()`.
    #[inline]
    pub fn annot_get_linked_annot(&self) -> Option<ObjectId> {
        self.linked_annot_ref()
    }

    /// Deprecated: use [`annot_get_linked_annot()`](Self::annot_get_linked_annot) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_linked_annot() instead")]
    #[inline]
    pub fn get_linked_annot(&self) -> Option<ObjectId> {
        self.linked_annot_ref()
    }

    // -----------------------------------------------------------------------
    // Gap fixes: form_field_flags, get_link, file_attachment
    // -----------------------------------------------------------------------

    /// Returns the form field flags (`/Ff`) for widget annotations, or `None`
    /// if the annotation has no `/Ff` entry.
    ///
    /// The flags encode properties such as read-only, required, multiline,
    /// password, etc. (ISO 32000-2 Table 226).
    ///
    /// Unlike the upstream `FPDFAnnot_GetFormFieldFlags()`, this method does
    /// not require a `FORMHANDLE` parameter because rpdfium embeds the flags
    /// directly in the parsed `Annotation` struct.
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldFlags()`.
    pub fn form_field_flags(&self) -> Option<FormFieldFlags> {
        self.form_field_flags
    }

    /// ADR-019 alias for [`Self::form_field_flags()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldFlags()`.
    #[inline]
    pub fn annot_get_form_field_flags(&self) -> Option<FormFieldFlags> {
        self.form_field_flags()
    }

    /// Deprecated: use [`annot_get_form_field_flags()`](Self::annot_get_form_field_flags) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_form_field_flags() instead")]
    #[inline]
    pub fn get_form_field_flags(&self) -> Option<FormFieldFlags> {
        self.form_field_flags()
    }

    // -----------------------------------------------------------------------
    // font_size() / annot_get_font_size()
    // -----------------------------------------------------------------------

    /// Returns the font size from the default appearance (`/DA`) string.
    ///
    /// Parses the `Tf` operator in the `/DA` string. Returns `None` if no `/DA`
    /// is present or the font size is 0 (variable — determined by field size).
    ///
    /// Valid for FreeText and Widget annotations.
    ///
    /// Corresponds to `FPDFAnnot_GetFontSize()`.
    pub fn font_size(&self) -> Option<f32> {
        let da = self.subtype_data.default_appearance.as_deref()?;
        let parsed = parse_default_appearance(da);
        let size = parsed.font_size as f32;
        if size == 0.0 { None } else { Some(size) }
    }

    /// ADR-019 alias for [`Self::font_size()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFontSize()`.
    #[inline]
    pub fn annot_get_font_size(&self) -> Option<f32> {
        self.font_size()
    }

    // -----------------------------------------------------------------------
    // font_color() / annot_get_font_color() / set_font_color() / annot_set_font_color()
    // -----------------------------------------------------------------------

    /// Returns the font color from the default appearance (`/DA`) string as `(R, G, B)`.
    ///
    /// Parses the color operator (`g`, `rg`, or `k`) in the `/DA` string and
    /// converts to 8-bit RGB values (0–255). Returns `None` if no color is
    /// specified in the DA string.
    ///
    /// Valid for FreeText and Widget annotations.
    ///
    /// Corresponds to `FPDFAnnot_GetFontColor()`.
    pub fn font_color(&self) -> Option<(u8, u8, u8)> {
        let da = self.subtype_data.default_appearance.as_deref()?;
        let parsed = parse_default_appearance(da);
        let color = parsed.color?;
        match color.len() {
            // Grayscale: g g g
            1 => {
                let g = (color[0].clamp(0.0, 1.0) * 255.0).round() as u8;
                Some((g, g, g))
            }
            // RGB
            3 => {
                let r = (color[0].clamp(0.0, 1.0) * 255.0).round() as u8;
                let g = (color[1].clamp(0.0, 1.0) * 255.0).round() as u8;
                let b = (color[2].clamp(0.0, 1.0) * 255.0).round() as u8;
                Some((r, g, b))
            }
            // CMYK: approximate conversion to RGB
            4 => {
                let c = color[0].clamp(0.0, 1.0);
                let m = color[1].clamp(0.0, 1.0);
                let y = color[2].clamp(0.0, 1.0);
                let k = color[3].clamp(0.0, 1.0);
                let r = ((1.0 - c) * (1.0 - k) * 255.0).round() as u8;
                let g = ((1.0 - m) * (1.0 - k) * 255.0).round() as u8;
                let b = ((1.0 - y) * (1.0 - k) * 255.0).round() as u8;
                Some((r, g, b))
            }
            _ => None,
        }
    }

    /// ADR-019 alias for [`Self::font_color()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFontColor()`.
    #[inline]
    pub fn annot_get_font_color(&self) -> Option<(u8, u8, u8)> {
        self.font_color()
    }

    /// Sets the font color in the default appearance (`/DA`) string.
    ///
    /// Updates the in-memory default appearance string by replacing or appending
    /// an `rg` color operator. To persist, use the edit layer to re-serialize
    /// the annotation.
    ///
    /// Valid for FreeText and Widget annotations. Returns `Err` if the
    /// annotation subtype does not support a `/DA` string.
    ///
    /// Corresponds to `FPDFAnnot_SetFontColor()`.
    pub fn set_font_color(&mut self, r: u8, g: u8, b: u8) -> DocResult<()> {
        match self.subtype {
            AnnotationType::FreeText | AnnotationType::Widget => {}
            _ => {
                return Err(DocError::NotSupported(
                    "set_font_color: only FreeText and Widget annotations support /DA".into(),
                ));
            }
        }
        let rf = r as f64 / 255.0;
        let gf = g as f64 / 255.0;
        let bf = b as f64 / 255.0;

        let color_token = format!("{rf:.4} {gf:.4} {bf:.4} rg");
        let current = self
            .subtype_data
            .default_appearance
            .get_or_insert_with(String::new);
        // Remove any existing color operator (g, rg, k) and append the new one.
        let stripped = strip_da_color(current);
        *current = format!("{stripped} {color_token}").trim().to_owned();
        Ok(())
    }

    /// ADR-019 alias for [`Self::set_font_color()`].
    ///
    /// Corresponds to `FPDFAnnot_SetFontColor()`.
    #[inline]
    pub fn annot_set_font_color(&mut self, r: u8, g: u8, b: u8) -> DocResult<()> {
        self.set_font_color(r, g, b)
    }

    // -----------------------------------------------------------------------
    // form_additional_action_javascript() / annot_get_form_additional_action_javascript()
    // -----------------------------------------------------------------------

    /// Returns the JavaScript code for a form field additional action event.
    ///
    /// Looks up the `/AA` entry for `event_type` on Widget annotations and
    /// returns the JavaScript code if the action is a `JavaScript` action.
    /// Returns an empty string if no such action exists or the action is not
    /// a JavaScript action (matching upstream `FPDFAnnot_GetFormAdditionalActionJavaScript`
    /// behavior).
    ///
    /// Only meaningful for Widget annotations.
    ///
    /// Corresponds to `FPDFAnnot_GetFormAdditionalActionJavaScript()`.
    pub fn form_additional_action_javascript(&self, event_type: AActionType) -> String {
        self.additional_actions
            .as_ref()
            .and_then(|aa| aa.action(event_type))
            .map(|a| a.javascript())
            .unwrap_or_default()
    }

    /// ADR-019 alias for [`Self::form_additional_action_javascript()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormAdditionalActionJavaScript()`.
    #[inline]
    pub fn annot_get_form_additional_action_javascript(&self, event_type: AActionType) -> String {
        self.form_additional_action_javascript(event_type)
    }

    /// Returns the action and destination stored on this annotation, intended
    /// for use with Link annotations.
    ///
    /// Returns `(action, destination)` where each component may be `None` if
    /// not present in the annotation dictionary.
    ///
    /// In the upstream PDFium API, `FPDFAnnot_GetLink()` returns an opaque
    /// `FPDF_LINK` handle wrapping the same data. rpdfium instead returns a
    /// tuple of references.
    ///
    /// Corresponds to `FPDFAnnot_GetLink()`.
    pub fn link_ref(&self) -> (Option<&Action>, Option<&Destination>) {
        (self.action.as_ref(), self.destination.as_ref())
    }

    /// ADR-019 alias for [`Self::link_ref()`].
    ///
    /// Corresponds to `FPDFAnnot_GetLink()`.
    #[inline]
    pub fn annot_get_link(&self) -> (Option<&Action>, Option<&Destination>) {
        self.link_ref()
    }

    /// Deprecated: use [`annot_get_link()`](Self::annot_get_link) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_link() instead")]
    #[inline]
    pub fn get_link(&self) -> (Option<&Action>, Option<&Destination>) {
        self.link_ref()
    }

    /// Returns the file specification attached to a FileAttachment annotation
    /// (the `/FS` entry), or `None` if not present.
    ///
    /// Corresponds to `FPDFAnnot_GetFileAttachment()`.
    pub fn file_attachment(&self) -> Option<&FileSpec> {
        self.file_spec.as_ref()
    }

    /// ADR-019 alias for [`Self::file_attachment()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFileAttachment()`.
    #[inline]
    pub fn annot_get_file_attachment(&self) -> Option<&FileSpec> {
        self.file_attachment()
    }

    /// Deprecated: use [`annot_get_file_attachment()`](Self::annot_get_file_attachment) instead.
    #[deprecated(since = "0.1.0", note = "use annot_get_file_attachment() instead")]
    #[inline]
    pub fn get_file_attachment(&self) -> Option<&FileSpec> {
        self.file_attachment()
    }

    // -----------------------------------------------------------------------
    // G6: form_field_type() — FPDFAnnot_GetFormFieldType
    // -----------------------------------------------------------------------

    /// Returns the form field type (`/FT`) for widget annotations.
    ///
    /// Returns `None` for non-widget annotations or when `/FT` is only
    /// present on a parent field dictionary.
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldType()`.
    pub fn form_field_type(&self) -> Option<FormFieldType> {
        self.form_field_type.clone()
    }

    /// ADR-019 alias for [`Self::form_field_type()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldType()`.
    #[inline]
    pub fn annot_get_form_field_type(&self) -> Option<FormFieldType> {
        self.form_field_type()
    }

    // -----------------------------------------------------------------------
    // G6 stubs: form_control_count / form_control_index / form_field_export_value
    // -----------------------------------------------------------------------

    /// Returns the number of form controls for this annotation in the AcroForm.
    ///
    /// # Not Supported
    ///
    /// Requires document-level AcroForm traversal which is not supported in
    /// the annotation-level API (ADR-002: read-only, no form session).
    ///
    /// Corresponds to `FPDFAnnot_GetFormControlCount()`.
    pub fn form_control_count(&self) -> DocResult<usize> {
        Err(DocError::NotSupported(
            "form_control_count: requires document-level AcroForm traversal (ADR-002)".into(),
        ))
    }

    /// ADR-019 alias for [`Self::form_control_count()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormControlCount()`.
    #[inline]
    pub fn annot_get_form_control_count(&self) -> DocResult<usize> {
        self.form_control_count()
    }

    /// Returns the index of this annotation in its form control list.
    ///
    /// # Not Supported
    ///
    /// Requires document-level AcroForm traversal which is not supported in
    /// the annotation-level API (ADR-002: read-only, no form session).
    ///
    /// Corresponds to `FPDFAnnot_GetFormControlIndex()`.
    pub fn form_control_index(&self) -> DocResult<usize> {
        Err(DocError::NotSupported(
            "form_control_index: requires document-level AcroForm traversal (ADR-002)".into(),
        ))
    }

    /// ADR-019 alias for [`Self::form_control_index()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormControlIndex()`.
    #[inline]
    pub fn annot_get_form_control_index(&self) -> DocResult<usize> {
        self.form_control_index()
    }

    /// Returns the export value for this form control.
    ///
    /// # Not Supported
    ///
    /// Requires document-level AcroForm traversal which is not supported in
    /// the annotation-level API (ADR-002: read-only, no form session).
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldExportValue()`.
    pub fn form_field_export_value(&self) -> DocResult<String> {
        Err(DocError::NotSupported(
            "form_field_export_value: requires document-level AcroForm traversal (ADR-002)".into(),
        ))
    }

    /// ADR-019 alias for [`Self::form_field_export_value()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFormFieldExportValue()`.
    #[inline]
    pub fn annot_get_form_field_export_value(&self) -> DocResult<String> {
        self.form_field_export_value()
    }

    // -----------------------------------------------------------------------
    // G7: is_checked / option_count / option_label / is_option_selected
    // -----------------------------------------------------------------------

    /// Returns `true` if this checkbox or radio-button annotation is checked.
    ///
    /// A check-box is considered checked when its `/V` value is anything
    /// other than `"Off"` or absent.
    ///
    /// Corresponds to `FPDFAnnot_IsChecked()`.
    pub fn is_checked(&self) -> bool {
        match self.field_value.as_deref() {
            None | Some("Off") => false,
            Some(_) => true,
        }
    }

    /// ADR-019 alias for [`Self::is_checked()`].
    ///
    /// Corresponds to `FPDFAnnot_IsChecked()`.
    #[inline]
    pub fn annot_is_checked(&self) -> bool {
        self.is_checked()
    }

    /// Returns the number of options in a choice-field annotation.
    ///
    /// Returns `0` if the annotation has no `/Opt` array (non-choice fields).
    ///
    /// Corresponds to `FPDFAnnot_GetOptionCount()`.
    pub fn option_count(&self) -> usize {
        self.options.as_ref().map_or(0, |v| v.len())
    }

    /// ADR-019 alias for [`Self::option_count()`].
    ///
    /// Corresponds to `FPDFAnnot_GetOptionCount()`.
    #[inline]
    pub fn annot_get_option_count(&self) -> usize {
        self.option_count()
    }

    /// Returns the display label for the option at `index`, or `None` if
    /// the index is out of bounds.
    ///
    /// Corresponds to `FPDFAnnot_GetOptionLabel()`.
    pub fn option_label(&self, index: usize) -> Option<&str> {
        self.options
            .as_ref()?
            .get(index)
            .map(|o| o.display_value.as_str())
    }

    /// ADR-019 alias for [`Self::option_label()`].
    ///
    /// Corresponds to `FPDFAnnot_GetOptionLabel()`.
    #[inline]
    pub fn annot_get_option_label(&self, index: usize) -> Option<&str> {
        self.option_label(index)
    }

    /// Returns `true` if the option at `index` is currently selected.
    ///
    /// For choice fields the selected option is identified by comparing the
    /// option's `export_value` against the annotation's `/V` string.
    ///
    /// Corresponds to `FPDFAnnot_IsOptionSelected()`.
    pub fn is_option_selected(&self, index: usize) -> bool {
        let Some(opts) = self.options.as_ref() else {
            return false;
        };
        let Some(opt) = opts.get(index) else {
            return false;
        };
        match self.field_value.as_deref() {
            Some(v) => v == opt.export_value,
            None => false,
        }
    }

    /// ADR-019 alias for [`Self::is_option_selected()`].
    ///
    /// Corresponds to `FPDFAnnot_IsOptionSelected()`.
    #[inline]
    pub fn annot_is_option_selected(&self, index: usize) -> bool {
        self.is_option_selected(index)
    }

    // -----------------------------------------------------------------------
    // G8 stubs: focusable subtypes — FPDFAnnot_GetFocusableSubtypesCount /
    //           FPDFAnnot_GetFocusableSubtypes / FPDFAnnot_SetFocusableSubtypes
    // -----------------------------------------------------------------------

    /// Returns the count of focusable annotation subtypes configured on the viewer.
    ///
    /// # Not Supported
    ///
    /// Focusable subtype configuration is a viewer/form-session concept that
    /// requires a `FPDF_FORMHANDLE` and is not supported in rpdfium's
    /// document-level read-only API (ADR-002).
    ///
    /// Corresponds to `FPDFAnnot_GetFocusableSubtypesCount()`.
    pub fn focusable_subtype_count(&self) -> DocResult<usize> {
        Err(DocError::NotSupported(
            "focusable_subtype_count: requires FPDF_FORMHANDLE viewer session (ADR-002)".into(),
        ))
    }

    /// ADR-019 alias for [`Self::focusable_subtype_count()`].
    ///
    /// Corresponds to `FPDFAnnot_GetFocusableSubtypesCount()`.
    #[inline]
    pub fn annot_get_focusable_subtypes_count(&self) -> DocResult<usize> {
        self.focusable_subtype_count()
    }

    /// Sets the focusable annotation subtypes on the viewer.
    ///
    /// # Not Supported
    ///
    /// Focusable subtype configuration is a viewer/form-session concept that
    /// requires a `FPDF_FORMHANDLE` and is not supported in rpdfium's
    /// document-level read-only API (ADR-002).
    ///
    /// Corresponds to `FPDFAnnot_SetFocusableSubtypes()`.
    pub fn set_focusable_subtypes(&mut self, _subtypes: &[AnnotationType]) -> DocResult<()> {
        Err(DocError::NotSupported(
            "set_focusable_subtypes: requires FPDF_FORMHANDLE viewer session (ADR-002)".into(),
        ))
    }

    /// ADR-019 alias for [`Self::set_focusable_subtypes()`].
    ///
    /// Corresponds to `FPDFAnnot_SetFocusableSubtypes()`.
    #[inline]
    pub fn annot_set_focusable_subtypes(&mut self, subtypes: &[AnnotationType]) -> DocResult<()> {
        self.set_focusable_subtypes(subtypes)
    }

    // -----------------------------------------------------------------------
    // G9: set_flags / set_form_field_flags
    // -----------------------------------------------------------------------

    /// Sets the annotation flags (`/F`).
    ///
    /// Updates the in-memory flags. To persist, re-serialize the annotation
    /// via the edit layer.
    ///
    /// Corresponds to `FPDFAnnot_SetFlags()`.
    pub fn set_flags(&mut self, flags: AnnotationFlags) -> DocResult<()> {
        self.flags = flags;
        Ok(())
    }

    /// ADR-019 alias for [`Self::set_flags()`].
    ///
    /// Corresponds to `FPDFAnnot_SetFlags()`.
    #[inline]
    pub fn annot_set_flags(&mut self, flags: AnnotationFlags) -> DocResult<()> {
        self.set_flags(flags)
    }

    /// Sets the form field flags (`/Ff`) for widget annotations.
    ///
    /// Updates the in-memory flags. To persist, re-serialize the annotation
    /// via the edit layer.
    ///
    /// Corresponds to `FPDFAnnot_SetFormFieldFlags()` (planned upstream API).
    pub fn set_form_field_flags(&mut self, flags: FormFieldFlags) -> DocResult<()> {
        self.form_field_flags = Some(flags);
        Ok(())
    }

    /// ADR-019 alias for [`Self::set_form_field_flags()`].
    ///
    /// Corresponds to `FPDFAnnot_SetFormFieldFlags()`.
    #[inline]
    pub fn annot_set_form_field_flags(&mut self, flags: FormFieldFlags) -> DocResult<()> {
        self.set_form_field_flags(flags)
    }
}

/// Decode AP stream bytes for Normal, Rollover, and Down modes.
///
/// Reads the `/AP` dictionary, resolves each sub-entry (`/N`, `/R`, `/D`),
/// and decodes the stream data if present. Failures are silently mapped to
/// `None` so that a missing or undecodable stream does not prevent annotation
/// parsing from succeeding.
#[allow(clippy::type_complexity)]
fn extract_ap_stream_bytes<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
    object_id: Option<ObjectId>,
) -> (Option<Vec<u8>>, Option<Vec<u8>>, Option<Vec<u8>>) {
    let ap_entry = match dict.get(&Name::ap()) {
        None => return (None, None, None),
        Some(o) => o,
    };
    let resolved_ap = match store.deep_resolve(ap_entry) {
        Ok(o) => o,
        Err(_) => return (None, None, None),
    };
    let ap_dict = match resolved_ap.as_dict() {
        None => return (None, None, None),
        Some(d) => d,
    };

    let decode_sub = |key: &Name| -> Option<Vec<u8>> {
        let sub = ap_dict.get(key)?;
        // Sub-entry may be an indirect reference to a stream object
        let stream_obj = if let Some(ref_id) = sub.as_reference() {
            match store.resolve(ref_id) {
                Ok(o) => o,
                Err(_) => return None,
            }
        } else {
            // Inline stream or dictionary — resolve in place
            match store.deep_resolve(sub) {
                Ok(o) => o,
                Err(_) => return None,
            }
        };
        // For state dicts, pick the first stream entry
        let actual_stream =
            if stream_obj.as_dict().is_some() && stream_obj.as_stream_dict().is_none() {
                // It's a plain dictionary (state dict), find first reference value
                let state_dict = stream_obj.as_dict()?;
                let mut found = None;
                for val in state_dict.values() {
                    if let Some(ref_id) = val.as_reference() {
                        if let Ok(s) = store.resolve(ref_id) {
                            found = Some(s);
                            break;
                        }
                    }
                }
                found?
            } else {
                stream_obj
            };
        // Decode the stream; use object_id for encryption context if available
        let dummy_id = ObjectId::new(0, 0);
        let oid = object_id.unwrap_or(dummy_id);
        store.decode_stream_for_object(actual_stream, oid).ok()
    };

    let n = decode_sub(&Name::n());
    let r = decode_sub(&Name::r());
    let d = decode_sub(&Name::d());
    (n, r, d)
}

/// Parse the `/Rect` array from an annotation dictionary.
fn parse_rect<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> DocResult<[f32; 4]> {
    let rect_obj = dict
        .get(&Name::rect())
        .ok_or_else(|| DocError::MissingKey("/Rect".into()))?;
    let resolved = store
        .deep_resolve(rect_obj)
        .map_err(|e| DocError::Parser(e.to_string()))?;
    let arr = resolved.as_array().ok_or(DocError::UnexpectedType)?;
    if arr.len() < 4 {
        return Err(DocError::UnexpectedType);
    }

    let get = |idx: usize| -> f32 {
        arr.get(idx)
            .and_then(|o| o.as_f64())
            .map(|f| f as f32)
            .unwrap_or(0.0)
    };

    Ok([get(0), get(1), get(2), get(3)])
}

/// Parse a color array from a resolved object.
fn parse_color_array(obj: &Object) -> Option<Vec<f32>> {
    let arr = obj.as_array()?;
    let colors: Vec<f32> = arr
        .iter()
        .filter_map(|o| o.as_f64().map(|f| f as f32))
        .collect();
    if colors.is_empty() && !arr.is_empty() {
        return None;
    }
    Some(colors)
}

/// Parse border information from `/Border` array or `/BS` dictionary.
fn parse_border<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> Option<AnnotationBorder> {
    // Try /BS (border style dictionary) first — it takes precedence
    if let Some(bs_obj) = dict.get(&Name::bs()) {
        if let Ok(resolved) = store.deep_resolve(bs_obj) {
            if let Some(bs_dict) = resolved.as_dict() {
                let width = bs_dict
                    .get(&Name::w())
                    .and_then(|o| o.as_f64())
                    .map(|f| f as f32)
                    .unwrap_or(1.0);
                let style = bs_dict
                    .get(&Name::s())
                    .and_then(|o| o.as_name())
                    .map(|n| BorderStyle::from_name(&n.as_str()))
                    .unwrap_or(BorderStyle::Solid);
                return Some(AnnotationBorder { width, style });
            }
        }
    }

    // Fall back to /Border array: [horizontal_radius, vertical_radius, width]
    if let Some(border_obj) = dict.get(&Name::border()) {
        if let Ok(resolved) = store.deep_resolve(border_obj) {
            if let Some(arr) = resolved.as_array() {
                // Border array has at least 3 elements
                let width = arr
                    .get(2)
                    .and_then(|o| o.as_f64())
                    .map(|f| f as f32)
                    .unwrap_or(1.0);
                return Some(AnnotationBorder {
                    width,
                    style: BorderStyle::Solid,
                });
            }
        }
    }

    None
}

/// Parse subtype-specific fields from the annotation dictionary.
fn parse_subtype_data<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
    subtype: AnnotationType,
) -> AnnotationSubtypeData {
    let mut data = AnnotationSubtypeData::default();

    match subtype {
        AnnotationType::Highlight
        | AnnotationType::Underline
        | AnnotationType::Squiggly
        | AnnotationType::StrikeOut
        | AnnotationType::Link => {
            data.quad_points = parse_f32_array_field(dict, store, &Name::quad_points());
        }
        AnnotationType::Line => {
            data.line_points = parse_line_points(dict, store);
            data.leader_line_length = parse_f32_field(dict, store, &Name::ll());
        }
        AnnotationType::Polygon | AnnotationType::PolyLine => {
            data.vertices = parse_f32_array_field(dict, store, &Name::vertices());
        }
        AnnotationType::Ink => {
            data.ink_list = parse_ink_list(dict, store);
        }
        AnnotationType::FreeText | AnnotationType::Widget => {
            data.default_appearance = parse_string_field(dict, store, &Name::da());
        }
        AnnotationType::Stamp => {
            data.stamp_name = dict
                .get(&Name::name_key())
                .and_then(|o| store.deep_resolve(o).ok())
                .and_then(|r| r.as_name().map(|n| n.as_str().into_owned()));
        }
        _ => {}
    }

    data
}

fn parse_f32_array_field<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
    key: &Name,
) -> Option<Vec<f32>> {
    let obj = dict.get(key)?;
    let resolved = store.deep_resolve(obj).ok()?;
    let arr = resolved.as_array()?;
    let values: Vec<f32> = arr
        .iter()
        .filter_map(|o| o.as_f64().map(|f| f as f32))
        .collect();
    if values.is_empty() {
        None
    } else {
        Some(values)
    }
}

fn parse_f32_field<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
    key: &Name,
) -> Option<f32> {
    let obj = dict.get(key)?;
    store.deep_resolve(obj).ok()?.as_f64().map(|f| f as f32)
}

fn parse_string_field<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
    key: &Name,
) -> Option<String> {
    let obj = dict.get(key)?;
    let resolved = store.deep_resolve(obj).ok()?;
    resolved.as_string().map(|s| s.to_string_lossy())
}

fn parse_line_points<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> Option<[f32; 4]> {
    let values = parse_f32_array_field(dict, store, &Name::l())?;
    if values.len() >= 4 {
        Some([values[0], values[1], values[2], values[3]])
    } else {
        None
    }
}

/// Strip existing color operators (`g`, `rg`, `k`) from a DA string.
///
/// Used by `set_font_color` to replace the color in an existing `/DA` string
/// before appending the new color operator.
fn strip_da_color(da: &str) -> String {
    // Tokenise the DA string and remove any color-setting operator + its operands.
    // PDF operators appear AFTER their operands, so when we encounter a color operator
    // we pop the already-accumulated operands from the result buffer.
    //
    // Color operators and their operand counts:
    //   g  (1 operand) — grayscale
    //   rg (3 operands) — RGB
    //   k  (4 operands) — CMYK
    let mut result: Vec<&str> = Vec::new();
    for token in da.split_whitespace() {
        match token {
            "g" => {
                if !result.is_empty() {
                    result.pop();
                }
            }
            "rg" => {
                let len = result.len();
                if len >= 3 {
                    result.truncate(len - 3);
                }
            }
            "k" => {
                let len = result.len();
                if len >= 4 {
                    result.truncate(len - 4);
                }
            }
            _ => {
                result.push(token);
            }
        }
    }
    result.join(" ")
}

/// Parse `/Opt` choice-field options from an annotation (or form-field) dictionary.
///
/// Each element can be a string (export == display) or a 2-element array
/// `[export_value, display_value]`.  Mirrors `form_field::parse_options`.
fn parse_choice_options<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> Vec<ChoiceOption> {
    let opt_obj = match dict.get(&Name::opt()) {
        Some(o) => o,
        None => return Vec::new(),
    };
    let resolved = match store.deep_resolve(opt_obj).ok() {
        Some(o) => o,
        None => return Vec::new(),
    };
    let arr = match resolved.as_array() {
        Some(a) => a,
        None => return Vec::new(),
    };

    let mut options = Vec::with_capacity(arr.len());
    for item in arr {
        let ri = match store.deep_resolve(item).ok() {
            Some(o) => o,
            None => continue,
        };
        if let Some(sub) = ri.as_array() {
            if sub.len() >= 2 {
                let export = store
                    .deep_resolve(&sub[0])
                    .ok()
                    .and_then(|o| o.as_string().map(|s| s.to_string_lossy()))
                    .unwrap_or_default();
                let display = store
                    .deep_resolve(&sub[1])
                    .ok()
                    .and_then(|o| o.as_string().map(|s| s.to_string_lossy()))
                    .unwrap_or_default();
                options.push(ChoiceOption {
                    export_value: export,
                    display_value: display,
                });
            }
        } else if let Some(s) = ri.as_string() {
            let val = s.to_string_lossy();
            options.push(ChoiceOption {
                export_value: val.clone(),
                display_value: val,
            });
        }
    }
    options
}

fn parse_ink_list<S: PdfSource>(
    dict: &std::collections::HashMap<Name, Object>,
    store: &ObjectStore<S>,
) -> Option<Vec<Vec<f32>>> {
    let obj = dict.get(&Name::ink_list())?;
    let resolved = store.deep_resolve(obj).ok()?;
    let outer = resolved.as_array()?;
    let mut strokes = Vec::new();
    for item in outer {
        if let Ok(inner) = store.deep_resolve(item) {
            if let Some(arr) = inner.as_array() {
                let points: Vec<f32> = arr
                    .iter()
                    .filter_map(|o| o.as_f64().map(|f| f as f32))
                    .collect();
                if !points.is_empty() {
                    strokes.push(points);
                }
            }
        }
    }
    if strokes.is_empty() {
        None
    } else {
        Some(strokes)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use rpdfium_parser::Object;

    // Tests for parse_annotations and find_parent_annotation are in annot_list.rs.

    #[test]
    fn test_annotation_flags_parsing() {
        // Hidden (bit 2) + Print (bit 3) = 6
        let flags = AnnotationFlags::from_bits(6);
        assert!(!flags.invisible());
        assert!(flags.hidden());
        assert!(flags.print());
        assert!(!flags.no_zoom());
        assert!(!flags.read_only());
    }

    #[test]
    fn test_annotation_flags_invisible_hidden_print() {
        let invisible = AnnotationFlags::from_bits(1);
        assert!(invisible.invisible());
        assert!(!invisible.hidden());

        let hidden = AnnotationFlags::from_bits(2);
        assert!(hidden.hidden());
        assert!(!hidden.is_visible());

        let print = AnnotationFlags::from_bits(4);
        assert!(print.print());
        assert!(print.is_visible());

        let no_view = AnnotationFlags::from_bits(32);
        assert!(no_view.no_view());
        assert!(!no_view.is_visible());
    }

    #[test]
    fn test_annotation_flags_toggle_no_view_locked_contents() {
        let toggle = AnnotationFlags::from_bits(256);
        assert!(toggle.toggle_no_view());
        assert!(!toggle.locked_contents());

        let lc = AnnotationFlags::from_bits(512);
        assert!(!lc.toggle_no_view());
        assert!(lc.locked_contents());

        let both = AnnotationFlags::from_bits(256 | 512);
        assert!(both.toggle_no_view());
        assert!(both.locked_contents());
    }

    #[test]
    fn test_annotation_flags_locked_read_only() {
        let locked = AnnotationFlags::from_bits(128);
        assert!(locked.locked());
        assert!(!locked.read_only());

        let read_only = AnnotationFlags::from_bits(64);
        assert!(read_only.read_only());
        assert!(!read_only.locked());
    }

    #[test]
    fn test_annotation_type_from_name() {
        assert_eq!(AnnotationType::from_name("Text"), AnnotationType::Text);
        assert_eq!(AnnotationType::from_name("Link"), AnnotationType::Link);
        assert_eq!(
            AnnotationType::from_name("FreeText"),
            AnnotationType::FreeText
        );
        assert_eq!(
            AnnotationType::from_name("Highlight"),
            AnnotationType::Highlight
        );
        assert_eq!(
            AnnotationType::from_name("StrikeOut"),
            AnnotationType::StrikeOut
        );
        assert_eq!(AnnotationType::from_name("Widget"), AnnotationType::Widget);
        assert_eq!(AnnotationType::from_name("Movie"), AnnotationType::Movie);
        assert_eq!(AnnotationType::from_name("Screen"), AnnotationType::Screen);
        assert_eq!(
            AnnotationType::from_name("PrinterMark"),
            AnnotationType::PrinterMark
        );
        assert_eq!(
            AnnotationType::from_name("TrapNet"),
            AnnotationType::TrapNet
        );
        assert_eq!(
            AnnotationType::from_name("Watermark"),
            AnnotationType::Watermark
        );
        assert_eq!(AnnotationType::from_name("3D"), AnnotationType::ThreeD);
        assert_eq!(
            AnnotationType::from_name("RichMedia"),
            AnnotationType::RichMedia
        );
        assert_eq!(
            AnnotationType::from_name("XFAWidget"),
            AnnotationType::XFAWidget
        );
        assert_eq!(AnnotationType::from_name("Redact"), AnnotationType::Redact);
        assert_eq!(AnnotationType::from_name("Unknown"), AnnotationType::Other);
    }

    #[test]
    fn test_border_style_from_name() {
        assert_eq!(BorderStyle::from_name("S"), BorderStyle::Solid);
        assert_eq!(BorderStyle::from_name("D"), BorderStyle::Dashed);
        assert_eq!(BorderStyle::from_name("B"), BorderStyle::Beveled);
        assert_eq!(BorderStyle::from_name("I"), BorderStyle::Inset);
        assert_eq!(BorderStyle::from_name("U"), BorderStyle::Underline);
        assert_eq!(BorderStyle::from_name("X"), BorderStyle::Solid); // unknown
    }

    #[test]
    fn test_annotation_border_default() {
        let border = AnnotationBorder::default();
        assert_eq!(border.width, 1.0);
        assert_eq!(border.style, BorderStyle::Solid);
    }

    #[test]
    fn test_color_array_parsing() {
        // 0 components (empty)
        let empty = parse_color_array(&Object::Array(vec![]));
        assert_eq!(empty, Some(vec![]));

        // 1 component (gray)
        let gray = parse_color_array(&Object::Array(vec![Object::Real(0.5)]));
        assert_eq!(gray, Some(vec![0.5]));

        // 3 components (RGB)
        let rgb = parse_color_array(&Object::Array(vec![
            Object::Real(1.0),
            Object::Real(0.0),
            Object::Real(0.0),
        ]));
        assert_eq!(rgb, Some(vec![1.0, 0.0, 0.0]));
    }

    #[test]
    fn test_set_rect_updates_in_memory() {
        let mut annot = Annotation {
            subtype: AnnotationType::Text,
            rect: [0.0, 0.0, 50.0, 50.0],
            contents: None,
            flags: AnnotationFlags::from_bits(0),
            name: None,
            appearance: None,
            color: None,
            border: None,
            action: None,
            destination: None,
            subtype_data: AnnotationSubtypeData::default(),
            mk: None,
            file_spec: None,
            parent_ref: None,
            object_id: None,
            open: None,
            ap_n_bytes: None,
            ap_r_bytes: None,
            ap_d_bytes: None,
            irt_ref: None,
            field_name: None,
            alternate_name: None,
            field_value: None,
            form_field_flags: None,
            additional_actions: None,
            form_field_type: None,
            options: None,
        };
        annot.set_rect([10.0, 20.0, 100.0, 50.0]).unwrap();
        assert_eq!(annot.rect, [10.0, 20.0, 100.0, 50.0]);
    }

    #[test]
    fn test_set_open_state_updates_in_memory() {
        let mut annot = Annotation {
            subtype: AnnotationType::Text,
            rect: [0.0, 0.0, 50.0, 50.0],
            contents: None,
            flags: AnnotationFlags::from_bits(0),
            name: None,
            appearance: None,
            color: None,
            border: None,
            action: None,
            destination: None,
            subtype_data: AnnotationSubtypeData::default(),
            mk: None,
            file_spec: None,
            parent_ref: None,
            object_id: None,
            open: None,
            ap_n_bytes: None,
            ap_r_bytes: None,
            ap_d_bytes: None,
            irt_ref: None,
            field_name: None,
            alternate_name: None,
            field_value: None,
            form_field_flags: None,
            additional_actions: None,
            form_field_type: None,
            options: None,
        };
        annot.set_open_state(true).unwrap();
        assert_eq!(annot.open, Some(true));
    }

    #[test]
    fn test_get_quad_points_returns_none_when_absent() {
        let annot = Annotation {
            subtype: AnnotationType::Text,
            rect: [0.0, 0.0, 50.0, 50.0],
            contents: None,
            flags: AnnotationFlags::from_bits(0),
            name: None,
            appearance: None,
            color: None,
            border: None,
            action: None,
            destination: None,
            subtype_data: AnnotationSubtypeData::default(),
            mk: None,
            file_spec: None,
            parent_ref: None,
            object_id: None,
            open: None,
            ap_n_bytes: None,
            ap_r_bytes: None,
            ap_d_bytes: None,
            irt_ref: None,
            field_name: None,
            alternate_name: None,
            field_value: None,
            form_field_flags: None,
            additional_actions: None,
            form_field_type: None,
            options: None,
        };
        assert!(annot.annot_get_quad_points().is_none());
    }

    #[test]
    fn test_annotation_type_to_name_round_trip() {
        // Every variant except Other should round-trip through to_name/from_name.
        let variants = [
            AnnotationType::Text,
            AnnotationType::Link,
            AnnotationType::FreeText,
            AnnotationType::Line,
            AnnotationType::Square,
            AnnotationType::Circle,
            AnnotationType::Polygon,
            AnnotationType::PolyLine,
            AnnotationType::Highlight,
            AnnotationType::Underline,
            AnnotationType::Squiggly,
            AnnotationType::StrikeOut,
            AnnotationType::Stamp,
            AnnotationType::Caret,
            AnnotationType::Ink,
            AnnotationType::Popup,
            AnnotationType::FileAttachment,
            AnnotationType::Sound,
            AnnotationType::Widget,
            AnnotationType::Movie,
            AnnotationType::Screen,
            AnnotationType::PrinterMark,
            AnnotationType::TrapNet,
            AnnotationType::Watermark,
            AnnotationType::ThreeD,
            AnnotationType::RichMedia,
            AnnotationType::XFAWidget,
            AnnotationType::Redact,
        ];
        for variant in &variants {
            let name = variant.to_name();
            let parsed = AnnotationType::from_name(name);
            assert_eq!(
                *variant, parsed,
                "Round-trip failed for {name}: to_name produced {name:?}, from_name produced {parsed:?}"
            );
        }
    }

    #[test]
    fn test_annotation_type_other_to_name() {
        assert_eq!(AnnotationType::Other.to_name(), "Unknown");
    }

    #[test]
    fn test_get_quad_points_returns_values_when_present() {
        let quad = vec![10.0_f32, 20.0, 100.0, 20.0, 100.0, 30.0, 10.0, 30.0];
        let annot = Annotation {
            subtype: AnnotationType::Highlight,
            rect: [0.0, 0.0, 200.0, 50.0],
            contents: None,
            flags: AnnotationFlags::from_bits(0),
            name: None,
            appearance: None,
            color: None,
            border: None,
            action: None,
            destination: None,
            subtype_data: AnnotationSubtypeData {
                quad_points: Some(quad.clone()),
                ..Default::default()
            },
            mk: None,
            file_spec: None,
            parent_ref: None,
            object_id: None,
            open: None,
            ap_n_bytes: None,
            ap_r_bytes: None,
            ap_d_bytes: None,
            irt_ref: None,
            field_name: None,
            alternate_name: None,
            field_value: None,
            form_field_flags: None,
            additional_actions: None,
            form_field_type: None,
            options: None,
        };
        let qp = annot.annot_get_quad_points().unwrap();
        assert_eq!(qp.len(), 8);
        assert_eq!(qp[0], 10.0);
        assert_eq!(qp[4], 100.0);
    }

    // Helper to build a minimal Annotation for testing getter methods.
    fn make_annot(subtype: AnnotationType) -> Annotation {
        Annotation {
            subtype,
            rect: [10.0, 20.0, 100.0, 50.0],
            contents: Some("Test content".into()),
            flags: AnnotationFlags::from_bits(4), // Print
            name: Some("annot-001".into()),
            appearance: None,
            color: None,
            border: None,
            action: None,
            destination: None,
            subtype_data: AnnotationSubtypeData::default(),
            mk: None,
            file_spec: None,
            parent_ref: None,
            object_id: None,
            open: None,
            ap_n_bytes: None,
            ap_r_bytes: None,
            ap_d_bytes: None,
            irt_ref: None,
            field_name: None,
            alternate_name: None,
            field_value: None,
            form_field_flags: None,
            additional_actions: None,
            form_field_type: None,
            options: None,
        }
    }

    // -----------------------------------------------------------------------
    // subtype() / get_subtype()
    // -----------------------------------------------------------------------
    #[test]
    fn test_subtype_getter_returns_correct_variant() {
        let a = make_annot(AnnotationType::Highlight);
        assert_eq!(a.subtype(), AnnotationType::Highlight);
        assert_eq!(a.annot_get_subtype(), AnnotationType::Highlight);
    }

    // -----------------------------------------------------------------------
    // rect() / get_rect()
    // -----------------------------------------------------------------------
    #[test]
    fn test_rect_getter_returns_rect() {
        let a = make_annot(AnnotationType::Text);
        assert_eq!(a.rect(), [10.0, 20.0, 100.0, 50.0]);
        assert_eq!(a.annot_get_rect(), [10.0, 20.0, 100.0, 50.0]);
    }

    // -----------------------------------------------------------------------
    // flags() / get_flags()
    // -----------------------------------------------------------------------
    #[test]
    fn test_flags_getter_returns_flags() {
        let a = make_annot(AnnotationType::Text);
        assert!(a.flags().print());
        assert_eq!(a.annot_get_flags().bits(), 4);
    }

    // -----------------------------------------------------------------------
    // has_attachment_points()
    // -----------------------------------------------------------------------
    #[test]
    fn test_has_attachment_points_true_for_markup_subtypes() {
        for subtype in [
            AnnotationType::Highlight,
            AnnotationType::Underline,
            AnnotationType::Squiggly,
            AnnotationType::StrikeOut,
            AnnotationType::Link,
        ] {
            let a = make_annot(subtype);
            assert!(
                a.has_attachment_points(),
                "{subtype:?} should support attachment points"
            );
        }
    }

    #[test]
    fn test_has_attachment_points_false_for_other_subtypes() {
        for subtype in [
            AnnotationType::Text,
            AnnotationType::Ink,
            AnnotationType::Line,
        ] {
            let a = make_annot(subtype);
            assert!(
                !a.has_attachment_points(),
                "{subtype:?} should not support attachment points"
            );
        }
    }

    // -----------------------------------------------------------------------
    // attachment_point_count() / count_attachment_points()
    // attachment_points() / get_attachment_points()
    // -----------------------------------------------------------------------
    #[test]
    fn test_attachment_point_count_no_quad_points() {
        let a = make_annot(AnnotationType::Highlight);
        assert_eq!(a.attachment_point_count(), 0);
        assert_eq!(a.annot_count_attachment_points(), 0);
    }

    #[test]
    fn test_attachment_point_count_with_two_quads() {
        let mut a = make_annot(AnnotationType::Highlight);
        // Two quadrilaterals = 16 floats
        a.subtype_data.quad_points = Some(vec![
            1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, // quad 0
            9.0, 10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0, // quad 1
        ]);
        assert_eq!(a.attachment_point_count(), 2);
        let q0 = a.attachment_points(0).unwrap();
        assert_eq!(q0, [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]);
        let q1 = a.annot_get_attachment_points(1).unwrap();
        assert_eq!(q1[0], 9.0);
        // Out of range
        assert!(a.attachment_points(2).is_none());
    }

    // -----------------------------------------------------------------------
    // vertices() / get_vertices()
    // -----------------------------------------------------------------------
    #[test]
    fn test_vertices_none_when_absent() {
        let a = make_annot(AnnotationType::Polygon);
        assert!(a.vertices().is_none());
        assert!(a.annot_get_vertices().is_none());
    }

    #[test]
    fn test_vertices_returns_flat_slice() {
        let mut a = make_annot(AnnotationType::Polygon);
        a.subtype_data.vertices = Some(vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
        let v = a.vertices().unwrap();
        assert_eq!(v.len(), 6);
        assert_eq!(v[0], 1.0);
        assert_eq!(a.annot_get_vertices().unwrap()[2], 3.0);
    }

    // -----------------------------------------------------------------------
    // ink_list_count() / get_ink_list_count()
    // ink_list_path() / get_ink_list_path()
    // -----------------------------------------------------------------------
    #[test]
    fn test_ink_list_count_zero_when_absent() {
        let a = make_annot(AnnotationType::Ink);
        assert_eq!(a.ink_list_count(), 0);
        assert_eq!(a.annot_get_ink_list_count(), 0);
        assert!(a.ink_list_path(0).is_none());
    }

    #[test]
    fn test_ink_list_returns_strokes() {
        let mut a = make_annot(AnnotationType::Ink);
        a.subtype_data.ink_list = Some(vec![
            vec![1.0, 2.0, 3.0, 4.0], // stroke 0: 2 points
            vec![5.0, 6.0],           // stroke 1: 1 point
        ]);
        assert_eq!(a.ink_list_count(), 2);
        assert_eq!(a.annot_get_ink_list_count(), 2);

        let s0 = a.ink_list_path(0).unwrap();
        assert_eq!(s0, &[1.0, 2.0, 3.0, 4.0]);

        let s1 = a.annot_get_ink_list_path(1).unwrap();
        assert_eq!(s1, &[5.0, 6.0]);

        assert!(a.ink_list_path(2).is_none());
    }

    // -----------------------------------------------------------------------
    // line_endpoints() / get_line()
    // -----------------------------------------------------------------------
    #[test]
    fn test_line_endpoints_none_when_absent() {
        let a = make_annot(AnnotationType::Line);
        assert!(a.line_endpoints().is_none());
        assert!(a.annot_get_line().is_none());
    }

    #[test]
    fn test_line_endpoints_returns_two_points() {
        let mut a = make_annot(AnnotationType::Line);
        a.subtype_data.line_points = Some([10.0, 20.0, 300.0, 400.0]);
        let (p1, p2) = a.line_endpoints().unwrap();
        assert_eq!(p1, [10.0, 20.0]);
        assert_eq!(p2, [300.0, 400.0]);

        let (p1b, p2b) = a.annot_get_line().unwrap();
        assert_eq!(p1b, [10.0, 20.0]);
        assert_eq!(p2b, [300.0, 400.0]);
    }

    // -----------------------------------------------------------------------
    // border_style() / get_border()
    // -----------------------------------------------------------------------
    #[test]
    fn test_border_style_none_when_absent() {
        let a = make_annot(AnnotationType::Text);
        assert!(a.border_style().is_none());
        assert!(a.annot_get_border().is_none());
    }

    #[test]
    fn test_border_style_returns_width_with_zero_radii() {
        let mut a = make_annot(AnnotationType::Text);
        a.border = Some(AnnotationBorder {
            width: 2.5,
            style: BorderStyle::Dashed,
        });
        let (h, v, w) = a.border_style().unwrap();
        assert_eq!(h, 0.0);
        assert_eq!(v, 0.0);
        assert_eq!(w, 2.5);
        assert_eq!(a.annot_get_border().unwrap().2, 2.5);
    }

    // -----------------------------------------------------------------------
    // color_rgba() / get_color()
    // -----------------------------------------------------------------------
    #[test]
    fn test_color_rgba_none_when_absent() {
        let a = make_annot(AnnotationType::Text);
        assert!(a.color_rgba().is_none());
        assert!(a.annot_get_color().is_none());
    }

    #[test]
    fn test_color_rgba_gray_one_component() {
        let mut a = make_annot(AnnotationType::Text);
        a.color = Some(vec![0.5]);
        let (r, g, b, al) = a.color_rgba().unwrap();
        assert_eq!(r, 128);
        assert_eq!(g, 128);
        assert_eq!(b, 128);
        assert_eq!(al, 255);
    }

    #[test]
    fn test_color_rgba_rgb_three_components() {
        let mut a = make_annot(AnnotationType::Highlight);
        a.color = Some(vec![1.0, 0.0, 0.0]); // red
        let (r, g, b, al) = a.color_rgba().unwrap();
        assert_eq!(r, 255);
        assert_eq!(g, 0);
        assert_eq!(b, 0);
        assert_eq!(al, 255);
    }

    #[test]
    fn test_color_rgba_cmyk_four_components() {
        let mut a = make_annot(AnnotationType::Text);
        // CMYK (0, 0, 0, 1) = black
        a.color = Some(vec![0.0, 0.0, 0.0, 1.0]);
        let (r, g, b, al) = a.color_rgba().unwrap();
        assert_eq!(r, 0);
        assert_eq!(g, 0);
        assert_eq!(b, 0);
        assert_eq!(al, 255);
    }

    #[test]
    fn test_color_rgba_none_for_zero_components() {
        let mut a = make_annot(AnnotationType::Text);
        a.color = Some(vec![]); // empty /C means "no color"
        // 0-length → None (empty vec returns Some(vec![]), but get_color returns None for len 0)
        // Actually the function matches on len 0 → falls through to _ => None
        assert!(a.color_rgba().is_none());
    }

    // -----------------------------------------------------------------------
    // string_value() / get_string_value() / has_key()
    // -----------------------------------------------------------------------
    #[test]
    fn test_string_value_contents_key() {
        let a = make_annot(AnnotationType::Text);
        assert_eq!(a.string_value("Contents"), Some("Test content"));
        assert_eq!(a.annot_get_string_value("Contents"), Some("Test content"));
        assert!(a.has_key("Contents"));
    }

    #[test]
    fn test_string_value_nm_key() {
        let a = make_annot(AnnotationType::Text);
        assert_eq!(a.string_value("NM"), Some("annot-001"));
        assert_eq!(a.annot_get_string_value("NM"), Some("annot-001"));
        assert!(a.has_key("NM"));
    }

    #[test]
    fn test_string_value_unknown_key_returns_none() {
        let a = make_annot(AnnotationType::Text);
        assert!(a.string_value("UnknownKey").is_none());
        assert!(!a.has_key("UnknownKey"));
    }

    // -----------------------------------------------------------------------
    // number_value() / get_number_value()
    // -----------------------------------------------------------------------
    #[test]
    fn test_number_value_f_key_returns_flags() {
        let a = make_annot(AnnotationType::Text); // flags = 4 (Print)
        assert_eq!(a.number_value("F"), Some(4.0));
        assert_eq!(a.annot_get_number_value("F"), Some(4.0));
    }

    #[test]
    fn test_number_value_border_width_key() {
        let mut a = make_annot(AnnotationType::Text);
        a.border = Some(AnnotationBorder {
            width: 1.5,
            style: BorderStyle::Solid,
        });
        assert_eq!(a.number_value("Border-Width"), Some(1.5));
        assert_eq!(a.annot_get_number_value("Border-Width"), Some(1.5));
    }

    #[test]
    fn test_number_value_unknown_key_returns_none() {
        let a = make_annot(AnnotationType::Text);
        assert!(a.number_value("UnknownKey").is_none());
    }

    // -----------------------------------------------------------------------
    // Gap 2: value_type() / get_value_type() — FPDFAnnot_GetValueType
    // -----------------------------------------------------------------------

    #[test]
    fn test_value_type_string_keys_return_string() {
        let a = make_annot(AnnotationType::Text); // has contents + name
        assert_eq!(a.value_type("Contents"), PdfValueType::String);
        assert_eq!(a.value_type("NM"), PdfValueType::String);
        assert_eq!(a.annot_get_value_type("Contents"), PdfValueType::String);
    }

    #[test]
    fn test_value_type_fixed_type_keys() {
        let a = make_annot(AnnotationType::Text);
        // "F" is always Number (flags field always exists)
        assert_eq!(a.value_type("F"), PdfValueType::Number);
        // "Subtype" is always Name
        assert_eq!(a.value_type("Subtype"), PdfValueType::Name);
        // "Rect" is always Array
        assert_eq!(a.value_type("Rect"), PdfValueType::Array);
    }

    #[test]
    fn test_value_type_absent_optional_fields_return_unknown() {
        let a = make_annot(AnnotationType::Text); // no color, no appearance, no irt
        assert_eq!(a.value_type("C"), PdfValueType::Unknown);
        assert_eq!(a.value_type("AP"), PdfValueType::Unknown);
        assert_eq!(a.value_type("IRT"), PdfValueType::Unknown);
        assert_eq!(a.value_type("NonExistentKey"), PdfValueType::Unknown);
    }

    #[test]
    fn test_value_type_present_optional_fields() {
        let mut a = make_annot(AnnotationType::Text);
        a.color = Some(vec![1.0, 0.0, 0.0]);
        assert_eq!(a.value_type("C"), PdfValueType::Array);
    }

    #[test]
    fn test_value_type_irt_reference_when_set() {
        use rpdfium_parser::ObjectId;
        let mut a = make_annot(AnnotationType::Text);
        a.irt_ref = Some(ObjectId::new(7, 0));
        assert_eq!(a.value_type("IRT"), PdfValueType::Reference);
        assert_eq!(a.annot_get_value_type("IRT"), PdfValueType::Reference);
    }

    // -----------------------------------------------------------------------
    // Gap 3: appearance_stream_bytes() / get_ap() — FPDFAnnot_GetAP
    // -----------------------------------------------------------------------

    #[test]
    fn test_appearance_stream_bytes_none_when_absent() {
        let a = make_annot(AnnotationType::Text);
        assert!(a.appearance_stream_bytes(AppearanceMode::Normal).is_none());
        assert!(a.annot_get_ap(AppearanceMode::Rollover).is_none());
        assert!(a.annot_get_ap(AppearanceMode::Down).is_none());
    }

    #[test]
    fn test_appearance_stream_bytes_returns_stored_bytes() {
        let mut a = make_annot(AnnotationType::Text);
        a.ap_n_bytes = Some(b"q BT /F1 12 Tf ET Q".to_vec());
        let bytes = a.appearance_stream_bytes(AppearanceMode::Normal).unwrap();
        assert_eq!(bytes, b"q BT /F1 12 Tf ET Q");
    }

    #[test]
    fn test_appearance_stream_bytes_mode_isolation() {
        let mut a = make_annot(AnnotationType::Text);
        a.ap_n_bytes = Some(b"normal".to_vec());
        a.ap_r_bytes = Some(b"rollover".to_vec());
        // Down is absent
        assert_eq!(
            a.appearance_stream_bytes(AppearanceMode::Normal).unwrap(),
            b"normal"
        );
        assert_eq!(
            a.annot_get_ap(AppearanceMode::Rollover).unwrap(),
            b"rollover"
        );
        assert!(a.appearance_stream_bytes(AppearanceMode::Down).is_none());
    }

    #[test]
    fn test_set_appearance_stream_bytes_returns_not_supported() {
        let mut a = make_annot(AnnotationType::Text);
        let result = a.set_appearance_stream_bytes(AppearanceMode::Normal, b"data");
        assert!(matches!(result, Err(DocError::NotSupported(_))));
    }

    // -----------------------------------------------------------------------
    // Gap 4: linked_annot_ref() / get_linked_annot() — FPDFAnnot_GetLinkedAnnot
    // -----------------------------------------------------------------------

    #[test]
    fn test_linked_annot_ref_none_when_absent() {
        let a = make_annot(AnnotationType::Text);
        assert!(a.linked_annot_ref().is_none());
        assert!(a.annot_get_linked_annot().is_none());
    }

    #[test]
    fn test_linked_annot_ref_returns_object_id() {
        use rpdfium_parser::ObjectId;
        let mut a = make_annot(AnnotationType::Text);
        a.irt_ref = Some(ObjectId::new(42, 0));
        let oid = a.linked_annot_ref().unwrap();
        assert_eq!(oid.number, 42);
        assert_eq!(oid.generation, 0);
        // ADR-019 alias
        assert_eq!(a.annot_get_linked_annot().unwrap().number, 42);
    }

    #[test]
    fn test_linked_annot_ref_alias_equals_primary() {
        use rpdfium_parser::ObjectId;
        let mut a = make_annot(AnnotationType::Text);
        a.irt_ref = Some(ObjectId::new(10, 1));
        assert_eq!(a.linked_annot_ref(), a.annot_get_linked_annot());
    }

    // -----------------------------------------------------------------------
    // Task 2: field_name / alternate_field_name / field_value_str
    // FPDFAnnot_GetFormFieldName / FPDFAnnot_GetFormFieldAlternateName /
    // FPDFAnnot_GetFormFieldValue
    // -----------------------------------------------------------------------

    #[test]
    fn test_field_name_none_when_absent() {
        let a = make_annot(AnnotationType::Widget);
        assert!(a.field_name().is_none());
        assert!(a.annot_get_form_field_name().is_none());
    }

    #[test]
    fn test_field_name_returns_t_value() {
        let mut a = make_annot(AnnotationType::Widget);
        a.field_name = Some("FirstName".into());
        assert_eq!(a.field_name(), Some("FirstName"));
        assert_eq!(a.annot_get_form_field_name(), Some("FirstName"));
        // string_value("T") should also work
        assert_eq!(a.string_value("T"), Some("FirstName"));
    }

    #[test]
    fn test_alternate_field_name_and_field_value() {
        let mut a = make_annot(AnnotationType::Widget);
        a.alternate_name = Some("Your first name".into());
        a.field_value = Some("Alice".into());
        assert_eq!(a.alternate_field_name(), Some("Your first name"));
        assert_eq!(
            a.annot_get_form_field_alternate_name(),
            Some("Your first name")
        );
        assert_eq!(a.field_value_str(), Some("Alice"));
        assert_eq!(a.annot_get_form_field_value(), Some("Alice"));
        // string_value() aliases
        assert_eq!(a.string_value("TU"), Some("Your first name"));
        assert_eq!(a.string_value("V"), Some("Alice"));
    }

    #[test]
    fn test_field_value_none_for_non_widget() {
        // Text annotations typically have no /V; make sure None is correct.
        let a = make_annot(AnnotationType::Text);
        assert!(a.field_value_str().is_none());
        assert!(a.annot_get_form_field_value().is_none());
    }

    // -----------------------------------------------------------------------
    // Task 3: AnnotationType::supports_ap_objects()
    // FPDFAnnot_IsObjectSupportedSubtype
    // -----------------------------------------------------------------------

    #[test]
    fn test_supports_ap_objects_true_for_supported_subtypes() {
        let supported = [
            AnnotationType::Stamp,
            AnnotationType::FreeText,
            AnnotationType::Ink,
            AnnotationType::Square,
            AnnotationType::Circle,
            AnnotationType::Polygon,
            AnnotationType::PolyLine,
            AnnotationType::Line,
            AnnotationType::Highlight,
            AnnotationType::Underline,
            AnnotationType::Squiggly,
            AnnotationType::StrikeOut,
        ];
        for subtype in &supported {
            assert!(
                subtype.supports_ap_objects(),
                "{subtype:?} should support AP objects"
            );
            assert!(
                subtype.annot_is_object_supported_subtype(),
                "{subtype:?} alias should also return true"
            );
        }
    }

    #[test]
    fn test_supports_ap_objects_false_for_text_annotation() {
        let a = AnnotationType::Text;
        assert!(!a.supports_ap_objects());
        assert!(!a.annot_is_object_supported_subtype());
    }

    #[test]
    fn test_supports_ap_objects_false_for_widget() {
        let w = AnnotationType::Widget;
        assert!(!w.supports_ap_objects());
        assert!(!w.annot_is_object_supported_subtype());
    }

    // -----------------------------------------------------------------------
    // Gap: form_field_flags() / get_form_field_flags() — FPDFAnnot_GetFormFieldFlags
    // -----------------------------------------------------------------------

    #[test]
    fn test_form_field_flags_none_when_absent() {
        let a = make_annot(AnnotationType::Widget);
        assert!(a.form_field_flags().is_none());
        assert!(a.annot_get_form_field_flags().is_none());
    }

    #[test]
    fn test_form_field_flags_returns_value_when_present() {
        use crate::form_field::FormFieldFlags;
        let mut a = make_annot(AnnotationType::Widget);
        // Bit 1 (0x1) = ReadOnly
        a.form_field_flags = Some(FormFieldFlags::from_bits(1));
        let flags = a.form_field_flags().unwrap();
        assert!(flags.is_read_only());
        // ADR-019 alias
        let flags2 = a.annot_get_form_field_flags().unwrap();
        assert!(flags2.is_read_only());
    }

    #[test]
    fn test_form_field_flags_alias_equals_primary() {
        use crate::form_field::FormFieldFlags;
        let mut a = make_annot(AnnotationType::Widget);
        a.form_field_flags = Some(FormFieldFlags::from_bits(2)); // Required
        assert_eq!(a.form_field_flags(), a.annot_get_form_field_flags());
    }

    // -----------------------------------------------------------------------
    // Gap: link_ref() / get_link() — FPDFAnnot_GetLink
    // -----------------------------------------------------------------------

    #[test]
    fn test_link_ref_none_when_no_action_or_dest() {
        let a = make_annot(AnnotationType::Link);
        let (action, dest) = a.link_ref();
        assert!(action.is_none());
        assert!(dest.is_none());
        // ADR-019 alias
        let (action2, dest2) = a.annot_get_link();
        assert!(action2.is_none());
        assert!(dest2.is_none());
    }

    #[test]
    fn test_link_ref_returns_destination_when_present() {
        use crate::destination::{Destination, PageFit};
        let mut a = make_annot(AnnotationType::Link);
        a.destination = Some(Destination::Page {
            page_index: 3,
            page_ref: None,
            fit: PageFit::Fit,
        });
        let (action, dest) = a.link_ref();
        assert!(action.is_none());
        let dest = dest.unwrap();
        assert_eq!(dest.dest_page_index(), Some(3));
    }

    // -----------------------------------------------------------------------
    // Gap: file_attachment() / get_file_attachment() — FPDFAnnot_GetFileAttachment
    // -----------------------------------------------------------------------

    #[test]
    fn test_file_attachment_none_when_absent() {
        let a = make_annot(AnnotationType::FileAttachment);
        assert!(a.file_attachment().is_none());
        assert!(a.annot_get_file_attachment().is_none());
    }

    #[test]
    fn test_file_attachment_returns_file_spec_when_present() {
        use crate::file_spec::FileSpec;
        let mut a = make_annot(AnnotationType::FileAttachment);
        a.file_spec = Some(FileSpec {
            file_system: None,
            filename: Some("attachment.pdf".to_string()),
            unicode_filename: None,
            dos_filename: None,
            unix_filename: None,
            embedded_file: None,
            description: None,
            data: None,
        });
        let fs = a.file_attachment().unwrap();
        assert_eq!(fs.filename, Some("attachment.pdf".to_string()));
        // ADR-019 alias
        let fs2 = a.annot_get_file_attachment().unwrap();
        assert_eq!(fs2.filename, Some("attachment.pdf".to_string()));
    }

    // -----------------------------------------------------------------------
    // Batch 18: is_supported_for_creation() — FPDFAnnot_IsSupportedSubtype
    // -----------------------------------------------------------------------

    #[test]
    fn test_is_supported_for_creation_true_for_highlight() {
        assert!(AnnotationType::Highlight.is_supported_for_creation());
    }

    #[test]
    fn test_is_supported_for_creation_false_for_widget() {
        assert!(!AnnotationType::Widget.is_supported_for_creation());
    }

    // -----------------------------------------------------------------------
    // Upstream: CPDF_Annot quad-point utility tests
    // -----------------------------------------------------------------------

    /// Helper: given a flat array of f32 values representing QuadPoints,
    /// extract the rect for one quadrilateral at `quad_index`.
    ///
    /// Each quad is 8 floats: [x1,y1, x2,y2, x3,y3, x4,y4].
    /// The rect is (left=x3, bottom=y3, right=x2, top=y2) — matching
    /// upstream CPDF_Annot::RectFromQuadPointsArray.
    fn rect_from_quad_points_array(points: &[f32], quad_index: usize) -> [f32; 4] {
        let base = quad_index * 8;
        if base + 7 >= points.len() {
            return [0.0, 0.0, 0.0, 0.0];
        }
        // Upstream layout: x1,y1 x2,y2 x3,y3 x4,y4
        // Rect: left=x3, bottom=y3, right=x2, top=y2
        let x2 = points[base + 2];
        let y2 = points[base + 3];
        let x3 = points[base + 4];
        let y3 = points[base + 5];
        [x3, y3, x2, y2] // [left, bottom, right, top]
    }

    /// Helper: count how many complete quadrilaterals (groups of 8 floats)
    /// are in the given array.
    fn quad_point_count(points: &[f32]) -> usize {
        points.len() / 8
    }

    /// Helper: compute the bounding rect of all quad points in a flat array.
    fn bounding_rect_from_quads(points: &[f32]) -> [f32; 4] {
        let count = quad_point_count(points);
        if count == 0 {
            return [0.0, 0.0, 0.0, 0.0];
        }
        let mut result = rect_from_quad_points_array(points, 0);
        for i in 1..count {
            let r = rect_from_quad_points_array(points, i);
            result[0] = result[0].min(r[0]); // left
            result[1] = result[1].min(r[1]); // bottom
            result[2] = result[2].max(r[2]); // right
            result[3] = result[3].max(r[3]); // top
        }
        result
    }

    /// Upstream: TEST(CPDFAnnotTest, RectFromQuadPointsArray)
    #[test]
    fn test_cpdf_annot_rect_from_quad_points_array() {
        let points: Vec<f32> = vec![
            0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, // quad 0
            8.0, 7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0, // quad 1
        ];

        let rect0 = rect_from_quad_points_array(&points, 0);
        assert_eq!(rect0, [4.0, 5.0, 2.0, 3.0]);

        let rect1 = rect_from_quad_points_array(&points, 1);
        assert_eq!(rect1, [4.0, 3.0, 6.0, 5.0]);
    }

    /// Upstream: TEST(CPDFAnnotTest, BoundingRectFromQuadPoints)
    #[test]
    fn test_cpdf_annot_bounding_rect_from_quad_points() {
        // Empty array
        let empty: Vec<f32> = vec![];
        assert_eq!(bounding_rect_from_quads(&empty), [0.0, 0.0, 0.0, 0.0]);

        // Too few elements (not a complete quad)
        let few = vec![0.0, 1.0, 2.0];
        assert_eq!(bounding_rect_from_quads(&few), [0.0, 0.0, 0.0, 0.0]);

        // One quad
        let one_quad = vec![0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0];
        assert_eq!(bounding_rect_from_quads(&one_quad), [4.0, 5.0, 2.0, 3.0]);

        // Three quads — bounding rect should be the union
        let three_quads = vec![
            0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, // quad 0
            8.0, 7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0, // quad 1
            9.0, 2.0, 5.0, 7.0, 3.0, 6.0, 4.0, 1.0, // quad 2
        ];
        let rect = bounding_rect_from_quads(&three_quads);
        assert_eq!(rect[0], 3.0); // min left
        assert_eq!(rect[1], 3.0); // min bottom
        assert_eq!(rect[2], 6.0); // max right
        assert_eq!(rect[3], 7.0); // max top
    }

    /// Upstream: TEST(CPDFAnnotTest, RectFromQuadPoints)
    ///
    /// Tests rect extraction from quad points at various indices,
    /// including out-of-range indices returning zero rect.
    #[test]
    fn test_cpdf_annot_rect_from_quad_points() {
        // Empty
        let empty: Vec<f32> = vec![];
        assert_eq!(rect_from_quad_points_array(&empty, 0), [0.0, 0.0, 0.0, 0.0]);
        assert_eq!(rect_from_quad_points_array(&empty, 5), [0.0, 0.0, 0.0, 0.0]);

        // One quad
        let one = vec![0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0];
        assert_eq!(rect_from_quad_points_array(&one, 0), [4.0, 5.0, 2.0, 3.0]);
        assert_eq!(rect_from_quad_points_array(&one, 5), [0.0, 0.0, 0.0, 0.0]);

        // Three quads
        let three = vec![
            0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 7.0, 6.0, 5.0, 4.0, 3.0, 2.0, 1.0, 9.0,
            2.0, 5.0, 7.0, 3.0, 6.0, 4.0, 1.0,
        ];
        assert_eq!(rect_from_quad_points_array(&three, 0), [4.0, 5.0, 2.0, 3.0]);
        assert_eq!(rect_from_quad_points_array(&three, 1), [4.0, 3.0, 6.0, 5.0]);
        assert_eq!(rect_from_quad_points_array(&three, 2), [3.0, 6.0, 5.0, 7.0]);
    }

    /// Upstream: TEST(CPDFAnnotTest, QuadPointCount)
    #[test]
    fn test_cpdf_annot_quad_point_count() {
        let empty: Vec<f32> = vec![];
        assert_eq!(quad_point_count(&empty), 0);

        // 0..7 elements => 0 quads
        for n in 0..8 {
            let arr: Vec<f32> = vec![0.0; n];
            assert_eq!(quad_point_count(&arr), 0);
        }
        // 8..15 elements => 1 quad
        for n in 8..16 {
            let arr: Vec<f32> = vec![0.0; n];
            assert_eq!(quad_point_count(&arr), 1);
        }
        // 65 elements => 8 quads (65 / 8 = 8)
        let arr: Vec<f32> = vec![0.0; 65];
        assert_eq!(quad_point_count(&arr), 8);
    }

    // -----------------------------------------------------------------------
    // font_size() / annot_get_font_size()
    // -----------------------------------------------------------------------

    #[test]
    fn test_font_size_returns_size_from_da() {
        let mut a = make_annot(AnnotationType::FreeText);
        a.subtype_data.default_appearance = Some("/Helv 12 Tf 0 g".into());
        assert_eq!(a.font_size(), Some(12.0));
        assert_eq!(a.annot_get_font_size(), Some(12.0));
    }

    #[test]
    fn test_font_size_returns_none_when_no_da() {
        let a = make_annot(AnnotationType::FreeText);
        assert!(a.font_size().is_none());
    }

    #[test]
    fn test_font_size_returns_none_for_zero_size() {
        let mut a = make_annot(AnnotationType::FreeText);
        a.subtype_data.default_appearance = Some("/Helv 0 Tf".into());
        assert!(a.font_size().is_none());
    }

    // -----------------------------------------------------------------------
    // font_color() / annot_get_font_color() / set_font_color() / annot_set_font_color()
    // -----------------------------------------------------------------------

    #[test]
    fn test_font_color_rgb_from_da() {
        let mut a = make_annot(AnnotationType::FreeText);
        a.subtype_data.default_appearance = Some("/Helv 12 Tf 1 0 0 rg".into());
        assert_eq!(a.font_color(), Some((255, 0, 0)));
        assert_eq!(a.annot_get_font_color(), Some((255, 0, 0)));
    }

    #[test]
    fn test_font_color_grayscale_from_da() {
        let mut a = make_annot(AnnotationType::FreeText);
        a.subtype_data.default_appearance = Some("0.5 g /Helv 12 Tf".into());
        let (r, g, b) = a.font_color().unwrap();
        assert_eq!(r, g);
        assert_eq!(g, b);
        assert!(r >= 127 && r <= 128);
    }

    #[test]
    fn test_font_color_returns_none_when_no_da() {
        let a = make_annot(AnnotationType::FreeText);
        assert!(a.font_color().is_none());
    }

    #[test]
    fn test_set_font_color_updates_da() {
        let mut a = make_annot(AnnotationType::FreeText);
        a.subtype_data.default_appearance = Some("/Helv 12 Tf 0 g".into());
        a.set_font_color(255, 0, 0).unwrap();
        let da = a.subtype_data.default_appearance.as_deref().unwrap();
        assert!(da.contains("rg"), "DA should contain rg operator: {da}");
        assert_eq!(a.font_color(), Some((255, 0, 0)));
    }

    #[test]
    fn test_set_font_color_on_widget() {
        let mut a = make_annot(AnnotationType::Widget);
        a.set_font_color(0, 128, 0).unwrap();
        let (r, g, b) = a.font_color().unwrap();
        assert_eq!(r, 0);
        assert!(g >= 127 && g <= 128);
        assert_eq!(b, 0);
    }

    #[test]
    fn test_set_font_color_errors_on_non_widget() {
        let mut a = make_annot(AnnotationType::Text);
        assert!(a.set_font_color(0, 0, 0).is_err());
    }

    // -----------------------------------------------------------------------
    // form_additional_action_javascript() / annot_get_form_additional_action_javascript()
    // -----------------------------------------------------------------------

    // -----------------------------------------------------------------------
    // strip_da_color() — internal helper
    // -----------------------------------------------------------------------

    #[test]
    fn test_strip_da_color_removes_grayscale() {
        assert_eq!(strip_da_color("/Helv 12 Tf 0 g"), "/Helv 12 Tf");
    }

    #[test]
    fn test_strip_da_color_removes_rgb() {
        assert_eq!(strip_da_color("/Helv 12 Tf 1 0 0 rg"), "/Helv 12 Tf");
    }

    #[test]
    fn test_strip_da_color_removes_cmyk() {
        assert_eq!(strip_da_color("/Helv 12 Tf 0 0 0 1 k"), "/Helv 12 Tf");
    }

    #[test]
    fn test_strip_da_color_color_before_font() {
        assert_eq!(strip_da_color("0 g /Helv 12 Tf"), "/Helv 12 Tf");
    }

    #[test]
    fn test_strip_da_color_no_color_unchanged() {
        assert_eq!(strip_da_color("/Helv 12 Tf"), "/Helv 12 Tf");
    }

    #[test]
    fn test_strip_da_color_empty() {
        assert_eq!(strip_da_color(""), "");
    }

    #[test]
    fn test_form_additional_action_javascript_none_when_no_aa() {
        let a = make_annot(AnnotationType::Widget);
        use crate::aaction::AActionType;
        assert_eq!(
            a.form_additional_action_javascript(AActionType::KeyStroke),
            ""
        );
    }

    #[test]
    fn test_form_additional_action_javascript_returns_code() {
        use crate::aaction::{AActionType, AdditionalActions};
        use crate::action::Action;
        use std::collections::HashMap;

        let mut entries = HashMap::new();
        entries.insert(
            "K".to_string(),
            Action::JavaScript {
                code: "alert(1)".into(),
            },
        );
        let aa = AdditionalActions { entries };
        let mut a = make_annot(AnnotationType::Widget);
        a.additional_actions = Some(aa);

        assert_eq!(
            a.form_additional_action_javascript(AActionType::KeyStroke),
            "alert(1)"
        );
        assert_eq!(
            a.annot_get_form_additional_action_javascript(AActionType::KeyStroke),
            "alert(1)"
        );
    }

    // -----------------------------------------------------------------------
    // G6: form_field_type / form_control stubs
    // -----------------------------------------------------------------------

    #[test]
    fn test_form_field_type_none_for_non_widget() {
        let a = make_annot(AnnotationType::Text);
        assert!(a.form_field_type().is_none());
        assert!(a.annot_get_form_field_type().is_none());
    }

    #[test]
    fn test_form_field_type_returns_set_value() {
        let mut a = make_annot(AnnotationType::Widget);
        a.form_field_type = Some(FormFieldType::Text);
        assert_eq!(a.form_field_type(), Some(FormFieldType::Text));
        a.form_field_type = Some(FormFieldType::Choice);
        assert_eq!(a.annot_get_form_field_type(), Some(FormFieldType::Choice));
    }

    #[test]
    fn test_form_control_count_returns_not_supported() {
        let a = make_annot(AnnotationType::Widget);
        assert!(a.form_control_count().is_err());
        assert!(a.annot_get_form_control_count().is_err());
    }

    #[test]
    fn test_form_control_index_returns_not_supported() {
        let a = make_annot(AnnotationType::Widget);
        assert!(a.form_control_index().is_err());
        assert!(a.annot_get_form_control_index().is_err());
    }

    #[test]
    fn test_form_field_export_value_returns_not_supported() {
        let a = make_annot(AnnotationType::Widget);
        assert!(a.form_field_export_value().is_err());
        assert!(a.annot_get_form_field_export_value().is_err());
    }

    // -----------------------------------------------------------------------
    // G7: is_checked / option_count / option_label / is_option_selected
    // -----------------------------------------------------------------------

    #[test]
    fn test_is_checked_off_is_unchecked() {
        let mut a = make_annot(AnnotationType::Widget);
        a.field_value = Some("Off".into());
        assert!(!a.is_checked());
        assert!(!a.annot_is_checked());
    }

    #[test]
    fn test_is_checked_none_is_unchecked() {
        let mut a = make_annot(AnnotationType::Widget);
        a.field_value = None;
        assert!(!a.is_checked());
    }

    #[test]
    fn test_is_checked_yes_is_checked() {
        let mut a = make_annot(AnnotationType::Widget);
        a.field_value = Some("Yes".into());
        assert!(a.is_checked());
        assert!(a.annot_is_checked());
    }

    #[test]
    fn test_option_count_none_when_no_options() {
        let a = make_annot(AnnotationType::Widget);
        assert_eq!(a.option_count(), 0);
        assert_eq!(a.annot_get_option_count(), 0);
    }

    #[test]
    fn test_option_count_and_label() {
        let mut a = make_annot(AnnotationType::Widget);
        a.options = Some(vec![
            ChoiceOption {
                export_value: "a".into(),
                display_value: "Apple".into(),
            },
            ChoiceOption {
                export_value: "b".into(),
                display_value: "Banana".into(),
            },
        ]);
        assert_eq!(a.option_count(), 2);
        assert_eq!(a.option_label(0), Some("Apple"));
        assert_eq!(a.annot_get_option_label(1), Some("Banana"));
        assert!(a.option_label(2).is_none());
    }

    #[test]
    fn test_is_option_selected() {
        let mut a = make_annot(AnnotationType::Widget);
        a.options = Some(vec![
            ChoiceOption {
                export_value: "a".into(),
                display_value: "Apple".into(),
            },
            ChoiceOption {
                export_value: "b".into(),
                display_value: "Banana".into(),
            },
        ]);
        a.field_value = Some("b".into());
        assert!(!a.is_option_selected(0));
        assert!(a.is_option_selected(1));
        assert!(!a.annot_is_option_selected(2)); // out of bounds
    }

    // -----------------------------------------------------------------------
    // G8: focusable subtype stubs
    // -----------------------------------------------------------------------

    #[test]
    fn test_focusable_subtype_count_returns_not_supported() {
        let a = make_annot(AnnotationType::Widget);
        assert!(a.focusable_subtype_count().is_err());
        assert!(a.annot_get_focusable_subtypes_count().is_err());
    }

    #[test]
    fn test_set_focusable_subtypes_returns_not_supported() {
        let mut a = make_annot(AnnotationType::Widget);
        assert!(a.set_focusable_subtypes(&[]).is_err());
        assert!(a.annot_set_focusable_subtypes(&[]).is_err());
    }

    // -----------------------------------------------------------------------
    // G9: set_flags / set_form_field_flags
    // -----------------------------------------------------------------------

    #[test]
    fn test_set_flags_updates_in_memory() {
        let mut a = make_annot(AnnotationType::Text);
        assert!(a.flags().print()); // starts with Print flag (bits=4)
        a.set_flags(AnnotationFlags::from_bits(0)).unwrap();
        assert!(!a.flags().print());
        a.annot_set_flags(AnnotationFlags::from_bits(2)).unwrap();
        assert!(a.flags().hidden());
    }

    #[test]
    fn test_set_form_field_flags_updates_in_memory() {
        use crate::form_field::FormFieldFlags;
        let mut a = make_annot(AnnotationType::Widget);
        assert!(a.form_field_flags().is_none());
        a.set_form_field_flags(FormFieldFlags::from_bits(1))
            .unwrap();
        assert_eq!(a.form_field_flags().map(|f| f.bits()), Some(1));
        a.annot_set_form_field_flags(FormFieldFlags::from_bits(3))
            .unwrap();
        assert_eq!(a.form_field_flags().map(|f| f.bits()), Some(3));
    }
}