@spec annotations(ExPdfium.Document.t(), non_neg_integer()) ::
  {:ok, [map()]} | {:error, atom()}

Return the annotations on a 0-indexed page, in page order.

Each annotation is:

%{
  type: atom(),                # the PDF /Subtype, e.g. :text, :highlight,
                               # :link, :widget, :ink, :stamp, :free_text…
  bounds: t:bounds/0 | nil,    # the annotation rectangle, in PDF points
  contents: String.t() | nil,  # the /Contents text
  name: String.t() | nil,      # the annotation's /NM name (not a field name)
  hidden: boolean(),
  printed: boolean()
}

Widget annotations (form-field controls) are listed alongside markup annotations; use form_fields/1 to read their field values. A page with no annotations returns {:ok, []}.

@spec form_fields(ExPdfium.Document.t()) :: {:ok, [map()]} | {:error, atom()}

Read the document's AcroForm fields, one entry per widget, across all pages.

Each field is:

%{
  name: String.t() | nil,   # the field's /T name
  type: :text | :checkbox | :radio_button | :combo_box | :list_box |
        :push_button | :signature | :unknown,
  value: String.t() | nil,  # text/combo/list value, or the selected on-state of a button group
  checked: boolean() | nil, # checkbox/radio only; nil for other types
  read_only: boolean(),
  required: boolean(),
  page: non_neg_integer(),  # 0-indexed page the widget sits on
  bounds: t:bounds/0 | nil
}

A checkbox or radio group shares one name across its option widgets, so it surfaces as one entry per option widget. For these, value is the group's currently-selected on-state (the same string on every widget in the group), and checked flags which widget is the selected one — so to find a radio group's answer, take the value of the entry whose checked is true. A document with no form returns {:ok, []}.

value and checked are read straight from pdfium without coercion: a checked checkbox is %{value: "Yes", checked: true}, never flattened to a string.

@spec form_type(ExPdfium.Document.t()) ::
  {:ok, :none | :acrobat | :xfa_full | :xfa_foreground} | {:error, atom()}

Return which interactive-form technology the document uses.

One of :none, :acrobat (a classic AcroForm), :xfa_full, or :xfa_foreground (XFA forms). A document with no form returns {:ok, :none}.