@reekon-tools/react-native-pdf-canvas 0.1.1 → 0.2.0

package/native/core/include/pdfcanvas/types.h

@@ -0,0 +1,110 @@
+// The value types the core speaks, mirroring `src/types.ts`.
+//
+// Every rect is in PAGE-LOCAL DOC SPACE: PDF points, y-down, origin at the
+// page's top-left, already post-rotation. That is exactly the space PDFium's
+// display matrix emits, which is why a PDFium core is a pass-through and needs
+// no transform of its own — the one thing the CoreGraphics core had to build by
+// hand (see the retired `PdfCanvasPageTransform.h`) does not exist here.
+#pragma once
+
+#include <atomic>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace pdfcanvas {
+
+enum class Background {
+  /// Fill the raster opaque white before drawing.
+  White,
+  /// Leave it cleared to transparent black before drawing. PDFium composites
+  /// onto whatever is there and never clears, so both backgrounds are an
+  /// explicit fill and only the value differs.
+  Transparent,
+};
+
+/// A page's intrinsic size in PDF points, POST-ROTATION.
+///
+/// `FPDF_GetPageSizeByIndexF` already applies `/Rotate` (measured: a 200x100
+/// MediaBox with `/Rotate 90` reports 100x200), and the render applies it too,
+/// so from this package's vantage point there is no residual rotation left for
+/// anyone to apply. `rotation` is therefore always 0 here. It exists because
+/// `PageGeometry.rotation` is on the TS contract, where it is informational.
+struct PageGeometry {
+  int index = 0;
+  double width = 0;
+  double height = 0;
+  int rotation = 0;
+};
+
+/// One raster to produce, mirroring `RasterRequest` in `src/types.ts`.
+struct RasterRequest {
+  int page = 0;
+  double x = 0;
+  double y = 0;
+  double width = 0;
+  double height = 0;
+  /// Device pixels per PDF point.
+  double scale = 1;
+  /// Draw PDF-embedded annotations (and form fields) into the raster.
+  bool annotations = true;
+  Background background = Background::White;
+
+  /// Destination width in device pixels: ROUND, not ceil, and at least 1 —
+  /// the rule `planner.ts`, the fake backend and both retired native cores all
+  /// share. The planner declares the pixel size the cache is keyed on, so a
+  /// backend that rounded the other way would hand back a raster of a
+  /// different size than the plan promised.
+  int pixelWidth() const;
+  int pixelHeight() const;
+};
+
+/// Where a document's bytes come from. Exactly one of `path` / `bytes` is used;
+/// a non-empty path wins.
+struct Source {
+  std::string path;
+  std::vector<uint8_t> bytes;
+  /// Present means "the caller supplied one", including the empty string —
+  /// PDFium reports the same error for "no password" and "wrong password", and
+  /// only the caller knows which it was.
+  bool hasPassword = false;
+  std::string password;
+};
+
+/// A cancellation flag, written by whoever owns the render's token and read by
+/// the render at five checkpoints — including MID-RENDER, through PDFium's
+/// progressive API. That last one is what neither retired core could offer:
+/// `CGContextDrawPDFPage` and `PdfRenderer.render` were uninterruptible once
+/// entered, and `RasterPolicy.minEpochIntervalMs` exists because of it.
+class Cancellation {
+ public:
+  void cancel() noexcept { cancelled_.store(true, std::memory_order_relaxed); }
+  bool isCancelled() const noexcept {
+    return cancelled_.load(std::memory_order_relaxed);
+  }
+
+  /// TESTING AFFORDANCE. Arms the flag to flip on the N-th poll of `poll()`,
+  /// which is what the render's mid-render checkpoint calls. It is the only
+  /// deterministic way to land a cancel INSIDE a render rather than before or
+  /// after it, and it is a no-op unless armed.
+  void cancelAfterPolls(int polls) noexcept {
+    pollsUntilCancel_.store(polls, std::memory_order_relaxed);
+  }
+
+  /// The render's view of the flag: `isCancelled()`, plus the poll counter.
+  bool poll() noexcept {
+    const int remaining = pollsUntilCancel_.load(std::memory_order_relaxed);
+    if (remaining > 0) {
+      if (pollsUntilCancel_.fetch_sub(1, std::memory_order_relaxed) == 1) {
+        cancel();
+      }
+    }
+    return isCancelled();
+  }
+
+ private:
+  std::atomic<bool> cancelled_{false};
+  std::atomic<int> pollsUntilCancel_{0};
+};
+
+}  // namespace pdfcanvas

package/native/core/pdfcanvas-core.cmake

@@ -0,0 +1,22 @@
+# The core's source list and include directory, for every build that compiles
+# it: the Android library (android/src/main/cpp/CMakeLists.txt), the host test
+# suite (native/CMakeLists.txt). The CocoaPods build lists the same files via
+# `source_files` globs in PdfCanvas.podspec, because CocoaPods does not read
+# CMake. Keep the two in step: a file added here and not there compiles on two
+# platforms and is undefined on the third.
+#
+# `include()` this, then compile `${PDFCANVAS_CORE_SOURCES}` with
+# `${PDFCANVAS_CORE_INCLUDE_DIR}` on the include path and the PDFium headers
+# reachable as `fpdfview.h`.
+
+set(PDFCANVAS_CORE_DIR "${CMAKE_CURRENT_LIST_DIR}")
+set(PDFCANVAS_CORE_INCLUDE_DIR "${PDFCANVAS_CORE_DIR}/include")
+set(PDFCANVAS_CORE_SOURCES
+  "${PDFCANVAS_CORE_DIR}/src/document.cpp"
+  "${PDFCANVAS_CORE_DIR}/src/error.cpp"
+  "${PDFCANVAS_CORE_DIR}/src/jsi.cpp"
+  "${PDFCANVAS_CORE_DIR}/src/library.cpp"
+  "${PDFCANVAS_CORE_DIR}/src/pixels.cpp"
+  "${PDFCANVAS_CORE_DIR}/src/service.cpp"
+  "${PDFCANVAS_CORE_DIR}/src/slots.cpp"
+)

package/native/core/src/document.cpp

@@ -0,0 +1,516 @@
+#include "pdfcanvas/document.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <cstdlib>
+#include <limits>
+#include <mutex>
+#include <string>
+#include <sys/stat.h>
+#include <vector>
+
+#include "fpdf_formfill.h"
+#include "fpdf_progressive.h"
+#include "fpdfview.h"
+#include "pdfcanvas/library.h"
+#include "pdfcanvas/slots.h"
+
+namespace pdfcanvas {
+
+namespace {
+
+/* ------------------------------------------------------------------ *
+ * Constants
+ * ------------------------------------------------------------------ */
+
+/// ARGB. Both values are symmetric under an R/B swap, which is what makes
+/// filling BEFORE a reverse-byte-order render correct rather than lucky:
+/// `FPDFBitmap_FillRect` writes in the bitmap's own BGRA order.
+constexpr FPDF_DWORD kOpaqueWhite = 0xFFFFFFFFu;
+constexpr FPDF_DWORD kTransparent = 0x00000000u;
+
+/// PDFium's ints are 32-bit; a request past this cannot be expressed at all.
+constexpr long long kMaxInt32 = (std::numeric_limits<int>::max)();
+
+/* ------------------------------------------------------------------ *
+ * Errors
+ * ------------------------------------------------------------------ */
+
+/// `FPDF_GetLastError()` after a failed load -> the frozen error union.
+///
+/// ONLY MEANINGFUL IMMEDIATELY AFTER A FAILED DOCUMENT LOAD (measured in the
+/// web backend: a later unrelated failure leaves the stale value in place), so
+/// this is consulted in exactly one place. `passwordSupplied` is what tells the
+/// two password outcomes apart: PDFium returns FPDF_ERR_PASSWORD both for an
+/// encrypted document opened with no password and for one opened with the
+/// wrong password, and the distinction matters — one means "prompt", the other
+/// "you got it wrong".
+PdfError loadError(unsigned long error, bool passwordSupplied, const std::string& what) {
+  ErrorCode code;
+  const char* name;
+  switch (error) {
+    case FPDF_ERR_FILE:
+      code = ErrorCode::NotFound;
+      name = "FILE";
+      break;
+    case FPDF_ERR_FORMAT:
+      // Both a truncated document and an eight-byte non-PDF report this.
+      code = ErrorCode::Corrupt;
+      name = "FORMAT";
+      break;
+    case FPDF_ERR_PASSWORD:
+      code = passwordSupplied ? ErrorCode::PasswordIncorrect : ErrorCode::PasswordRequired;
+      name = "PASSWORD";
+      break;
+    case FPDF_ERR_SECURITY:
+      // An encryption scheme this PDFium build cannot handle. Not corruption
+      // and not a wrong password — nothing the user can do about it.
+      code = ErrorCode::Unsupported;
+      name = "SECURITY";
+      break;
+    case FPDF_ERR_PAGE:
+      code = ErrorCode::Corrupt;
+      name = "PAGE";
+      break;
+    default:
+      code = ErrorCode::BackendFailure;
+      name = "UNKNOWN";
+      break;
+  }
+  return PdfError(code, "PDFium could not open " + what + " (FPDF_GetLastError = " +
+                            std::to_string(error) + " " + name +
+                            (passwordSupplied ? ", a password was supplied" : "") + ").");
+}
+
+/// What the file system can say that PDFium's single FPDF_ERR_FILE cannot: the
+/// four failures "no such file", "a directory", "unreadable" and "empty" all
+/// want different messages, because a host showing "corrupt" for a path that
+/// simply does not exist sends somebody looking at the wrong thing.
+void preflightPath(const std::string& path) {
+  if (path.empty()) {
+    throw PdfError(ErrorCode::NotFound, "No document path was given.");
+  }
+  struct stat st {};
+  if (::stat(path.c_str(), &st) != 0) {
+    throw PdfError(ErrorCode::NotFound, "No file at " + path + ".");
+  }
+  if ((st.st_mode & S_IFMT) == S_IFDIR) {
+    throw PdfError(ErrorCode::NotFound, path + " is a directory, not a PDF.");
+  }
+  if (st.st_size == 0) {
+    throw PdfError(ErrorCode::Corrupt, path + " is empty (0 bytes).");
+  }
+}
+
+void checkCancelled(Cancellation* signal, const char* stage) {
+  if (signal != nullptr && signal->isCancelled()) {
+    throw PdfError(ErrorCode::Cancelled, std::string("Render cancelled (") + stage + ").");
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * Geometry
+ * ------------------------------------------------------------------ */
+
+/// Read every page's size without loading a single page.
+///
+/// `FPDF_GetPageSizeByIndexF` works off the page DICTIONARY — no content
+/// stream is parsed — so the cost is proportional to the page tree and not to
+/// what is drawn on it. It is already post-rotation (measured: a 200x100
+/// MediaBox with `/Rotate 90` reports 100x200; the CropBox intersected with the
+/// MediaBox, after rotation — precisely what `PageGeometry` is defined as).
+///
+/// A page that cannot be measured fails the OPEN rather than being papered
+/// over with a zero size: a `PageGeometry` is what the layout turns into the
+/// document's whole coordinate space, so a wrong one is every page after it in
+/// the wrong place.
+std::vector<PageGeometry> readGeometry(FPDF_DOCUMENT document) {
+  const int pageCount = FPDF_GetPageCount(document);
+  std::vector<PageGeometry> pages;
+  pages.reserve(static_cast<size_t>(std::max(0, pageCount)));
+  for (int index = 0; index < pageCount; index++) {
+    FS_SIZEF size{};
+    if (!FPDF_GetPageSizeByIndexF(document, index, &size)) {
+      throw PdfError(ErrorCode::Corrupt, "PDFium could not read the size of page " +
+                                             std::to_string(index) + " of " +
+                                             std::to_string(pageCount) + ".");
+    }
+    PageGeometry geometry;
+    geometry.index = index;
+    geometry.width = size.width;
+    geometry.height = size.height;
+    // Always 0: PDFium pre-applies `/Rotate` to both the size above and the
+    // render, so there is no residual rotation for a caller to apply. Reading
+    // the raw value would need `FPDF_LoadPage`, which parses the content
+    // stream — the one thing `pageGeometry` is forbidden to do.
+    geometry.rotation = 0;
+    pages.push_back(geometry);
+  }
+  return pages;
+}
+
+/* ------------------------------------------------------------------ *
+ * The progressive pause
+ * ------------------------------------------------------------------ */
+
+/// PDFium's progressive renderer calls `NeedToPauseNow` between batches of page
+/// objects. Answering "yes" only when the render has been cancelled means a
+/// live render never pauses at all, and a superseded one stops within one batch
+/// — which is what makes `interruptibleRender: true` honest for the first time
+/// on a native backend.
+struct PauseAdapter {
+  IFSDK_PAUSE pause{};
+  Cancellation* signal = nullptr;
+
+  explicit PauseAdapter(Cancellation* s) : signal(s) {
+    pause.version = 1;
+    pause.user = this;
+    pause.NeedToPauseNow = [](IFSDK_PAUSE* self) -> FPDF_BOOL {
+      auto* adapter = static_cast<PauseAdapter*>(self->user);
+      return adapter->signal != nullptr && adapter->signal->poll() ? 1 : 0;
+    };
+  }
+};
+
+}  // namespace
+
+/* ------------------------------------------------------------------ *
+ * Impl
+ * ------------------------------------------------------------------ */
+
+struct Document::Impl {
+  FPDF_DOCUMENT document = nullptr;
+  FPDF_FORMHANDLE form = nullptr;
+  FPDF_FORMFILLINFO formInfo{};
+  /// The bytes a memory document reads from. `FPDF_LoadMemDocument64` does
+  /// not copy: PDFium reads lazily for the whole life of the document, so this
+  /// is freed after `FPDF_CloseDocument` and never before.
+  std::vector<uint8_t> bytes;
+  bool closed = false;
+
+  struct LoadedPage {
+    int index = -1;
+    FPDF_PAGE page = nullptr;
+    uint64_t lastUse = 0;
+  };
+  std::vector<LoadedPage> cache;
+  uint64_t useCounter = 0;
+
+  /// Requires the library lock.
+  FPDF_PAGE loadPage(int index) {
+    for (auto& entry : cache) {
+      if (entry.index == index) {
+        entry.lastUse = ++useCounter;
+        return entry.page;
+      }
+    }
+    if (cache.size() >= static_cast<size_t>(kPageCacheCapacity)) {
+      auto oldest = std::min_element(
+          cache.begin(), cache.end(),
+          [](const LoadedPage& a, const LoadedPage& b) { return a.lastUse < b.lastUse; });
+      unloadPage(*oldest);
+      cache.erase(oldest);
+    }
+    // `FPDF_LoadPage` is the call that parses the content stream; an epoch is
+    // several tiles of the same page, so the cache above turns N parses into
+    // one.
+    FPDF_PAGE page = FPDF_LoadPage(document, index);
+    if (page == nullptr) {
+      // Not `FPDF_GetLastError` — it is stale here. The index was already
+      // bounds-checked against the geometry read at open, so a failure at this
+      // point is a page whose content PDFium refuses.
+      throw PdfError(ErrorCode::Corrupt,
+                     "PDFium could not load page " + std::to_string(index) +
+                         ". The page exists (its size was read at open) but its "
+                         "content could not be parsed.");
+    }
+    if (form != nullptr) {
+      // Required for FPDF_FFLDraw to know the page's widgets; balanced by
+      // FORM_OnBeforeClosePage in unloadPage.
+      FORM_OnAfterLoadPage(page, form);
+    }
+    cache.push_back({index, page, ++useCounter});
+    return page;
+  }
+
+  void unloadPage(LoadedPage& entry) {
+    if (entry.page == nullptr) return;
+    if (form != nullptr) FORM_OnBeforeClosePage(entry.page, form);
+    FPDF_ClosePage(entry.page);
+    entry.page = nullptr;
+  }
+
+  void closeAll() {
+    if (closed) return;
+    closed = true;
+    for (auto& entry : cache) unloadPage(entry);
+    cache.clear();
+    if (form != nullptr) {
+      FPDFDOC_ExitFormFillEnvironment(form);
+      form = nullptr;
+    }
+    if (document != nullptr) {
+      FPDF_CloseDocument(document);
+      document = nullptr;
+    }
+    // AFTER the close, never before.
+    bytes.clear();
+    bytes.shrink_to_fit();
+  }
+};
+
+/* ------------------------------------------------------------------ *
+ * Open / close
+ * ------------------------------------------------------------------ */
+
+Document::Document(std::unique_ptr<Impl> impl) : impl_(std::move(impl)) {}
+
+Document::~Document() {
+  std::lock_guard<std::mutex> lock(Library::mutex());
+  impl_->closeAll();
+}
+
+std::unique_ptr<Document> Document::open(const Source& source) {
+  const bool fromPath = !source.path.empty();
+  if (fromPath) {
+    preflightPath(source.path);
+  } else if (source.bytes.empty()) {
+    throw PdfError(ErrorCode::Corrupt, "The document is empty (0 bytes).");
+  }
+
+  auto impl = std::make_unique<Impl>();
+  std::lock_guard<std::mutex> lock(Library::mutex());
+  Library::ensureInitialized();
+
+  const char* password = source.hasPassword ? source.password.c_str() : nullptr;
+  if (fromPath) {
+    impl->document = FPDF_LoadDocument(source.path.c_str(), password);
+  } else {
+    impl->bytes = source.bytes;
+    impl->document = FPDF_LoadMemDocument64(impl->bytes.data(), impl->bytes.size(), password);
+  }
+  if (impl->document == nullptr) {
+    throw loadError(FPDF_GetLastError(), source.hasPassword,
+                    fromPath ? source.path : "the document bytes");
+  }
+
+  std::vector<PageGeometry> pages;
+  try {
+    pages = readGeometry(impl->document);
+  } catch (...) {
+    impl->closeAll();
+    throw;
+  }
+
+  // The form-fill environment is what draws WIDGET annotations — form fields
+  // — which `FPDF_RenderPageBitmap` skips even with `FPDF_ANNOT`. Version 1 of
+  // the info struct, with every callback null: PDFium null-checks them all,
+  // and this build has no V8, so nothing here ever needs to answer a
+  // JavaScript action. Opened eagerly because it is cheap and because a page
+  // must be registered with it at load time, before anyone knows whether an
+  // annotations render will come.
+  impl->formInfo = FPDF_FORMFILLINFO{};
+  impl->formInfo.version = 1;
+  impl->form = FPDFDOC_InitFormFillEnvironment(impl->document, &impl->formInfo);
+  if (impl->form != nullptr) {
+    // No field highlight. Chrome and Acrobat tint fillable fields light blue
+    // on screen; under an annotation canvas that wash would read as content,
+    // and it is not what a printed or flattened copy of the page looks like.
+    FPDF_SetFormFieldHighlightColor(impl->form, FPDF_FORMFIELD_UNKNOWN, 0xFFE4DD);
+    FPDF_SetFormFieldHighlightAlpha(impl->form, 0);
+  }
+
+  std::unique_ptr<Document> document(new Document(std::move(impl)));
+  document->pages_ = std::move(pages);
+  return document;
+}
+
+void Document::close() {
+  std::lock_guard<std::mutex> lock(Library::mutex());
+  impl_->closeAll();
+}
+
+bool Document::isClosed() const noexcept { return impl_->closed; }
+
+const PageGeometry& Document::geometry(int index) const {
+  if (index < 0 || static_cast<size_t>(index) >= pages_.size()) {
+    throw PdfError(ErrorCode::NotFound, "Document has " + std::to_string(pages_.size()) +
+                                            " pages; asked for " + std::to_string(index) + ".");
+  }
+  return pages_[static_cast<size_t>(index)];
+}
+
+/* ------------------------------------------------------------------ *
+ * Render
+ * ------------------------------------------------------------------ */
+
+RasterPixels Document::render(const RasterRequest& request, Cancellation* signal,
+                              PixelSink* sink) {
+  checkCancelled(signal, "before start");
+  if (impl_->closed) {
+    throw PdfError(ErrorCode::BackendFailure, "Document handle is closed.");
+  }
+  const PageGeometry& geometry = this->geometry(request.page);
+
+  if (!std::isfinite(request.scale) || request.scale <= 0) {
+    throw PdfError(ErrorCode::BackendFailure,
+                   "Scale must be a positive finite number, got " + std::to_string(request.scale) + ".");
+  }
+  if (!std::isfinite(request.x) || !std::isfinite(request.y) || !(request.width > 0) ||
+      !(request.height > 0)) {
+    throw PdfError(ErrorCode::BackendFailure,
+                   "Doc rect must be finite and have positive extent, got " +
+                       std::to_string(request.width) + "x" + std::to_string(request.height) +
+                       " at (" + std::to_string(request.x) + ", " + std::to_string(request.y) + ").");
+  }
+
+  const int pxW = request.pixelWidth();
+  const int pxH = request.pixelHeight();
+  const long long pixels = static_cast<long long>(pxW) * pxH;
+  // THE RECT MECHANISM — negative offsets, not a matrix. PDFium draws the WHOLE
+  // page at the target scale slid by (-x*s, -y*s) into a bitmap that is only
+  // the tile's size; everything outside is clipped by the bitmap itself.
+  // `-round(x*s)`, not `round(-x*s)`: the tile's origin inside a hypothetical
+  // full-page render is `round(x*s)`, and negating the rounded origin makes the
+  // two the same integer by construction. The web backend measured this
+  // byte-identical to the matrix form on every rect it tried.
+  const long long startX = -std::llround(request.x * request.scale);
+  const long long startY = -std::llround(request.y * request.scale);
+  const long long pageW = std::llround(geometry.width * request.scale);
+  const long long pageH = std::llround(geometry.height * request.scale);
+  if (pixels > kMaxRasterPixels) {
+    throw PdfError(ErrorCode::OutOfMemory,
+                   "Refused a " + std::to_string(pxW) + "x" + std::to_string(pxH) + " raster (" +
+                       std::to_string(pixels) + " pixels > " + std::to_string(kMaxRasterPixels) + ").");
+  }
+  if (pageW > kMaxInt32 || pageH > kMaxInt32 || std::llabs(startX) > kMaxInt32 ||
+      std::llabs(startY) > kMaxInt32) {
+    throw PdfError(ErrorCode::OutOfMemory,
+                   "A " + std::to_string(pxW) + "x" + std::to_string(pxH) + " raster of a " +
+                       std::to_string(pageW) + "x" + std::to_string(pageH) +
+                       " page cannot be expressed in PDFium's 32-bit ints. Lower "
+                       "`RasterPolicy.maxPieceDimension` or `maxRasterPixels`.");
+  }
+  const int rowBytes = pxW * 4;
+  const size_t byteCount = static_cast<size_t>(rowBytes) * static_cast<size_t>(pxH);
+
+  std::lock_guard<std::mutex> lock(Library::mutex());
+  // The wait above is where a cancel most often lands — a superseded detail
+  // raster typically queues behind a base raster — so the signal is re-read on
+  // the far side of it.
+  checkCancelled(signal, "after lock");
+  if (impl_->closed) {
+    throw PdfError(ErrorCode::BackendFailure, "Document handle is closed.");
+  }
+
+  FPDF_PAGE page = impl_->loadPage(request.page);
+
+  // RESERVE BEFORE DRAWING, and fall back before drawing too. A sink refusal
+  // here costs nothing, which is the point of deciding it before the raster
+  // exists.
+  HeapSink heap;
+  PixelSink* destination = sink;
+  uint8_t* buffer = destination != nullptr ? destination->reserve(byteCount) : nullptr;
+  if (buffer == nullptr) {
+    destination = &heap;
+    buffer = heap.reserve(byteCount);
+  }
+  if (buffer == nullptr) {
+    throw PdfError(ErrorCode::OutOfMemory, "Could not allocate " + std::to_string(byteCount) +
+                                               " bytes for a " + std::to_string(pxW) + "x" +
+                                               std::to_string(pxH) + " raster.");
+  }
+
+  FPDF_BITMAP bitmap = FPDFBitmap_CreateEx(pxW, pxH, FPDFBitmap_BGRA, buffer, rowBytes);
+  if (bitmap == nullptr) {
+    destination->abandon();
+    throw PdfError(ErrorCode::BackendFailure, "PDFium refused a " + std::to_string(pxW) + "x" +
+                                                  std::to_string(pxH) + " bitmap over the sink's buffer.");
+  }
+
+  // THE FILL IS NOT OPTIONAL. PDFium composites onto the destination and never
+  // clears it; a zeroed RGBA buffer is transparent BLACK, which under the app's
+  // annotation layers reads as a black page rather than a blank one, and ingest
+  // cannot tell "the PDF painted black here" from "nothing painted here".
+  if (!FPDFBitmap_FillRect(bitmap, 0, 0, pxW, pxH,
+                           request.background == Background::White ? kOpaqueWhite : kTransparent)) {
+    FPDFBitmap_Destroy(bitmap);
+    destination->abandon();
+    throw PdfError(ErrorCode::BackendFailure,
+                   "PDFium refused to clear the destination before rendering page " +
+                       std::to_string(request.page) + ".");
+  }
+
+  // RGBA out (Skia's universally-accepted colour type) instead of PDFium's
+  // native BGRA; annotations only when asked. NO `FPDF_LCD_TEXT`: subpixel text
+  // is calibrated to a specific pixel grid, and every tile here is scaled and
+  // composited by Skia afterwards.
+  const int flags = FPDF_REVERSE_BYTE_ORDER | (request.annotations ? FPDF_ANNOT : 0);
+  const int sx = static_cast<int>(startX);
+  const int sy = static_cast<int>(startY);
+  const int pw = static_cast<int>(pageW);
+  const int ph = static_cast<int>(pageH);
+
+  auto abandonWith = [&](PdfError error) -> PdfError {
+    FPDFBitmap_Destroy(bitmap);
+    destination->abandon();
+    return error;
+  };
+
+  if (signal != nullptr && signal->isCancelled()) {
+    throw abandonWith(PdfError(ErrorCode::Cancelled, "Render cancelled (before render)."));
+  }
+
+  // THE PROGRESSIVE API, so a cancel lands mid-draw. `Start` returns
+  // TOBECONTINUED when the pause adapter asked to stop, which it does only
+  // once the signal is set; a live render runs to DONE in one call.
+  PauseAdapter pause(signal);
+  int status = FPDF_RenderPageBitmap_Start(bitmap, page, sx, sy, pw, ph, /*rotate=*/0, flags,
+                                           &pause.pause);
+  while (status == FPDF_RENDER_TOBECONTINUED) {
+    if (signal != nullptr && signal->isCancelled()) {
+      FPDF_RenderPage_Close(page);
+      throw abandonWith(PdfError(ErrorCode::Cancelled, "Render cancelled (mid-render)."));
+    }
+    status = FPDF_RenderPage_Continue(page, &pause.pause);
+  }
+  FPDF_RenderPage_Close(page);
+  if (status == FPDF_RENDER_FAILED) {
+    throw abandonWith(PdfError(ErrorCode::BackendFailure,
+                               "PDFium failed to render page " + std::to_string(request.page) + "."));
+  }
+
+  // Form fields are WIDGET annotations, and `FPDF_RenderPageBitmap` skips
+  // widgets even with FPDF_ANNOT (they belong to the form-fill environment).
+  // This is the pass that draws them — the filled-in value, the checkbox
+  // state — with the same offsets, so they land exactly where the page put
+  // them.
+  if (request.annotations && impl_->form != nullptr) {
+    FPDF_FFLDraw(impl_->form, bitmap, page, sx, sy, pw, ph, /*rotate=*/0, flags);
+  }
+
+  FPDFBitmap_Destroy(bitmap);
+
+  // Post-check. This saves no drawing — the pixels are already finished — it
+  // only stops a superseded raster being handed back and ingested into Skia,
+  // which is the expensive half on the JS side. THE ABANDON IS NOT OPTIONAL: a
+  // slot-backed raster is about to be published to a process-wide map where
+  // nothing else will ever look for it.
+  if (signal != nullptr && signal->isCancelled()) {
+    destination->abandon();
+    throw PdfError(ErrorCode::Cancelled, "Render cancelled (after render).");
+  }
+
+  RasterPixels out;
+  out.width = pxW;
+  out.height = pxH;
+  out.rowBytes = rowBytes;
+  out.slot = destination->publish();
+  if (destination == &heap) {
+    out.bytes = heap.takeBytes();
+  }
+  return out;
+}
+
+}  // namespace pdfcanvas

package/native/core/src/error.cpp

@@ -0,0 +1,29 @@
+#include "pdfcanvas/error.h"
+
+namespace pdfcanvas {
+
+const char* wireName(ErrorCode code) {
+  switch (code) {
+    case ErrorCode::NotFound:
+      return "not-found";
+    case ErrorCode::PasswordRequired:
+      return "password-required";
+    case ErrorCode::PasswordIncorrect:
+      return "password-incorrect";
+    case ErrorCode::Corrupt:
+      return "corrupt";
+    case ErrorCode::Unsupported:
+      return "unsupported";
+    case ErrorCode::Cancelled:
+      return "cancelled";
+    case ErrorCode::OutOfMemory:
+      return "out-of-memory";
+    case ErrorCode::BackendFailure:
+      return "backend-failure";
+  }
+  // No `default:` above, so a new member is a compiler warning rather than a
+  // silent fall-through to this line.
+  return "backend-failure";
+}
+
+}  // namespace pdfcanvas