feat(pdf): annotate a pdf from json

[andiwand]

🤖 Generated with Claude Code

Phase 4 of docs/design/pdf-annotation.md. Stacked on #847. Second of four; the browser layer and bindings follow.

void PdfFile::annotate(std::string_view annotations, std::ostream &out,
                       const Logger & = Logger::null()) const;

Takes the JSON payload the browser-side annotator will produce and writes the annotated file. Per decision 1, it hangs off PdfFile, not Document — pdf has none — and addresses annotations by page index and user-space geometry, never by element id. That is what keeps this feature independent of the deferred editing.md work.

{"version": 1, "annotations": [
  {"page": 0, "type": "highlight",
   "quads": [[72, 700, 300, 700, 72, 688, 300, 688]],
   "color": [1, 0.9, 0.2], "opacity": 1, "author": "…", "contents": "…"},
  {"page": 1, "type": "ink", "strokes": [[100, 500, 130, 540]],
   "width": 2, "color": [0.9, 0.1, 0.1]}
]}

Refused rather than half-understood

Fail-fast, per the repo convention — each with its own test:

• a version that is not 1 (the drift guard against a newer frontend)
• text that is not JSON
• a type we do not write
• a page that is not there
• a quad that is not eight coordinates
• a missing required member (color, quads, type, page)
• an encrypted file, and one whose xref was recovered (decisions 2 and 6)

An empty payload is legal and writes a no-op update, which falls out of the writer rather than being special-cased.

Annotations landing on the same page share a single page rewrite rather than one per annotation.

Capability

FileTypeCapabilities gains annotate, set on the pdf row. The existing edit/save bits are documented against Document, which pdf has none of, so reusing either would have been a lie — and the conformance test's edit ⇒ save invariant would not hold. annotate gets the same treatment the others get: a type nothing can open cannot claim it.

Bindings for it come with the rest in the bindings PR.

Verified

Seven tests over style-various-1.pdf through the real public entry point: a highlight lands with its appearance resolved, all five types land on the right pages, author/contents/opacity reach the file (with a ( in contents surviving escaping), the empty payload, every refusal, and the encrypted file.

448 tests pass across the pdf, writer, odr, file and html suites; -Werror clean. clang-tidy on the touched file reports only two pre-existing findings (file_meta's exception-escape at an untouched line, and the known decrypt shadowing false positive).

Changelog entry added.