open_pdf_annotation_engine

Android-first Flutter plugin for editable PDF annotations, sidecar persistence, notes export, flattened export, and open PDF write-back without a commercial SDK.

What v4 improves

  • safer file handling for copy, overwrite, sidecar, and export flows
  • annotation validation before platform calls
  • duplicate managed annotations are removed before re-writing native annotations
  • better example app structure for pub.flutter-io.cn package scoring
  • metadata and docs added for package publication
  • Android library config updated toward current Google Play submission expectations

What the package does

  • stores editable annotations in a sidecar JSON file
  • exports a filename+notes.pdf style notes document
  • can write first-pass native Ink, FreeText, and Highlight annotations into a PDF copy
  • can export a flattened annotated PDF
  • can list embedded annotations from an existing PDF

Important scope notes

This package focuses on Android. It is not yet a full Adobe/Xodo/Foxit replacement.

Current limitations:

  • highlight creation still depends on your app supplying correct PDF-space geometry
  • flattened export is raster-based, not vector-preserving
  • third-party embedded annotation editing is not complete
  • the host app is responsible for secure file picking and user-consented access

Why sidecar data is still the source of truth

Editable annotation round-tripping in pure open Flutter tooling remains much harder than rendering PDFs. This package keeps annotations editable in a sidecar model first, then writes or flattens exports when requested.

Installation

dependencies:
  open_pdf_annotation_engine:
    git:
      url: https://github.com/kgdthomas/open_pdf_annotation_engine.git
      ref: v0.4.0

Basic use

final engine = OpenPdfAnnotationEngine();

final annotation = PdfAnnotation(
  type: AnnotationType.freeText,
  pageNumber: 1,
  color: const AnnotationColor(r: 220, g: 0, b: 0, opacity: 1),
  createdAtIso: DateTime.now().toUtc().toIso8601String(),
  rect: const PdfRect(left: 40, top: 80, right: 250, bottom: 120),
  text: 'Hello from open_pdf_annotation_engine',
  fontSize: 16,
  tool: DrawTool.text,
);

final result = await engine.saveAnnotations(
  pdfPath: '/path/to/input.pdf',
  documentId: 'input_pdf',
  annotations: [annotation],
  mode: SaveMode.saveAsCopy,
  outputPdfPath: '/path/to/input_annotated.pdf',
  notesPdfPath: '/path/to/input+notes.pdf',
  flatten: false,
);

Security Policy

Reporting a Vulnerability

Please report security issues through GitHub Security Advisories for this repository. If that is not available, contact the maintainer through the repository issue tracker and mark the report as security-sensitive.

Repository: https://github.com/kgdthomas/open_pdf_annotation_engine

Pub.dev requires at minimum a valid package name, version, description, and SDK constraints. Optional metadata such as repository, topics, and screenshots improves discoverability.

Android / Play notes

Google Play currently requires new app submissions and updates to target Android 15, API level 35, or higher. This package now aligns its Android library compile target to 35, but the host app still controls the final Play compliance posture.

Libraries

open_pdf_annotation_engine