v0.6.0 — AcroForm extraction + PdfDocument fill/save SDK

[rrader26]

Summary

PDFs with AcroForm fields are now first-class. They snapshot as `kind: 'form'` with each field exposed as an AgentMark action; the new `PdfDocument` SDK class lets agents fill, save, and flatten them with the same `execute()` shape as the web `Page` SDK.

Stacked on top of #4 (v0.5 OCR). Merge #2 → #3 → #4 → this PR in order.

What's new

AcroForm extraction

`convertPdf()` now automatically reads form fields and sets `kind: 'form'` when they exist. Each AcroForm field becomes an `ActionDefinition` with the right AgentMark type:

AcroForm	AgentMark	Notes
Text (single / multi-line)	`type: 'type'`	Sensitive names redacted
Checkbox	`type: 'check'`	Boolean coerced from PDF "Yes"/"Off"
Radio group	`type: 'select'`	Options included
Dropdown	`type: 'select'`	Options included
Listbox single	`type: 'select'`
Listbox multi (`multipleSelection`)	`type: 'multi_select'`
Signature	`type: 'click'` (disabled)	Refused — agents can't sign
Push button	`type: 'click'`

PdfDocument SDK class

import { openPdfDocument } from '@thinkfleet/agentmark'

const doc = await openPdfDocument({ data, sourceUrl: 'file:///vendor.pdf' })
const snap = await doc.snapshot()                  // kind: 'form' with all actions

await doc.execute('act_field_1', 'Acme Inc.')       // text
await doc.execute('act_field_2', true)              // checkbox
await doc.execute('act_field_3', 'NC')              // dropdown
await doc.execute('act_field_4', ['English', 'Spanish'])  // multi-select

const filled = await doc.save()                     // new PDF bytes with values
const flattened = await doc.save({ flatten: true }) // bake values into page content

await doc.close()

Mirrors the web `Page` SDK so callers' agent loops are identical regardless of surface.

Field-flag handling

`Required` and `ReadOnly` are read from page widget annotations (where pdfjs-dist surfaces `fieldFlags`) since `getFieldObjects()` doesn't expose them in v4+.

Sensitive-name redaction

Field names matching common patterns (`password`, `ssn`, `credit_card`, `cvv`, `account_num`, `token`, `secret`, `csrf`, `session`, `auth`) get `(redacted)` labels and `undefined` values.

Humanized labels

`applicant.first_name` / `firstName` / `first-name` all → `"First Name"`.

Internal type rename

The internal extraction-result interface `PdfDocument` was renamed to `ExtractedPdf` to free the `PdfDocument` name for the new public class. Internal-only — no consumer code referenced the old name through the public API.

Optional peer dependency

`pdf-lib` added as optional peer. Reading uses `pdfjs-dist` (already installed); writing requires `pdf-lib`. Throws `SnapshotError` with install instructions if missing.

Tests

• 12 new acroform-extractor tests (all field types, redaction, flags, humanization, schema compliance)
• 11 new `PdfDocument` round-trip tests (fill → save → re-extract for every field type, error semantics, flatten, close idempotency)
• 199 unit + 10 real-Chromium integration = 209 total (was 188)

Known limitations

• `pdfjs-dist`'s `getFieldObjects()` reports only the first selected value of a multi-select listbox. AgentMark's saved PDF DOES contain all values correctly (verified directly via pdf-lib in the test suite); only the snapshot view under-reports. Wait for pdfjs upstream.
• Form-structure inference for non-AcroForm PDFs (the insurance-renewal case) deferred.
• Signature fields refuse fill — agents can't truly sign.

Test plan

• Merge v0.3.0 — production-ready SDK surface + action executor #2 → v0.4.0 — PDF support + spec v0.2 (kind: document) #3 → v0.5.0 — OCR + render-backend pipeline (100% on insurance corpus) #4 first (in order)
• `npm install && npm test` — all 199 unit tests pass
• Spot-check a real fillable gov form: `openPdfDocument` → `execute` → `save` → open in Acrobat to verify
• Verify backwards compat: PDFs without AcroForm fields still produce `kind: 'document'`
• Verify `pdf-lib`-not-installed error: temporarily `npm uninstall pdf-lib` and confirm `save()` throws clean error
• Verify the type rename didn't break existing imports — `ExtractedPdf` is the new internal name; the public class is now `PdfDocument`

🤖 Generated with Claude Code