rpdfium_edit/

fpdf_annot.rs

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

//! Annotation editing — create, modify, and delete annotations on pages.

use std::collections::HashMap;

use rpdfium_core::Name;
use rpdfium_doc::{Annotation, AnnotationFlags, AnnotationType, generate_annotation_appearance};
use rpdfium_parser::object::{Object, ObjectId, StreamData};

use crate::cpdf_pagecontentgenerator::{
    ResourceCollector, build_resource_dict, generate_content_stream,
};
use crate::document::EditDocument;
use crate::error::EditError;
use crate::page_object::PageObject;

/// Specification for a new annotation.
#[derive(Debug, Clone)]
pub struct AnnotationSpec {
    /// The annotation subtype.
    pub subtype: AnnotationType,
    /// The annotation rectangle [x1, y1, x2, y2].
    pub rect: [f32; 4],
    /// Optional text contents.
    pub contents: Option<String>,
    /// Optional color components (RGB: 3, CMYK: 4, Gray: 1).
    pub color: Option<Vec<f32>>,
    /// Annotation flags.
    pub flags: AnnotationFlags,
    /// Optional quad points (for markup annotations).
    pub quad_points: Option<Vec<f32>>,
}

/// Builder for creating annotation specifications.
pub struct AnnotationBuilder {
    spec: AnnotationSpec,
}

impl AnnotationBuilder {
    /// Create a new annotation builder.
    pub fn new(subtype: AnnotationType, rect: [f32; 4]) -> Self {
        Self {
            spec: AnnotationSpec {
                subtype,
                rect,
                contents: None,
                color: None,
                flags: AnnotationFlags::default(),
                quad_points: None,
            },
        }
    }

    /// Set the annotation contents text.
    pub fn contents(mut self, text: &str) -> Self {
        self.spec.contents = Some(text.to_string());
        self
    }

    /// Set the annotation color.
    pub fn color(mut self, color: Vec<f32>) -> Self {
        self.spec.color = Some(color);
        self
    }

    /// Set the annotation flags.
    pub fn flags(mut self, flags: AnnotationFlags) -> Self {
        self.spec.flags = flags;
        self
    }

    /// Set quad points (for highlight, underline, etc.).
    pub fn quad_points(mut self, points: Vec<f32>) -> Self {
        self.spec.quad_points = Some(points);
        self
    }

    /// Build the annotation specification.
    pub fn build(self) -> AnnotationSpec {
        self.spec
    }
}

/// Updates to apply to an existing annotation.
#[derive(Debug, Clone, Default)]
pub struct AnnotationUpdates {
    /// New contents text.
    pub contents: Option<String>,
    /// New color.
    pub color: Option<Vec<f32>>,
    /// New flags.
    pub flags: Option<AnnotationFlags>,
    /// New rect.
    pub rect: Option<[f32; 4]>,
    /// Open/closed state for Text and Popup annotations (`/Open`).
    pub open: Option<bool>,
    /// Annotation subject (`/Subj`).
    ///
    /// Corresponds to `FPDFAnnot_SetStringValue` with key `/Subj`.
    pub subject: Option<String>,
    /// Annotation author/title (`/T`).
    ///
    /// Corresponds to `FPDFAnnot_SetStringValue` with key `/T`.
    pub author: Option<String>,
    /// Simple border width in points (`/BS /W`).
    ///
    /// Sets the border-style dictionary width.  Pass `Some(0.0)` to hide the
    /// border; `None` leaves the existing border unchanged.
    ///
    /// Corresponds to `FPDFAnnot_SetBorderWidth`.
    pub border_width: Option<f32>,

    /// Full border triple `(horizontal_radius, vertical_radius, width)` written to `/Border`.
    ///
    /// This takes precedence over `border_width` when both are set.
    ///
    /// Corresponds to `FPDFAnnot_SetBorder()`.
    pub border_style: Option<(f32, f32, f32)>,

    /// Annotation color as `(red, green, blue, alpha)` in 0–255 range.
    ///
    /// Stored as a 3-component `/C` array (RGB) in the PDF dictionary; the alpha
    /// channel is currently ignored (PDF does not support annotation opacity via `/C`).
    ///
    /// Corresponds to `FPDFAnnot_SetColor()`.
    pub color_rgba: Option<(u8, u8, u8, u8)>,

    /// Attachment (quad) point groups for markup annotations.
    ///
    /// Each element is 8 floats `[x1,y1, x2,y2, x3,y3, x4,y4]`.
    /// Replaces the entire `/QuadPoints` array.
    ///
    /// Corresponds to `FPDFAnnot_SetAttachmentPoints()` (for a single group) /
    /// writing all groups at once.
    pub attachment_points: Option<Vec<[f32; 8]>>,

    /// Ink strokes for Ink annotations.
    ///
    /// Each inner `Vec<f32>` is a flat `[x, y, x, y, …]` sequence for one stroke.
    /// Replaces the entire `/InkList` array.
    ///
    /// Corresponds to `FPDFAnnot_AddInkStroke()` / `FPDFAnnot_RemoveInkList()`.
    pub ink_list: Option<Vec<Vec<f32>>>,

    /// Arbitrary string value to write: `(key, value)`.
    ///
    /// Writes `/<key> <value-as-PDF-string>` into the annotation dictionary.
    /// Useful for less common keys not covered by the other fields.
    ///
    /// Corresponds to `FPDFAnnot_SetStringValue()`.
    pub extra_string: Option<(String, String)>,

    /// Polygon/PolyLine vertex pairs to write as `/Vertices`.
    ///
    /// Each element is an `[x, y]` coordinate pair. Replaces the entire
    /// `/Vertices` array in the annotation dictionary.
    ///
    /// Corresponds to `FPDFAnnot_SetVertices()`.
    pub vertices: Option<Vec<[f32; 2]>>,

    /// Set a URI action on the annotation (`/A << /S /URI /URI (uri) >>`).
    ///
    /// Writes an action dictionary with subtype `/URI` and the given URI string
    /// into the annotation's `/A` entry.
    ///
    /// Corresponds to `FPDFAnnot_SetURI()`.
    pub uri_action: Option<String>,
}

impl AnnotationUpdates {
    /// Append a new set of attachment points (quadpoints) to the list.
    ///
    /// If `attachment_points` is currently `None`, this initialises it to an
    /// empty list before appending. Note that once any element is set, the
    /// **entire** attachment-points array will be written on
    /// [`EditDocument::update_annotation`](crate::document::EditDocument::update_annotation).
    ///
    /// # Upstream Correspondence
    ///
    /// `FPDFAnnot_AppendAttachmentPoints`.
    pub fn append_attachment_points(&mut self, quad: [f32; 8]) -> &mut Self {
        self.attachment_points
            .get_or_insert_with(Vec::new)
            .push(quad);
        self
    }
}

impl EditDocument {
    /// Add an annotation to a page.
    ///
    /// Returns the object ID of the new annotation dictionary.
    pub fn add_annotation(
        &mut self,
        page_index: usize,
        spec: AnnotationSpec,
    ) -> Result<ObjectId, EditError> {
        let count = self.page_count();
        if page_index >= count {
            return Err(EditError::PageOutOfRange {
                index: page_index,
                count,
            });
        }

        // Build annotation dictionary
        let mut annot_dict = HashMap::new();
        annot_dict.insert(Name::r#type(), Object::Name(Name::annot()));
        annot_dict.insert(
            Name::subtype(),
            Object::Name(Name::from_bytes(
                annotation_type_name(&spec.subtype).to_vec(),
            )),
        );
        annot_dict.insert(
            Name::rect(),
            Object::Array(vec![
                Object::Real(spec.rect[0] as f64),
                Object::Real(spec.rect[1] as f64),
                Object::Real(spec.rect[2] as f64),
                Object::Real(spec.rect[3] as f64),
            ]),
        );

        if let Some(text) = &spec.contents {
            annot_dict.insert(
                Name::contents(),
                Object::String(rpdfium_core::PdfString::from_bytes(
                    text.as_bytes().to_vec(),
                )),
            );
        }

        if let Some(color) = &spec.color {
            let color_arr: Vec<Object> = color.iter().map(|&c| Object::Real(c as f64)).collect();
            annot_dict.insert(Name::c(), Object::Array(color_arr));
        }

        let flags_val = spec.flags.bits();
        if flags_val != 0 {
            annot_dict.insert(Name::f(), Object::Integer(flags_val as i64));
        }

        if let Some(qp) = &spec.quad_points {
            let qp_arr: Vec<Object> = qp.iter().map(|&p| Object::Real(p as f64)).collect();
            annot_dict.insert(Name::quad_points(), Object::Array(qp_arr));
        }

        // Set /P (parent page reference) — PDF spec recommends this entry.
        let page_id = self.page_ids()[page_index];
        annot_dict.insert(Name::p(), Object::Reference(page_id));

        // Auto-generate appearance stream (AP) so viewers can render the annotation.
        // Build a minimal Annotation struct for the AP generator.
        let temp_annot = Annotation {
            subtype: spec.subtype,
            rect: spec.rect,
            contents: spec.contents.clone(),
            flags: spec.flags,
            color: spec.color.clone(),
            name: None,
            appearance: None,
            border: None,
            action: None,
            destination: None,
            subtype_data: 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,
        };
        if let Some(ap_bytes) = generate_annotation_appearance(&temp_annot) {
            // Create an AP stream XObject
            let w = (spec.rect[2] - spec.rect[0]).abs();
            let h = (spec.rect[3] - spec.rect[1]).abs();
            let mut ap_stream_dict = HashMap::new();
            ap_stream_dict.insert(Name::r#type(), Object::Name(Name::x_object()));
            ap_stream_dict.insert(Name::subtype(), Object::Name(Name::form()));
            ap_stream_dict.insert(
                Name::b_box(),
                Object::Array(vec![
                    Object::Real(0.0),
                    Object::Real(0.0),
                    Object::Real(w as f64),
                    Object::Real(h as f64),
                ]),
            );
            let ap_stream = Object::Stream {
                dict: ap_stream_dict,
                data: StreamData::Decoded { data: ap_bytes },
            };
            let ap_id = self.add_object(ap_stream);

            // Set /AP /N on the annotation dict
            let mut ap_dict = HashMap::new();
            ap_dict.insert(Name::n(), Object::Reference(ap_id));
            annot_dict.insert(Name::ap(), Object::Dictionary(ap_dict));
        }

        let annot_id = self.add_object(Object::Dictionary(annot_dict));

        // Add to page's /Annots array
        let page = self.get_mut(page_id)?;
        if let Object::Dictionary(dict) = page {
            let annots = dict
                .entry(Name::annots())
                .or_insert_with(|| Object::Array(Vec::new()));
            if let Object::Array(arr) = annots {
                arr.push(Object::Reference(annot_id));
            }
        }

        Ok(annot_id)
    }

    /// Delete an annotation from a page.
    pub fn delete_annotation(
        &mut self,
        page_index: usize,
        annot_id: ObjectId,
    ) -> Result<(), EditError> {
        let count = self.page_count();
        if page_index >= count {
            return Err(EditError::PageOutOfRange {
                index: page_index,
                count,
            });
        }

        let page_id = self.page_ids()[page_index];
        let page = self.get_mut(page_id)?;
        if let Object::Dictionary(dict) = page {
            if let Some(Object::Array(arr)) = dict.get_mut(&Name::annots()) {
                arr.retain(|obj| {
                    if let Object::Reference(id) = obj {
                        *id != annot_id
                    } else {
                        true
                    }
                });
            }
        }

        self.delete_object(annot_id);
        Ok(())
    }

    /// Update an existing annotation.
    ///
    /// After applying changes, the appearance stream (/AP /N) is regenerated
    /// so viewers display the updated annotation correctly (upstream:
    /// `CPDFSDK_Widget::ResetAppearance()`).
    pub fn update_annotation(
        &mut self,
        annot_id: ObjectId,
        updates: AnnotationUpdates,
    ) -> Result<(), EditError> {
        // Apply updates to the annotation dict.
        {
            let annot = self.get_mut(annot_id)?;
            let dict = annot
                .as_dict_mut()
                .ok_or(EditError::AnnotationNotFound(annot_id))?;

            if let Some(text) = &updates.contents {
                dict.insert(
                    Name::contents(),
                    Object::String(rpdfium_core::PdfString::from_bytes(
                        text.as_bytes().to_vec(),
                    )),
                );
            }

            if let Some(color) = &updates.color {
                let color_arr: Vec<Object> =
                    color.iter().map(|&c| Object::Real(c as f64)).collect();
                dict.insert(Name::c(), Object::Array(color_arr));
            }

            if let Some(flags) = &updates.flags {
                dict.insert(Name::f(), Object::Integer(flags.bits() as i64));
            }

            if let Some(rect) = &updates.rect {
                dict.insert(
                    Name::rect(),
                    Object::Array(vec![
                        Object::Real(rect[0] as f64),
                        Object::Real(rect[1] as f64),
                        Object::Real(rect[2] as f64),
                        Object::Real(rect[3] as f64),
                    ]),
                );
            }

            if let Some(open) = updates.open {
                dict.insert(Name::open(), Object::Boolean(open));
            }

            if let Some(ref subject) = updates.subject {
                dict.insert(
                    Name::subj(),
                    Object::String(rpdfium_core::PdfString::from_bytes(
                        subject.as_bytes().to_vec(),
                    )),
                );
            }

            if let Some(ref author) = updates.author {
                dict.insert(
                    Name::t(),
                    Object::String(rpdfium_core::PdfString::from_bytes(
                        author.as_bytes().to_vec(),
                    )),
                );
            }

            if let Some(width) = updates.border_width {
                // Write /BS << /W <width> >> border-style dict.
                let mut bs_dict = HashMap::new();
                bs_dict.insert(Name::from_bytes(b"W".to_vec()), Object::Real(width as f64));
                dict.insert(Name::bs(), Object::Dictionary(bs_dict));
            }

            // Full border triple — /Border [h_rad v_rad width]
            if let Some((h, v, w)) = updates.border_style {
                dict.insert(
                    Name::border(),
                    Object::Array(vec![
                        Object::Real(h as f64),
                        Object::Real(v as f64),
                        Object::Real(w as f64),
                    ]),
                );
            }

            // RGBA color → 3-component /C array (alpha not stored in PDF /C)
            if let Some((r, g, b, _a)) = updates.color_rgba {
                let to_f = |byte: u8| Object::Real(byte as f64 / 255.0);
                dict.insert(Name::c(), Object::Array(vec![to_f(r), to_f(g), to_f(b)]));
            }

            // Attachment (quad) points → flat /QuadPoints array
            if let Some(ref groups) = updates.attachment_points {
                let flat: Vec<Object> = groups
                    .iter()
                    .flat_map(|g| g.iter().map(|&f| Object::Real(f as f64)))
                    .collect();
                dict.insert(Name::quad_points(), Object::Array(flat));
            }

            // Ink strokes → /InkList array-of-arrays
            if let Some(ref strokes) = updates.ink_list {
                let outer: Vec<Object> = strokes
                    .iter()
                    .map(|stroke| {
                        Object::Array(stroke.iter().map(|&f| Object::Real(f as f64)).collect())
                    })
                    .collect();
                dict.insert(Name::ink_list(), Object::Array(outer));
            }

            // Arbitrary string key-value
            if let Some((ref key, ref value)) = updates.extra_string {
                dict.insert(
                    Name::from_bytes(key.as_bytes().to_vec()),
                    Object::String(rpdfium_core::PdfString::from_bytes(
                        value.as_bytes().to_vec(),
                    )),
                );
            }

            // Polygon/PolyLine vertices → flat /Vertices array
            if let Some(ref verts) = updates.vertices {
                let flat: Vec<Object> = verts
                    .iter()
                    .flat_map(|v| [Object::Real(v[0] as f64), Object::Real(v[1] as f64)])
                    .collect();
                dict.insert(Name::vertices(), Object::Array(flat));
            }

            // URI action → /A << /S /URI /URI (uri_string) >>
            if let Some(ref uri) = updates.uri_action {
                let mut action_dict = HashMap::new();
                action_dict.insert(Name::s(), Object::Name(Name::uri()));
                action_dict.insert(
                    Name::uri(),
                    Object::String(rpdfium_core::PdfString::from_bytes(uri.as_bytes().to_vec())),
                );
                dict.insert(Name::a(), Object::Dictionary(action_dict));
            }
        }

        // G-R5: Regenerate appearance stream from updated dict.
        regenerate_annotation_ap(self, annot_id)?;

        Ok(())
    }

    /// Append a page object to an annotation's AP object list.
    ///
    /// The object is stored in memory keyed by `annot_id`.  Call
    /// [`update_annotation_ap()`](Self::update_annotation_ap) afterwards to
    /// regenerate the annotation's `/AP /N` stream from the accumulated list.
    ///
    /// Corresponds to `FPDFAnnot_AppendObject()`.
    pub fn append_annotation_object(
        &mut self,
        annot_id: ObjectId,
        object: PageObject,
    ) -> Result<(), EditError> {
        self.ap_objects.entry(annot_id).or_default().push(object);
        Ok(())
    }

    /// Upstream-aligned alias for [`append_annotation_object()`](Self::append_annotation_object).
    ///
    /// Corresponds to `FPDFAnnot_AppendObject()`.
    #[inline]
    pub fn annot_append_object(
        &mut self,
        annot_id: ObjectId,
        object: PageObject,
    ) -> Result<(), EditError> {
        self.append_annotation_object(annot_id, object)
    }

    /// Deprecated: use [`annot_append_object()`](Self::annot_append_object) — matches upstream `FPDFAnnot_AppendObject`.
    #[deprecated(note = "use `annot_append_object()` — matches upstream `FPDFAnnot_AppendObject`")]
    #[inline]
    pub fn append_object(
        &mut self,
        annot_id: ObjectId,
        object: PageObject,
    ) -> Result<(), EditError> {
        self.append_annotation_object(annot_id, object)
    }

    /// Return the number of objects in an annotation's AP object list.
    ///
    /// Returns `0` if no objects have been appended to `annot_id`.
    ///
    /// Corresponds to `FPDFAnnot_GetObjectCount()`.
    pub fn annotation_object_count(&self, annot_id: ObjectId) -> usize {
        self.ap_objects.get(&annot_id).map_or(0, Vec::len)
    }

    /// Non-upstream convenience alias for [`annotation_object_count()`](Self::annotation_object_count).
    ///
    /// Prefer [`annot_get_object_count()`](Self::annot_get_object_count), which matches the
    /// upstream `FPDFAnnot_GetObjectCount` name exactly.
    #[deprecated(
        note = "use `annot_get_object_count()` — matches upstream `FPDFAnnot_GetObjectCount`"
    )]
    #[inline]
    pub fn count_annotation_objects(&self, annot_id: ObjectId) -> usize {
        self.annotation_object_count(annot_id)
    }

    /// Upstream-aligned alias for [`annotation_object_count()`](Self::annotation_object_count).
    ///
    /// Corresponds to `FPDFAnnot_GetObjectCount()`.
    #[inline]
    pub fn annot_get_object_count(&self, annot_id: ObjectId) -> usize {
        self.annotation_object_count(annot_id)
    }

    /// Deprecated: use [`annot_get_object_count()`](Self::annot_get_object_count) — matches upstream `FPDFAnnot_GetObjectCount`.
    #[deprecated(
        note = "use `annot_get_object_count()` — matches upstream `FPDFAnnot_GetObjectCount`"
    )]
    #[inline]
    pub fn get_object_count(&self, annot_id: ObjectId) -> usize {
        self.annotation_object_count(annot_id)
    }

    /// Return a reference to the object at `index` in an annotation's AP object list.
    ///
    /// Returns `None` if `annot_id` has no objects or `index` is out of bounds.
    ///
    /// Corresponds to `FPDFAnnot_GetObject()`.
    pub fn annotation_object_at(&self, annot_id: ObjectId, index: usize) -> Option<&PageObject> {
        self.ap_objects.get(&annot_id)?.get(index)
    }

    /// Non-upstream convenience alias for [`annotation_object_at()`](Self::annotation_object_at).
    ///
    /// Prefer [`get_object()`](Self::get_object), which matches the upstream
    /// `FPDFAnnot_GetObject` name exactly.
    #[deprecated(note = "use `get_object()` — matches upstream FPDFAnnot_GetObject")]
    #[inline]
    pub fn get_annotation_object(&self, annot_id: ObjectId, index: usize) -> Option<&PageObject> {
        self.annotation_object_at(annot_id, index)
    }

    /// Deprecated entry point for `FPDFAnnot_GetObject`.
    ///
    /// The exact T2 alias `get_object` cannot live on `EditDocument` alongside
    /// `FPDFPage_GetObject` (same name, same struct).  Use the context type
    /// instead:
    ///
    /// ```text
    /// doc.annot_objects(annot_id).get_object(index)
    /// ```
    ///
    /// The context type ([`AnnotObjectCtx`](crate::object_ctx::AnnotObjectCtx))
    /// provides the correctly-namespaced `get_object` alias.
    #[deprecated(note = "use `doc.annot_objects(annot_id).get_object(index)` — \
                namespaced via AnnotObjectCtx to avoid collision with FPDFPage_GetObject")]
    #[inline]
    pub fn get_object(&self, annot_id: ObjectId, index: usize) -> Option<&PageObject> {
        self.annotation_object_at(annot_id, index)
    }

    /// Return a mutable reference to the object at `index` in an annotation's AP object list.
    ///
    /// Returns `None` if `annot_id` has no objects or `index` is out of bounds.
    pub fn annotation_object_at_mut(
        &mut self,
        annot_id: ObjectId,
        index: usize,
    ) -> Option<&mut PageObject> {
        self.ap_objects.get_mut(&annot_id)?.get_mut(index)
    }

    /// Non-upstream convenience alias — use [`annotation_object_at_mut()`](Self::annotation_object_at_mut).
    ///
    /// There is no upstream `FPDFAnnot_GetObjectMut`; mutable access is
    /// a Rust-specific addition.
    #[deprecated(note = "use `annotation_object_at_mut()` — no exact upstream counterpart")]
    #[inline]
    pub fn get_annotation_object_mut(
        &mut self,
        annot_id: ObjectId,
        index: usize,
    ) -> Option<&mut PageObject> {
        self.annotation_object_at_mut(annot_id, index)
    }

    /// Remove the object at `index` from an annotation's AP object list.
    ///
    /// Returns an error if `annot_id` has no AP objects or `index` is out of
    /// bounds.
    ///
    /// Corresponds to `FPDFAnnot_RemoveObject()`.
    pub fn remove_annotation_object(
        &mut self,
        annot_id: ObjectId,
        index: usize,
    ) -> Result<(), EditError> {
        let list = self
            .ap_objects
            .get_mut(&annot_id)
            .ok_or_else(|| EditError::NotSupported("annotation has no AP objects".into()))?;
        if index >= list.len() {
            return Err(EditError::NotSupported("index out of bounds".into()));
        }
        list.remove(index);
        Ok(())
    }

    /// Deprecated entry point for `FPDFAnnot_RemoveObject`.
    ///
    /// The exact T2 alias `remove_object` cannot live on `EditDocument`
    /// alongside `FPDFPage_RemoveObject` (same name, same struct).  Use the
    /// context type instead:
    ///
    /// ```text
    /// doc.annot_objects_mut(annot_id).remove_object(index)
    /// ```
    ///
    /// The context type ([`AnnotObjectCtxMut`](crate::object_ctx::AnnotObjectCtxMut))
    /// provides the correctly-namespaced `remove_object` alias.
    #[deprecated(note = "use `doc.annot_objects_mut(annot_id).remove_object(index)` — \
                namespaced via AnnotObjectCtxMut to avoid collision with FPDFPage_RemoveObject")]
    #[inline]
    pub fn remove_object(&mut self, annot_id: ObjectId, index: usize) -> Result<(), EditError> {
        self.remove_annotation_object(annot_id, index)
    }

    /// Regenerate the annotation's `/AP /N` stream from the stored object list.
    ///
    /// Reads the object list stored via [`append_annotation_object()`](Self::append_annotation_object),
    /// generates a PDF content stream, and writes it as a Form XObject into
    /// the annotation's `/AP /N` entry.  The `/BBox` of the Form XObject is
    /// derived from the annotation's current `/Rect`.
    ///
    /// Returns an error if no objects have been appended to `annot_id`.
    ///
    /// Corresponds to `FPDFAnnot_UpdateObject()`.
    pub fn update_annotation_ap(&mut self, annot_id: ObjectId) -> Result<(), EditError> {
        // Clone the object list to avoid holding an immutable borrow while we
        // need to call `add_object()` (which requires &mut self).
        let objects = self
            .ap_objects
            .get(&annot_id)
            .ok_or_else(|| EditError::NotSupported("annotation has no AP objects".into()))?
            .clone();

        // Generate content stream and collect resource references.
        let mut resources = ResourceCollector::new();
        let content = generate_content_stream(&objects, &mut resources);

        // Read the annotation's /Rect for the Form XObject /BBox.
        let rect = {
            let annot = self.resolve(annot_id)?;
            let dict = annot
                .as_dict()
                .ok_or(EditError::AnnotationNotFound(annot_id))?;
            dict.get(&Name::rect())
                .and_then(|o| o.as_array())
                .map(|arr| {
                    let get = |i: usize| arr.get(i).and_then(|v| v.as_f64()).unwrap_or(0.0) as f32;
                    [get(0), get(1), get(2), get(3)]
                })
                .unwrap_or([0.0; 4])
        };

        let w = (rect[2] - rect[0]).abs();
        let h = (rect[3] - rect[1]).abs();

        // Build the Form XObject stream dict.
        let mut ap_stream_dict = HashMap::new();
        ap_stream_dict.insert(
            Name::r#type(),
            Object::Name(Name::from_bytes(b"XObject".to_vec())),
        );
        ap_stream_dict.insert(
            Name::subtype(),
            Object::Name(Name::from_bytes(b"Form".to_vec())),
        );
        ap_stream_dict.insert(
            Name::from_bytes(b"BBox".to_vec()),
            Object::Array(vec![
                Object::Real(0.0),
                Object::Real(0.0),
                Object::Real(w as f64),
                Object::Real(h as f64),
            ]),
        );

        // Attach resources dict only if non-empty (e.g. fonts for text objects).
        let res_obj = build_resource_dict(&resources);
        let has_resources = matches!(&res_obj, Object::Dictionary(d) if !d.is_empty());
        if has_resources {
            ap_stream_dict.insert(Name::from_bytes(b"Resources".to_vec()), res_obj);
        }

        let ap_stream = Object::Stream {
            dict: ap_stream_dict,
            data: StreamData::Decoded { data: content },
        };
        let ap_id = self.add_object(ap_stream);

        // Write /AP /N reference into the annotation dict.
        // Preserve any existing /D (Down) or /R (Rollover) streams — only /N is regenerated.
        let annot = self.get_mut(annot_id)?;
        if let Object::Dictionary(dict) = annot {
            let ap_key = Name::from_bytes(b"AP".to_vec());
            let n_key = Name::from_bytes(b"N".to_vec());
            match dict.get_mut(&ap_key) {
                Some(Object::Dictionary(existing)) => {
                    existing.insert(n_key, Object::Reference(ap_id));
                }
                _ => {
                    let mut ap_dict = HashMap::new();
                    ap_dict.insert(n_key, Object::Reference(ap_id));
                    dict.insert(ap_key, Object::Dictionary(ap_dict));
                }
            }
        }

        Ok(())
    }

    /// Upstream-aligned alias for [`update_annotation_ap()`](Self::update_annotation_ap).
    ///
    /// Corresponds to `FPDFAnnot_UpdateObject()`.
    #[inline]
    pub fn annot_update_object(&mut self, annot_id: ObjectId) -> Result<(), EditError> {
        self.update_annotation_ap(annot_id)
    }

    /// Deprecated: use [`annot_update_object()`](Self::annot_update_object) — matches upstream `FPDFAnnot_UpdateObject`.
    #[deprecated(note = "use `annot_update_object()` — matches upstream `FPDFAnnot_UpdateObject`")]
    #[inline]
    pub fn update_object(&mut self, annot_id: ObjectId) -> Result<(), EditError> {
        self.update_annotation_ap(annot_id)
    }

    /// Add an embedded file attachment to a file-attachment annotation.
    ///
    /// **ADR-017 stub** — file-attachment annotation mutation is not yet
    /// implemented. This stub is provided for API completeness per ADR-017.
    ///
    /// Corresponds to `FPDFAnnot_AddFileAttachment()`.
    pub fn add_annotation_file_attachment(
        &mut self,
        _annot_id: rpdfium_parser::ObjectId,
        _name: &str,
    ) -> Result<(), crate::error::EditError> {
        Err(crate::error::EditError::NotSupported(
            "add_annotation_file_attachment: file-attachment annotation mutation not yet implemented"
                .into(),
        ))
    }

    /// Upstream-aligned alias for [`add_annotation_file_attachment()`](Self::add_annotation_file_attachment).
    ///
    /// Corresponds to `FPDFAnnot_AddFileAttachment`.
    #[inline]
    pub fn annot_add_file_attachment(
        &mut self,
        annot_id: rpdfium_parser::ObjectId,
        name: &str,
    ) -> Result<(), crate::error::EditError> {
        self.add_annotation_file_attachment(annot_id, name)
    }

    /// Non-upstream alias — use [`annot_add_file_attachment()`](Self::annot_add_file_attachment).
    #[deprecated(
        note = "use `annot_add_file_attachment()` — matches upstream `FPDFAnnot_AddFileAttachment`"
    )]
    #[inline]
    pub fn add_file_attachment(
        &mut self,
        annot_id: rpdfium_parser::ObjectId,
        name: &str,
    ) -> Result<(), crate::error::EditError> {
        self.add_annotation_file_attachment(annot_id, name)
    }

    // -----------------------------------------------------------------------
    // Appearance stream set/get  (FPDFAnnot_SetAP / FPDFAnnot_GetAP)
    // -----------------------------------------------------------------------

    /// Set the appearance stream content for the given AP mode on an annotation.
    ///
    /// Writes `content` as a decoded `/AP /<mode>` stream on the annotation
    /// dictionary at `annot_id`.  Pass an empty slice to clear the stream for
    /// that mode.
    ///
    /// Corresponds to `FPDFAnnot_SetAP`.
    pub fn annotation_set_ap(
        &mut self,
        annot_id: ObjectId,
        mode: rpdfium_doc::AppearanceMode,
        content: &[u8],
    ) -> Result<(), EditError> {
        let mode_key = ap_mode_name(mode);

        // Build a Form XObject stream for the appearance.
        let ap_stream = Object::Stream {
            dict: HashMap::new(),
            data: StreamData::Decoded {
                data: content.to_vec(),
            },
        };
        let ap_id = self.add_object(ap_stream);

        // Write /AP /<mode> into the annotation dict.
        let ap_key = Name::ap();
        let n_key = Name::from_bytes(mode_key.to_vec());
        let annot = self.get_mut(annot_id)?;
        if let Object::Dictionary(dict) = annot {
            match dict.get_mut(&ap_key) {
                Some(Object::Dictionary(existing)) => {
                    existing.insert(n_key, Object::Reference(ap_id));
                }
                _ => {
                    let mut ap_dict = HashMap::new();
                    ap_dict.insert(n_key, Object::Reference(ap_id));
                    dict.insert(ap_key, Object::Dictionary(ap_dict));
                }
            }
        }
        Ok(())
    }

    /// Upstream-aligned alias for [`annotation_set_ap()`](Self::annotation_set_ap).
    ///
    /// Corresponds to `FPDFAnnot_SetAP`.
    #[inline]
    pub fn annot_set_ap(
        &mut self,
        annot_id: ObjectId,
        mode: rpdfium_doc::AppearanceMode,
        content: &[u8],
    ) -> Result<(), EditError> {
        self.annotation_set_ap(annot_id, mode, content)
    }

    /// Non-upstream alias — use [`annot_set_ap()`](Self::annot_set_ap).
    #[deprecated(note = "use `annot_set_ap()` — matches upstream `FPDFAnnot_SetAP`")]
    #[inline]
    pub fn set_ap(
        &mut self,
        annot_id: ObjectId,
        mode: rpdfium_doc::AppearanceMode,
        content: &[u8],
    ) -> Result<(), EditError> {
        self.annotation_set_ap(annot_id, mode, content)
    }

    /// Return the decoded appearance stream bytes for the given AP mode, or
    /// `None` if no AP stream is set for that mode.
    ///
    /// Corresponds to `FPDFAnnot_GetAP`.
    pub fn annotation_get_ap(
        &self,
        annot_id: ObjectId,
        mode: rpdfium_doc::AppearanceMode,
    ) -> Result<Option<Vec<u8>>, EditError> {
        let mode_key = ap_mode_name(mode);
        let ap_key = Name::ap();
        let n_key = Name::from_bytes(mode_key.to_vec());

        // Extract the AP stream reference in a nested scope to end borrows on `self`
        // before we call `resolve` or `decode_stream` a second time.
        let ap_ref: ObjectId = {
            let annot = self.resolve(annot_id)?;
            let dict = annot
                .as_dict()
                .ok_or(EditError::AnnotationNotFound(annot_id))?;
            let ap_dict = match dict.get(&ap_key) {
                Some(Object::Dictionary(d)) => d,
                _ => return Ok(None),
            };
            match ap_dict.get(&n_key) {
                Some(Object::Reference(id)) => *id,
                _ => return Ok(None),
            }
        }; // borrows on `self` end here

        let ap_obj = self.resolve(ap_ref)?.clone();
        match &ap_obj {
            Object::Stream { data, .. } => match data {
                StreamData::Decoded { data } => Ok(Some(data.clone())),
                StreamData::Raw { .. } => self.decode_stream(&ap_obj).map(Some),
            },
            _ => Ok(None),
        }
    }

    /// Upstream-aligned alias for [`annotation_get_ap()`](Self::annotation_get_ap).
    ///
    /// Corresponds to `FPDFAnnot_GetAP`.
    #[inline]
    pub fn annot_get_ap(
        &self,
        annot_id: ObjectId,
        mode: rpdfium_doc::AppearanceMode,
    ) -> Result<Option<Vec<u8>>, EditError> {
        self.annotation_get_ap(annot_id, mode)
    }

    /// Non-upstream alias — use [`annot_get_ap()`](Self::annot_get_ap).
    #[deprecated(note = "use `annot_get_ap()` — matches upstream `FPDFAnnot_GetAP`")]
    #[inline]
    pub fn get_ap(
        &self,
        annot_id: ObjectId,
        mode: rpdfium_doc::AppearanceMode,
    ) -> Result<Option<Vec<u8>>, EditError> {
        self.annotation_get_ap(annot_id, mode)
    }
}

/// Map AppearanceMode to the PDF /AP sub-key byte string (b"N", b"R", or b"D").
fn ap_mode_name(mode: rpdfium_doc::AppearanceMode) -> &'static [u8] {
    match mode {
        rpdfium_doc::AppearanceMode::Normal => b"N",
        rpdfium_doc::AppearanceMode::Rollover => b"R",
        rpdfium_doc::AppearanceMode::Down => b"D",
    }
}

/// Map annotation type to PDF name.
fn annotation_type_name(ty: &AnnotationType) -> &'static [u8] {
    match ty {
        AnnotationType::Text => b"Text",
        AnnotationType::Link => b"Link",
        AnnotationType::FreeText => b"FreeText",
        AnnotationType::Line => b"Line",
        AnnotationType::Square => b"Square",
        AnnotationType::Circle => b"Circle",
        AnnotationType::Polygon => b"Polygon",
        AnnotationType::PolyLine => b"PolyLine",
        AnnotationType::Highlight => b"Highlight",
        AnnotationType::Underline => b"Underline",
        AnnotationType::Squiggly => b"Squiggly",
        AnnotationType::StrikeOut => b"StrikeOut",
        AnnotationType::Stamp => b"Stamp",
        AnnotationType::Caret => b"Caret",
        AnnotationType::Ink => b"Ink",
        AnnotationType::Popup => b"Popup",
        AnnotationType::FileAttachment => b"FileAttachment",
        AnnotationType::Sound => b"Sound",
        AnnotationType::Movie => b"Movie",
        AnnotationType::Widget => b"Widget",
        AnnotationType::Screen => b"Screen",
        AnnotationType::PrinterMark => b"PrinterMark",
        AnnotationType::TrapNet => b"TrapNet",
        AnnotationType::Watermark => b"Watermark",
        AnnotationType::ThreeD => b"3D",
        AnnotationType::RichMedia => b"RichMedia",
        AnnotationType::XFAWidget => b"XFAWidget",
        AnnotationType::Redact => b"Redact",
        AnnotationType::Other => b"Unknown",
    }
}

/// Regenerate the AP (appearance) stream for an annotation after updates.
///
/// Reads the current annotation dict, builds a minimal `Annotation`, calls
/// `generate_annotation_appearance()`, and replaces /AP /N in the dict.
fn regenerate_annotation_ap(doc: &mut EditDocument, annot_id: ObjectId) -> Result<(), EditError> {
    // Read current annotation fields (immutable borrow).
    let (subtype, rect, contents, color, flags) = {
        let annot = doc.resolve(annot_id)?;
        let dict = annot
            .as_dict()
            .ok_or(EditError::AnnotationNotFound(annot_id))?;

        let subtype = dict
            .get(&Name::subtype())
            .and_then(|o| o.as_name())
            .map(|n| name_to_annotation_type(n.as_bytes()))
            .unwrap_or(AnnotationType::Other);

        let rect = dict
            .get(&Name::rect())
            .and_then(|o| o.as_array())
            .map(|arr| {
                let get = |i: usize| arr.get(i).and_then(|v| v.as_f64()).unwrap_or(0.0) as f32;
                [get(0), get(1), get(2), get(3)]
            })
            .unwrap_or([0.0; 4]);

        let contents = dict
            .get(&Name::contents())
            .and_then(|o| o.as_string())
            .map(|s| String::from_utf8_lossy(s.as_bytes()).into_owned());

        let color = dict.get(&Name::c()).and_then(|o| o.as_array()).map(|arr| {
            arr.iter()
                .filter_map(|v| v.as_f64().map(|f| f as f32))
                .collect::<Vec<f32>>()
        });

        let flags_val = dict.get(&Name::f()).and_then(|o| o.as_i64()).unwrap_or(0);
        let flags = AnnotationFlags::from_bits(flags_val as u32);

        (subtype, rect, contents, color, flags)
    };

    // Build temporary Annotation for AP generation.
    let temp_annot = Annotation {
        subtype,
        rect,
        contents,
        flags,
        color,
        name: None,
        appearance: None,
        border: None,
        action: None,
        destination: None,
        subtype_data: 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,
    };

    if let Some(ap_bytes) = generate_annotation_appearance(&temp_annot) {
        let w = (rect[2] - rect[0]).abs();
        let h = (rect[3] - rect[1]).abs();
        let mut ap_stream_dict = HashMap::new();
        ap_stream_dict.insert(
            Name::r#type(),
            Object::Name(Name::from_bytes(b"XObject".to_vec())),
        );
        ap_stream_dict.insert(
            Name::subtype(),
            Object::Name(Name::from_bytes(b"Form".to_vec())),
        );
        ap_stream_dict.insert(
            Name::from_bytes(b"BBox".to_vec()),
            Object::Array(vec![
                Object::Real(0.0),
                Object::Real(0.0),
                Object::Real(w as f64),
                Object::Real(h as f64),
            ]),
        );
        let ap_stream = Object::Stream {
            dict: ap_stream_dict,
            data: StreamData::Decoded { data: ap_bytes },
        };
        let ap_id = doc.add_object(ap_stream);

        // Update /AP /N in the annotation dict, preserving /D and /R if present.
        let annot = doc.get_mut(annot_id)?;
        if let Object::Dictionary(dict) = annot {
            let ap_key = Name::from_bytes(b"AP".to_vec());
            let n_key = Name::from_bytes(b"N".to_vec());
            match dict.get_mut(&ap_key) {
                Some(Object::Dictionary(existing)) => {
                    existing.insert(n_key, Object::Reference(ap_id));
                }
                _ => {
                    let mut ap_dict = HashMap::new();
                    ap_dict.insert(n_key, Object::Reference(ap_id));
                    dict.insert(ap_key, Object::Dictionary(ap_dict));
                }
            }
        }
    }

    Ok(())
}

/// Map a PDF annotation subtype name back to `AnnotationType`.
fn name_to_annotation_type(name: &[u8]) -> AnnotationType {
    match name {
        b"Text" => AnnotationType::Text,
        b"Link" => AnnotationType::Link,
        b"FreeText" => AnnotationType::FreeText,
        b"Line" => AnnotationType::Line,
        b"Square" => AnnotationType::Square,
        b"Circle" => AnnotationType::Circle,
        b"Polygon" => AnnotationType::Polygon,
        b"PolyLine" => AnnotationType::PolyLine,
        b"Highlight" => AnnotationType::Highlight,
        b"Underline" => AnnotationType::Underline,
        b"Squiggly" => AnnotationType::Squiggly,
        b"StrikeOut" => AnnotationType::StrikeOut,
        b"Stamp" => AnnotationType::Stamp,
        b"Caret" => AnnotationType::Caret,
        b"Ink" => AnnotationType::Ink,
        b"Popup" => AnnotationType::Popup,
        b"FileAttachment" => AnnotationType::FileAttachment,
        b"Sound" => AnnotationType::Sound,
        b"Movie" => AnnotationType::Movie,
        b"Widget" => AnnotationType::Widget,
        b"Screen" => AnnotationType::Screen,
        b"PrinterMark" => AnnotationType::PrinterMark,
        b"TrapNet" => AnnotationType::TrapNet,
        b"Watermark" => AnnotationType::Watermark,
        b"3D" => AnnotationType::ThreeD,
        b"RichMedia" => AnnotationType::RichMedia,
        b"XFAWidget" => AnnotationType::XFAWidget,
        b"Redact" => AnnotationType::Redact,
        _ => AnnotationType::Other,
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use rpdfium_core::Rect;

    #[test]
    fn test_builder_creates_spec() {
        let spec = AnnotationBuilder::new(AnnotationType::Highlight, [10.0, 20.0, 100.0, 50.0])
            .contents("Test annotation")
            .color(vec![1.0, 0.0, 0.0])
            .build();

        assert!(matches!(spec.subtype, AnnotationType::Highlight));
        assert_eq!(spec.rect, [10.0, 20.0, 100.0, 50.0]);
        assert_eq!(spec.contents.as_deref(), Some("Test annotation"));
        assert_eq!(spec.color.as_ref().map(|c| c.len()), Some(3));
    }

    #[test]
    fn test_add_annotation_to_page() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0])
            .contents("Hello")
            .build();

        let annot_id = doc.add_annotation(0, spec).unwrap();

        // Verify annotation exists
        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        assert!(dict.contains_key(&Name::subtype()));
        assert!(dict.contains_key(&Name::rect()));

        // Verify it's in the page's /Annots
        let page_id = doc.page_id(0).unwrap();
        let page = doc.resolve(page_id).unwrap();
        let pdict = page.as_dict().unwrap();
        let annots = pdict.get(&Name::annots()).unwrap().as_array().unwrap();
        assert_eq!(annots.len(), 1);
    }

    #[test]
    fn test_add_annotation_out_of_range() {
        let mut doc = EditDocument::new_blank();
        let spec = AnnotationBuilder::new(AnnotationType::Text, [0.0; 4]).build();
        let result = doc.add_annotation(0, spec);
        assert!(result.is_err());
    }

    #[test]
    fn test_delete_annotation() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        doc.delete_annotation(0, annot_id).unwrap();

        // Annotation should no longer be resolvable
        assert!(doc.resolve(annot_id).is_err());

        // Page's /Annots should be empty
        let page_id = doc.page_id(0).unwrap();
        let page = doc.resolve(page_id).unwrap();
        let pdict = page.as_dict().unwrap();
        let annots = pdict.get(&Name::annots()).unwrap().as_array().unwrap();
        assert_eq!(annots.len(), 0);
    }

    #[test]
    fn test_update_annotation_contents() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0])
            .contents("Original")
            .build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            contents: Some("Updated".to_string()),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let contents = dict
            .get(&Name::contents())
            .and_then(|o| o.as_string())
            .unwrap();
        assert_eq!(contents.as_bytes(), b"Updated");
    }

    #[test]
    fn test_update_annotation_rect() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            rect: Some([0.0, 0.0, 100.0, 100.0]),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let rect = dict.get(&Name::rect()).unwrap().as_array().unwrap();
        assert_eq!(rect[2].as_f64(), Some(100.0));
    }

    #[test]
    fn test_multiple_annotations_on_page() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        for i in 0..5 {
            let r = i as f32 * 10.0;
            let spec =
                AnnotationBuilder::new(AnnotationType::Text, [r, r, r + 30.0, r + 30.0]).build();
            doc.add_annotation(0, spec).unwrap();
        }

        let page_id = doc.page_id(0).unwrap();
        let page = doc.resolve(page_id).unwrap();
        let pdict = page.as_dict().unwrap();
        let annots = pdict.get(&Name::annots()).unwrap().as_array().unwrap();
        assert_eq!(annots.len(), 5);
    }

    #[test]
    fn test_annotation_type_names() {
        assert_eq!(
            annotation_type_name(&AnnotationType::Highlight),
            b"Highlight"
        );
        assert_eq!(annotation_type_name(&AnnotationType::Link), b"Link");
        assert_eq!(annotation_type_name(&AnnotationType::ThreeD), b"3D");
    }

    // ------------------------------------------------------------------
    // Fix E: AnnotationUpdates new fields — subject, author, border_width
    // ------------------------------------------------------------------

    #[test]
    fn test_update_annotation_subject() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            subject: Some("Important Note".to_string()),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let subj = dict.get(&Name::subj()).and_then(|o| o.as_string()).unwrap();
        assert_eq!(subj.as_bytes(), b"Important Note");
    }

    #[test]
    fn test_update_annotation_author() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            author: Some("Jane Doe".to_string()),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let author = dict.get(&Name::t()).and_then(|o| o.as_string()).unwrap();
        assert_eq!(author.as_bytes(), b"Jane Doe");
    }

    #[test]
    fn test_update_annotation_border_width() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            border_width: Some(2.5),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let bs_dict = dict.get(&Name::bs()).and_then(|o| o.as_dict()).unwrap();
        let w = bs_dict
            .get(&Name::from_bytes(b"W".to_vec()))
            .and_then(|o| o.as_f64())
            .unwrap();
        assert!((w - 2.5).abs() < 0.001);
    }

    // ------------------------------------------------------------------
    // New AnnotationUpdates fields: border_style, color_rgba,
    // attachment_points, ink_list, extra_string
    // ------------------------------------------------------------------

    #[test]
    fn test_update_annotation_border_style_writes_border_array() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec =
            AnnotationBuilder::new(AnnotationType::Square, [10.0, 10.0, 100.0, 100.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            border_style: Some((5.0, 10.0, 2.0)), // h_rad=5, v_rad=10, width=2
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let border = dict
            .get(&Name::border())
            .and_then(|o| o.as_array())
            .unwrap();
        assert_eq!(border.len(), 3);
        assert!((border[0].as_f64().unwrap() - 5.0).abs() < 0.001);
        assert!((border[1].as_f64().unwrap() - 10.0).abs() < 0.001);
        assert!((border[2].as_f64().unwrap() - 2.0).abs() < 0.001);
    }

    #[test]
    fn test_update_annotation_color_rgba_writes_c_array() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        // Red: (255, 0, 0, 255)
        let updates = AnnotationUpdates {
            color_rgba: Some((255, 0, 0, 255)),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let c = dict.get(&Name::c()).and_then(|o| o.as_array()).unwrap();
        assert_eq!(c.len(), 3);
        assert!((c[0].as_f64().unwrap() - 1.0).abs() < 0.01); // R ≈ 1.0
        assert!((c[1].as_f64().unwrap() - 0.0).abs() < 0.01); // G ≈ 0.0
        assert!((c[2].as_f64().unwrap() - 0.0).abs() < 0.01); // B ≈ 0.0
    }

    #[test]
    fn test_update_annotation_attachment_points_writes_quad_points() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec =
            AnnotationBuilder::new(AnnotationType::Highlight, [10.0, 10.0, 200.0, 30.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            attachment_points: Some(vec![[10.0, 10.0, 200.0, 10.0, 200.0, 30.0, 10.0, 30.0]]),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let qp = dict
            .get(&Name::quad_points())
            .and_then(|o| o.as_array())
            .unwrap();
        assert_eq!(qp.len(), 8);
        assert!((qp[0].as_f64().unwrap() - 10.0).abs() < 0.001);
        assert!((qp[2].as_f64().unwrap() - 200.0).abs() < 0.001);
    }

    #[test]
    fn test_update_annotation_ink_list_writes_ink_list() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec = AnnotationBuilder::new(AnnotationType::Ink, [0.0, 0.0, 200.0, 200.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            ink_list: Some(vec![
                vec![10.0, 10.0, 20.0, 30.0, 40.0, 50.0], // stroke 0
                vec![100.0, 100.0, 110.0, 120.0],         // stroke 1
            ]),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let ink = dict
            .get(&Name::ink_list())
            .and_then(|o| o.as_array())
            .unwrap();
        assert_eq!(ink.len(), 2); // 2 strokes
        let stroke0 = ink[0].as_array().unwrap();
        assert_eq!(stroke0.len(), 6);
        assert!((stroke0[0].as_f64().unwrap() - 10.0).abs() < 0.001);
        let stroke1 = ink[1].as_array().unwrap();
        assert_eq!(stroke1.len(), 4);
    }

    #[test]
    fn test_update_annotation_extra_string_writes_arbitrary_key() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec = AnnotationBuilder::new(AnnotationType::Text, [10.0, 10.0, 50.0, 50.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            extra_string: Some(("RC".to_string(), "rich text content".to_string())),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let key = Name::from_bytes(b"RC".to_vec());
        let val = dict.get(&key).and_then(|o| o.as_string()).unwrap();
        assert_eq!(val.as_bytes(), b"rich text content");
    }

    // ------------------------------------------------------------------
    // AP stream object management (FPDFAnnot_AppendObject etc.)
    // ------------------------------------------------------------------

    #[test]
    fn test_ap_object_append_and_count() {
        use crate::page_object::{PageObject, PathObject, PathSegment};

        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Ink, [0.0, 0.0, 100.0, 100.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        // Initially no AP objects
        assert_eq!(doc.annotation_object_count(annot_id), 0);
        assert!(doc.annotation_object_at(annot_id, 0).is_none());

        // Append a simple path object
        let path = PathObject {
            segments: vec![
                PathSegment::MoveTo(10.0, 10.0),
                PathSegment::LineTo(90.0, 90.0),
            ],
            ..Default::default()
        };
        doc.append_annotation_object(annot_id, PageObject::Path(path))
            .unwrap();

        assert_eq!(doc.annotation_object_count(annot_id), 1);
        assert!(doc.annotation_object_at(annot_id, 0).is_some());
        assert!(doc.annotation_object_at(annot_id, 1).is_none());
    }

    #[test]
    fn test_ap_object_remove() {
        use crate::page_object::{PageObject, PathObject, PathSegment};

        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Ink, [0.0, 0.0, 100.0, 100.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let path = PathObject {
            segments: vec![PathSegment::MoveTo(0.0, 0.0)],
            ..Default::default()
        };
        doc.append_annotation_object(annot_id, PageObject::Path(path))
            .unwrap();

        assert_eq!(doc.annotation_object_count(annot_id), 1);

        // Remove it
        doc.remove_annotation_object(annot_id, 0).unwrap();
        assert_eq!(doc.annotation_object_count(annot_id), 0);

        // Remove from non-existing list returns error
        let other_id = ObjectId::new(999, 0);
        assert!(doc.remove_annotation_object(other_id, 0).is_err());
    }

    #[test]
    fn test_ap_object_update_generates_ap_stream() {
        use crate::page_object::{FillMode, PageObject, PathObject, PathSegment};
        use rpdfium_graphics::Color;

        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Ink, [10.0, 10.0, 90.0, 90.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let path = PathObject {
            segments: vec![
                PathSegment::MoveTo(10.0, 10.0),
                PathSegment::LineTo(90.0, 10.0),
                PathSegment::LineTo(90.0, 90.0),
                PathSegment::LineTo(10.0, 90.0),
                PathSegment::Close,
            ],
            fill_color: Some(Color::rgb(1.0, 0.0, 0.0)),
            stroke_color: Some(Color::rgb(0.0, 0.0, 1.0)),
            line_width: 2.0,
            fill_mode: FillMode::NonZero,
            ..Default::default()
        };
        doc.append_annotation_object(annot_id, PageObject::Path(path))
            .unwrap();

        // update_annotation_ap should succeed and write /AP /N
        doc.update_annotation_ap(annot_id).unwrap();

        // Verify the annotation dict now has /AP entry
        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        assert!(
            dict.contains_key(&Name::from_bytes(b"AP".to_vec())),
            "/AP key should be present after update_annotation_ap"
        );
        let ap_dict = dict
            .get(&Name::from_bytes(b"AP".to_vec()))
            .and_then(|o| o.as_dict())
            .unwrap();
        assert!(
            ap_dict.contains_key(&Name::from_bytes(b"N".to_vec())),
            "/AP /N key should be present"
        );
    }

    #[test]
    fn test_ap_object_update_no_objects_returns_error() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Ink, [0.0, 0.0, 100.0, 100.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        // No objects appended — should return error
        let result = doc.update_annotation_ap(annot_id);
        assert!(
            result.is_err(),
            "update_annotation_ap with no objects should return error"
        );
    }

    #[test]
    fn test_count_annotation_objects_alias() {
        use crate::page_object::{PageObject, PathObject, PathSegment};

        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));

        let spec = AnnotationBuilder::new(AnnotationType::Stamp, [0.0, 0.0, 200.0, 100.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let path = PathObject {
            segments: vec![PathSegment::MoveTo(0.0, 0.0)],
            ..Default::default()
        };
        doc.append_annotation_object(annot_id, PageObject::Path(path))
            .unwrap();

        assert_eq!(
            doc.annotation_object_count(annot_id),
            doc.annot_get_object_count(annot_id)
        );
    }

    // ------------------------------------------------------------------
    // Gap 1: AnnotationUpdates::vertices — FPDFAnnot_SetVertices
    // ------------------------------------------------------------------

    #[test]
    fn test_update_annotation_vertices_writes_vertices_array() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec =
            AnnotationBuilder::new(AnnotationType::Polygon, [0.0, 0.0, 200.0, 200.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            vertices: Some(vec![
                [10.0, 20.0],
                [100.0, 20.0],
                [100.0, 120.0],
                [10.0, 120.0],
            ]),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let verts = dict
            .get(&Name::vertices())
            .and_then(|o| o.as_array())
            .unwrap();
        // 4 points × 2 coords = 8 values
        assert_eq!(verts.len(), 8);
        assert!((verts[0].as_f64().unwrap() - 10.0).abs() < 0.001);
        assert!((verts[1].as_f64().unwrap() - 20.0).abs() < 0.001);
        assert!((verts[2].as_f64().unwrap() - 100.0).abs() < 0.001);
    }

    #[test]
    fn test_update_annotation_vertices_replaces_existing() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec =
            AnnotationBuilder::new(AnnotationType::Polygon, [0.0, 0.0, 200.0, 200.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        // First update
        let updates1 = AnnotationUpdates {
            vertices: Some(vec![[0.0, 0.0], [50.0, 0.0], [50.0, 50.0]]),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates1).unwrap();

        // Second update replaces
        let updates2 = AnnotationUpdates {
            vertices: Some(vec![[5.0, 5.0], [15.0, 5.0]]),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates2).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let verts = dict
            .get(&Name::vertices())
            .and_then(|o| o.as_array())
            .unwrap();
        // 2 points × 2 = 4 values
        assert_eq!(verts.len(), 4);
        assert!((verts[0].as_f64().unwrap() - 5.0).abs() < 0.001);
    }

    #[test]
    fn test_update_annotation_vertices_empty_clears_array() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec =
            AnnotationBuilder::new(AnnotationType::Polygon, [0.0, 0.0, 200.0, 200.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            vertices: Some(vec![]),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let verts = dict
            .get(&Name::vertices())
            .and_then(|o| o.as_array())
            .unwrap();
        assert_eq!(verts.len(), 0);
    }

    // ------------------------------------------------------------------
    // Task 2: AnnotationUpdates::uri_action — FPDFAnnot_SetURI
    // ------------------------------------------------------------------

    #[test]
    fn test_update_annotation_sets_uri_action() {
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec = AnnotationBuilder::new(AnnotationType::Link, [10.0, 10.0, 100.0, 30.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            uri_action: Some("https://example.com".to_string()),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();
        let action_dict = dict.get(&Name::a()).and_then(|o| o.as_dict()).unwrap();
        // /S entry should be the Name /URI
        let s_val = action_dict
            .get(&Name::s())
            .and_then(|o| o.as_name())
            .unwrap();
        assert_eq!(s_val.as_bytes(), b"URI");
        // /URI entry should be the string value
        let uri_val = action_dict
            .get(&Name::uri())
            .and_then(|o| o.as_string())
            .unwrap();
        assert_eq!(uri_val.as_bytes(), b"https://example.com");
    }

    #[test]
    fn test_update_annotation_uri_in_correct_dict_structure() {
        // Verify the exact dict structure: /A << /S /URI /URI (url) >>
        let mut doc = EditDocument::new_blank();
        doc.add_page(Rect::new(0.0, 0.0, 612.0, 792.0));
        let spec = AnnotationBuilder::new(AnnotationType::Widget, [0.0, 0.0, 200.0, 50.0]).build();
        let annot_id = doc.add_annotation(0, spec).unwrap();

        let updates = AnnotationUpdates {
            uri_action: Some("https://rust-lang.org/".to_string()),
            ..Default::default()
        };
        doc.update_annotation(annot_id, updates).unwrap();

        let annot = doc.resolve(annot_id).unwrap();
        let dict = annot.as_dict().unwrap();

        // /A key must exist and be a dictionary
        let action = dict.get(&Name::a()).expect("/A key missing");
        let action_dict = action.as_dict().expect("/A value is not a dictionary");

        // Must contain /S and /URI entries
        assert!(
            action_dict.contains_key(&Name::s()),
            "/S missing from action dict"
        );
        assert!(
            action_dict.contains_key(&Name::uri()),
            "/URI missing from action dict"
        );

        let s = action_dict
            .get(&Name::s())
            .and_then(|o| o.as_name())
            .unwrap();
        assert_eq!(s.as_bytes(), b"URI", "/S value should be /URI");

        let uri = action_dict
            .get(&Name::uri())
            .and_then(|o| o.as_string())
            .unwrap();
        assert_eq!(uri.as_bytes(), b"https://rust-lang.org/");
    }

    // ------------------------------------------------------------------
    // Batch 18: AnnotationUpdates::append_attachment_points
    // FPDFAnnot_AppendAttachmentPoints
    // ------------------------------------------------------------------

    #[test]
    fn test_annotation_updates_append_attachment_points() {
        let mut updates = AnnotationUpdates::default();
        updates.append_attachment_points([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]);
        updates.append_attachment_points([9.0, 10.0, 11.0, 12.0, 13.0, 14.0, 15.0, 16.0]);
        let pts = updates.attachment_points.as_ref().unwrap();
        assert_eq!(pts.len(), 2);
        assert_eq!(pts[0][0], 1.0);
        assert_eq!(pts[1][0], 9.0);
    }
}