betto_pdfium_ios

The first stable release of betto_pdfium and its iOS companion plugin
betto_pdfium_ios.

betto_pdfium is a pure Dart wrapper around
PDFium via dart:ffi. There is no
dependency on dart:ui or Flutter, so it works in CLI tools, server-side Dart,
and Flutter apps alike. Pre-built PDFium binaries
(bblanchon/pdfium-binaries
chromium/7906) are downloaded automatically by the native-assets build hook on
first use — no C++ toolchain required.

There are no functional changes since 0.1.0-dev.4; this release promotes the
dev channel to a stable version. The notes below summarise everything that
landed across 0.1.0-dev.1 → 0.1.0.

Installation

dependencies:
  betto_pdfium: ^0.1.0

Flutter iOS apps also need the companion plugin, which delivers the PDFium
xcframework via Swift Package Manager:

dependencies:
  betto_pdfium: ^0.1.0
  betto_pdfium_ios: ^0.1.0

Platform support

All eight targets are supported:

On desktop the binary is fetched automatically on the first dart test or
dart run. On iOS the xcframework arrives through SPM during flutter pub get.
Web requires make fetch_wasm_assets to stage the WASM/JS artifacts — see the
package README.

API surface

Everything hangs off PdfDocument:

• Document loading — PdfDocument.fromBytes() loads into a background
  isolate so the calling isolate is never blocked. PdfExtractionException
  distinguishes PdfError.passwordRequired from PdfError.invalidDocument.
  close() releases the native handle and is safe to call more than once.
• Metadata — getMetadata() (title, author, subject, keywords, creator,
  producer, creation/modification dates), getDocumentInfo() (file version,
  permanent/changing IDs), and pageCount.
• Text extraction — extractPlainText() streams PdfPageText per page with
  hasTextLayer and hasUnicodeErrors flags; isPlainTextExtractable() gives
  a quick scanned-document check.
• Rendering — renderPageToBytes() produces a raw BGRA pixel buffer, with
  optional annotation rendering, LCD text, and background colour.
  getPageSize() returns dimensions in points plus sizeForDpi().
• Annotations — extractAnnotations() streams typed annotations: text,
  markup (highlight/underline/squiggly/strikeout, with quadPoints), free text,
  ink, shape, popup, and stamp.
• Images — extractImages() streams image objects with bounding boxes and
  metadata, optionally with bitmaps; renderImage() fetches a single image's
  BGRA bitmap on demand.
• Search — search() streams matches with page index, character index, and
  rects in PDF user space; supports case, whole-word, and consecutive flags.
• Table of contents — tableOfContents returns the full nested bookmark
  tree.
• Thumbnails — getThumbnail() returns the embedded /Thumb stream when
  present, or a rendered fallback at a requested maximum dimension.
• pdfinfo CLI — dart run bin/pdfinfo.dart inspects metadata, document
  info, page count, table of contents, and text extractability.

Streams are fully cancellable — cancelling or calling close() stops processing
immediately with no native handle leaks.

Architecture notes

• PDFium is not thread-safe, so all calls run on a single process-wide isolate
  (PdfiumIsolate), lazily spawned and shared by every PdfDocument.
• On web, dart:isolate is unavailable, so the same concurrency model is
  implemented with a dedicated Web Worker and a postMessage protocol. Large
  document operations do not block the browser main thread.
• Rendering returns raw BGRA bytes rather than a dart:ui Image, keeping the
  rendering surface usable outside Flutter.

Notable fixes in the dev channel

• Native library resolution in a Pub workspace (dev.4) — when running from
  a workspace member package, the native-assets pipeline stages the library to
  the workspace root .dart_tool/lib/. The loader now walks up from the
  working directory probing each ancestor, covering both single-package and
  workspace layouts on Linux, macOS, and Windows.
• Dart 3.13 support (dev.4) — SDK constraint raised to ^3.13.0, verified
  end-to-end against the 3.13 native-assets pipeline on macOS, Linux (x64 and
  arm64), and Windows.

Quality

608 tests passing at 96.2% line coverage.

Documentation

• Package README: packages/betto_pdfium/README.md
• Full specification and API docs: https://bettongia.github.io/pdfium
• Changelog: packages/betto_pdfium/CHANGELOG.md

Packages on pub.dev

• betto_pdfium 0.1.0
• betto_pdfium_ios 0.1.0

First stable release. No functional changes since 0.1.0-dev.4.

When dart test runs from a workspace member package, the native-assets
pipeline stages the bundled PDFium library to the workspace root
.dart_tool/lib/, not the package's own .dart_tool/lib/. The runtime loader
(_openLibrary) previously probed only the current directory's
.dart_tool/lib/, so a PDFium call issued from a spawned isolate — which cannot
see the test runner's LD_LIBRARY_PATH and so cannot use the bare-name
fallback — failed with cannot open shared object file: No such file or directory.

This surfaced under Dart 3.13 in the kmdb workspace's PDF vault indexing:
dart test (run from packages/kmdb_cli) stages libpdfium.so to the
workspace root .dart_tool/lib/, but _openLibrary looked in the package dir
and missed it. betto_pdfium's own CI never exercised this because its test
suite injects an explicit dylib path via nativeDylibPath().

• Add dartToolLibCandidates(startDir, libName): walks up from the working
  directory, yielding each ancestor's .dart_tool/lib/<libName> nearest-first.
  Covers both the single-package layout (staged in cwd) and the workspace
  layout (staged in an ancestor root).
• Use it in the Linux, macOS, and Windows branches of _openLibrary in place
  of the single $cwd/.dart_tool/lib/ probe.
• Add unit tests for the walk-up (ordering, ancestor inclusion, root
  termination, library-name embedding). The helper is pure and testable, so it
  is not under the platform coverage:ignore region.

Version stays at 0.1.0-dev.4; bump to 0.1.0 (WI-9) once CI is green.

Co-authored-by: Claude Opus 4.8 [email protected]

• Dart 3.13 support. SDK constraint raised to ^3.13.0. No API changes.

Version bump — no API changes.

Version bump — no API changes.

minor fixes for release

• Initial version. Carries the PDFium static xcframework as an SPM binary target so that DynamicLibrary.process() can resolve FPDF_* symbols in Flutter iOS apps using betto_pdfium.