Phase 6: annotation authoring

[billdenney]

Summary

11 new exports closing the create / mutate / delete loop for annotations.

Lifecycle	Wraps
pdf_annot_new(page, subtype, bounds = NULL)	FPDFPage_CreateAnnot (+ optional FPDFAnnot_SetRect)
pdf_annot_delete(annot)	FPDFPage_RemoveAnnot + R-side handle invalidation

Setter	Wraps
pdf_annot_set_bounds	FPDFAnnot_SetRect
pdf_annot_set_color	FPDFAnnot_SetColor(Color)
pdf_annot_set_interior_color	FPDFAnnot_SetColor(InteriorColor)
pdf_annot_set_flags	FPDFAnnot_SetFlags
pdf_annot_set_contents	FPDFAnnot_SetStringValue("Contents", …)
pdf_annot_set_title	FPDFAnnot_SetStringValue("T", …)
pdf_annot_set_subject	FPDFAnnot_SetStringValue("Subj", …)
pdf_annot_set_dict_value	FPDFAnnot_SetStringValue(key, …)
pdf_annot_append_quad	FPDFAnnot_AppendAttachmentPoints

Conventions (ADR-018)

• Composite color setters accept a full color vector or per-channel overrides; auto-detect 0-255 ints vs 0-1 doubles. Bug fix on the partial-overlay path: pdf_annot_color() returns 0..1, so when the setter reads the current color for an overlay it scales back to 0..255 before merging — without that step the unchanged channels would clamp to near-zero.
• Flag setter accepts either a raw integer bitmask or a named logical matching pdf_annot_flags_decoded(). New internal pdfium_annot_flag_encode() is the inverse of the existing decoder.
• Delete removes via FPDFPage_RemoveAnnot and R_ClearExternalPtrs the handle so the existing is_open() chain reports closed for subsequent calls. The annot's own finalizer becomes a no-op (it's nullptr-tolerant).

Subtypes supported by pdf_annot_new

PDFium accepts: circle, fileattachment, freetext, highlight, ink, link, popup, square, squiggly, stamp, strikeout, text, underline. Other subtypes (e.g. widget, polygon, line) error from PDFium with a clear message.

Carve-outs (deferred to future phases)

• AP stream authoring (FPDFAnnot_SetAP + FPDFAnnot_AppendObject): a non-trivial workflow that overlaps with the page-object creators. Deferred — the existing pdf_annot_appearance() reader is enough to read AP streams and the writer side can come later.
• FPDFAnnot_SetAttachmentPoints(index, quad) (rewrite quad at index): only the append form ships. Reader returns the whole quad list; the natural authoring model is build-from-scratch + use pdf_annot_append_quad per quad.

Test plan

• devtools::test() — 1949 R assertions, 0 failures.
• lintr::lint_package() — no lints.
• R coverage 100% locally.
• Round-trip tests: every setter has a paired assertion reading back through the corresponding reader.
• Color partial-overlay test catches the 0..1 / 0..255 units mismatch (and confirms the fix).
• UTF-8 contents test ("日本語のテスト" round-trips).
• Read-only doc + closed-page rejection for every authoring function.
• CI matrix green on the PR.

Stacking note

Branches off claude/0.1.0-phase5-obj-creators (which in turn stacks on Phase 4). Please merge Phases 4 → 5 → 6 in order; each phase touches different source files so the NAMESPACE / RcppExports merges should be conflict-free.

🤖 Generated with Claude Code