docs: Android AcroForm / form field appearance limits (#303)

[endigo]

Summary

• Investigated #303: first PDFBox PDTextField missing on Android while Adobe shows all fields.
• Not a plugin bug / not fixable in-viewer. Android already enables annotation rendering. Pdfium paints /AP appearance streams only and does not regenerate widget appearances from /V + /DA the way Adobe does.
• Root cause on the attached sample PDF: field tb_187524_0 (PDTextField 1) has /AP → 29 0 R, but object 29 in the final document is an XRef stream, not a Form appearance dictionary (object-number collision from incremental updates / signing). Fields 2 and 3 still have valid /AP Form XObjects, which matches the reporter screenshots.
• Documented AcroForm limits and producer workarounds in README; CHANGELOG note under 1.5.0-beta.1 docs line.
• No package version bump (coordinator releases later). No native code changes.

Test plan

• flutter pub get && dart format . && flutter analyze && flutter test (all passed)
• No Android code changes → skipped Android unit tests
• Review README “AcroForm / fillable form fields” section for accuracy

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0b1df79d-e138-41ac-a150-2457f8b0a639

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[endigo]

Review results (worker review-release-prs-353-357)

Quality gates

Check	Result
flutter analyze	✅
flutter test	✅ 95 passed
Docs-only	✅ No native code changes

Review notes

Accurate Pdfium /AP limitation write-up with producer workarounds for PDFBox/signing object-number collisions. Correctly scoped as not a plugin defect.

Merge + release

Merged into migrate/kotlin-swift and published as 1.5.0-beta.4 on pub.dev.