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

package/android/src/androidTest/java/tools/reekon/pdfcanvas/PoisonsTheProcess.java

@@ -1,20 +0,0 @@
-package tools.reekon.pdfcanvas;
-
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * Marks a test that deliberately triggers the API 24 PDFium poisoning and can
- * therefore only be the LAST thing its process does.
- *
- * `android/build.gradle` passes `notAnnotation` for this type, so
- * `connectedDebugAndroidTest` never runs it by accident. It is run on its own —
- * the command is in {@code PdfCanvasPoisonGuardTest}'s javadoc — which is the
- * only way to observe the guard doing its job, because observing it requires the
- * platform to actually be broken.
- */
-@Retention(RetentionPolicy.RUNTIME)
-@Target({ElementType.METHOD, ElementType.TYPE})
-public @interface PoisonsTheProcess {}

package/android/src/jsi/cpp/CMakeLists.txt

@@ -1,33 +0,0 @@
-# The raster transport's native half. See pdfcanvas-jsi.cpp for what it does.
-#
-# PDFCANVAS_WITH_JSI is passed ON only by the autolinked build, where
-# ReactAndroid's prefab publishes jsi/jsi.h and libjsi.so. The standalone build
-# (`cd android && ./gradlew connectedDebugAndroidTest`) passes nothing, has no
-# React Native anywhere on its classpath, and still compiles this library — the
-# slot storage and its JNI surface are React-free, which is what lets the device
-# suite prove the transport's byte fidelity with no app in the picture.
-
-cmake_minimum_required(VERSION 3.13)
-project(pdfcanvasjsi)
-
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-
-add_library(pdfcanvasjsi SHARED pdfcanvas-jsi.cpp)
-
-# jnigraphics is the NDK's Bitmap accessor (AndroidBitmap_getInfo /
-# AndroidBitmap_lockPixels), which is how the one-copy path reads a raster
-# straight out of the Bitmap's own pixel memory. Part of the platform since
-# API 8 and present on every device this package supports, so it is linked in
-# BOTH configurations — the standalone build needs it too, and that is what lets
-# the instrumented suite prove the fill's byte fidelity with no app in the
-# picture.
-target_link_libraries(pdfcanvasjsi jnigraphics)
-
-if(PDFCANVAS_WITH_JSI)
-  target_compile_definitions(pdfcanvasjsi PRIVATE PDFCANVAS_WITH_JSI=1)
-  # CONFIG mode against the react-android AAR's prefab package. `jsi` is the
-  # only target needed: nothing here touches TurboModules, fbjni or folly.
-  find_package(ReactAndroid REQUIRED CONFIG)
-  target_link_libraries(pdfcanvasjsi ReactAndroid::jsi)
-endif()

package/android/src/jsi/cpp/pdfcanvas-jsi.cpp

@@ -1,469 +0,0 @@
-/*
- * The raster transport: a Java `byte[]` becomes a JS `ArrayBuffer` with no
- * base64 anywhere in between.
- *
- * WHY THIS FILE EXISTS. The measured split for one 1024x1024 tile on an LG V60
- * was 100.07 ms of bridge round trip, 1005.46 ms of `decodeBase64` in Hermes and
- * 4.09 ms of Skia ingest. The decode is 90.6% of the cost and it is a
- * 5.6-million-iteration interpreted loop that exists only to undo an encode that
- * happened 3 ms earlier on the other side of the bridge. Deleting BOTH is what
- * this file does; the Skia ingest is untouched and is expected to survive.
- *
- * HOW MANY COPIES. TWO ENTRY POINTS, and they differ by exactly one copy. The
- * count below is of FULL-RASTER copies; the ArrayBuffer hand-off is a pointer
- * wrap in both cases and is not one of them.
- *
- *   `nativeStoreFromBitmap` — ONE copy. The `SlotBuffer` is allocated here, then
- *      `AndroidBitmap_lockPixels` gives the Bitmap's own pixel memory and one
- *      `memcpy` moves it in. The Java heap is never involved: no `byte[]`, and
- *      nothing for ART's large-object space to collect afterwards. This is the
- *      path `PdfCanvasRasterizer.extract` takes when a slot is asked for.
- *
- *   `nativeStore` — TWO copies, and it is kept because the base64 fallback needs
- *      a `byte[]` anyway. `Bitmap.copyPixelsToBuffer` has already copied the
- *      raster into a Java array (copy 1) before this is called; here
- *      `GetByteArrayRegion` copies it again into the `SlotBuffer` (copy 2).
- *      THIS COMMENT USED TO CLAIM "exactly one" FOR THIS PATH. It undercounted:
- *      it was counting from the `byte[]`, as though the array had arrived free.
- *
- * Both run on the render executor thread, the same worker that just did
- * `PdfRenderer.render`, so their cost is paid in parallel with whatever JS is
- * doing. Then `__pdfCanvasTakePixels` hands the `SlotBuffer` to
- * `jsi::ArrayBuffer(runtime, shared_ptr<MutableBuffer>)`: Hermes retains the
- * shared_ptr and points the ArrayBuffer's storage AT the vector. No copy.
- *
- * WHY THE FILL IS NOT DONE FROM JAVA THROUGH A DIRECT ByteBuffer. That was the
- * obvious shape — `NewDirectByteBuffer` over the `SlotBuffer` and let Java
- * `copyPixelsToBuffer` into it — and it opens a use-after-free this one does not.
- * A slot in `g_slots` is reachable by `nativeReleaseAll`, which runs on ANOTHER
- * thread (`PdfCanvasModule.invalidate`, i.e. every Fast Refresh) and frees the
- * vector. Handing the address to Java means the slot must be published BEFORE the
- * fill, so a reload landing mid-copy frees memory a render worker is still
- * writing into: silent heap corruption, weeks from the change that caused it.
- * Filling inside one JNI call keeps the shape every slot has always had —
- * allocate, fill, publish under the lock, in that order — so the buffer is
- * unreachable by anything else until it is finished.
- *
- * WHO FREES IT. The `SlotBuffer` is a `std::shared_ptr`. The slot map drops its
- * reference the instant the take succeeds, so from that moment the only owner is
- * the JS ArrayBuffer, and the vector is freed when Hermes collects it. A slot
- * that is stored and never taken (a JS teardown between the promise resolving
- * and its continuation running) is freed by `nativeReleaseAll`, which
- * `PdfCanvasModule.invalidate()` calls.
- *
- * TWO BUILDS, ONE FILE — the same split `build.gradle` already draws:
- *
- *   PDFCANVAS_WITH_JSI defined   — the autolinked build. ReactAndroid's prefab
- *                                  supplies `jsi/jsi.h`, and the host function
- *                                  is installed onto the JS global.
- *   PDFCANVAS_WITH_JSI undefined — the standalone build
- *                                  (`./gradlew connectedDebugAndroidTest`).
- *                                  There is no React Native on the classpath and
- *                                  no libjsi.so to link, so `nativeInstall`
- *                                  reports false and the slot storage is
- *                                  compiled on its own.
- *
- * That second configuration is not a stub for its own sake: it is what lets
- * `PdfCanvasJsiTransportTest` prove ON DEVICE that the bytes which become the
- * ArrayBuffer are byte-identical to what the base64 path would have produced.
- * The JNI copy is the only step that could shear a raster, and it is the step
- * both builds share.
- *
- * PLAIN JNI, NO FBJNI. The whole surface is four static methods on one class and
- * one host function; fbjni would add a dependency and a registration dance to
- * express `GetByteArrayRegion`.
- */
-
-#include <android/bitmap.h>
-#include <jni.h>
-
-#include <cstddef>
-#include <cstdint>
-#include <cstring>
-#include <memory>
-#include <mutex>
-#include <unordered_map>
-#include <vector>
-
-#ifdef PDFCANVAS_WITH_JSI
-#include <jsi/jsi.h>
-#endif
-
-namespace {
-
-#ifdef PDFCANVAS_WITH_JSI
-using SlotBufferBase = facebook::jsi::MutableBuffer;
-#else
-/**
- * The two methods `jsi::MutableBuffer` declares, restated so the standalone
- * build compiles the identical storage code with no JSI header in sight. If
- * these ever drift from jsi.h the autolinked build stops compiling, which is the
- * failure mode worth having.
- */
-struct SlotBufferBase {
-  virtual ~SlotBufferBase() = default;
-  virtual size_t size() const = 0;
-  virtual uint8_t* data() = 0;
-};
-#endif
-
-/**
- * One raster's bytes, owned outright.
- *
- * NOT TAKEN, AND MEASURED BEFORE IT IS: `std::vector<uint8_t> bytes_(size)`
- * VALUE-initialises, so constructing this memsets the whole raster to zero and
- * then a fill immediately overwrites every byte of it. That is a second
- * full-raster pass per tile, on the same serialised render executor as the copy
- * it precedes, and a `unique_ptr<uint8_t[]>` from `new uint8_t[size]` would
- * delete it outright.
- *
- * It stays because it buys a real invariant for free: a published slot can never
- * hand JS memory that was not written. Every fill path today writes all `size`
- * bytes BEFORE publishing, so the invariant is already structural rather than
- * incidental — but "already structural" is the sort of thing that stops being
- * true quietly, and the failure mode is a tile of somebody else's heap. Take it
- * only with `PdfCanvasPhaseTimingTest`'s LANES-JSI-DIRECT row measured on both
- * sides of the change.
- */
-class SlotBuffer final : public SlotBufferBase {
- public:
-  explicit SlotBuffer(size_t size) : bytes_(size) {}
-
-  size_t size() const override { return bytes_.size(); }
-  uint8_t* data() override { return bytes_.data(); }
-
- private:
-  std::vector<uint8_t> bytes_;
-};
-
-/**
- * Slots are written on the render executor and read on the JS thread, so the map
- * is guarded. The lock is held only around the map operation itself — never
- * across the allocation or the copy, and never across a JSI call.
- */
-std::mutex g_slotsMutex;
-std::unordered_map<int64_t, std::shared_ptr<SlotBuffer>> g_slots;
-
-/**
- * Publishes a finished buffer, or refuses.
- *
- * REFUSES rather than overwrites when the id is already occupied. Slot ids are
- * monotonic per PROCESS (`PdfCanvasModule.nextSlot` is static for exactly this
- * reason), so a collision cannot happen by design and can only mean the id
- * allocator has been duplicated — in which case overwriting hands one module
- * ANOTHER module's raster, which is a wrong image rather than an error. `false`
- * here means the caller falls back, and the buffer is freed by its shared_ptr.
- *
- * Separate from the fill so the lock is held only around the map operation,
- * never across the allocation or the memcpy.
- */
-bool publishSlot(int64_t slot, std::shared_ptr<SlotBuffer> buffer) {
-  std::lock_guard<std::mutex> lock(g_slotsMutex);
-  if (g_slots.find(slot) != g_slots.end()) {
-    return false;
-  }
-  g_slots.emplace(slot, std::move(buffer));
-  return true;
-}
-
-std::shared_ptr<SlotBuffer> takeSlot(int64_t slot) {
-  std::lock_guard<std::mutex> lock(g_slotsMutex);
-  auto found = g_slots.find(slot);
-  if (found == g_slots.end()) {
-    return nullptr;
-  }
-  std::shared_ptr<SlotBuffer> buffer = std::move(found->second);
-  g_slots.erase(found);
-  return buffer;
-}
-
-/**
- * Raises a Java throwable, so a C++ failure leaves this JNI method as an
- * exception the caller can catch rather than as an unwind into ART.
- */
-void throwJava(JNIEnv* env, const char* className, const char* message) {
-  if (env->ExceptionCheck()) {
-    return;
-  }
-  jclass clazz = env->FindClass(className);
-  if (clazz == nullptr) {
-    // FindClass has already set its own NoClassDefFoundError; nothing better to
-    // report and nothing that may throw from here.
-    return;
-  }
-  env->ThrowNew(clazz, message);
-}
-
-}  // namespace
-
-extern "C" {
-
-JNIEXPORT void JNICALL
-Java_tools_reekon_pdfcanvas_jsi_PdfCanvasPixelBridge_nativeStore(
-    JNIEnv* env,
-    jclass,
-    jlong slot,
-    jbyteArray data) {
-  if (data == nullptr) {
-    throwJava(
-        env, "java/lang/NullPointerException", "nativeStore: bytes is null.");
-    return;
-  }
-  const jsize length = env->GetArrayLength(data);
-  // ALLOCATES, so it can raise a C++ exception: `std::vector` throws
-  // `std::bad_alloc` for a 4 MiB raster under memory pressure, and the map node
-  // allocation can too. (`nativeStoreFromBitmap` allocates as well, but reports
-  // every failure of its own as `false` rather than as a throwable — see there.)
-  //
-  // A C++ exception MUST NOT unwind out of a JNI method: the ART frame below is
-  // not exception-aware, so the unwind reaches `std::terminate` and aborts the
-  // process. It is converted to a Java throwable here because that is what this
-  // method's callers are written to catch — `PdfCanvasModule.installJsiTransport`
-  // catches `Throwable` and returns -1, which declines the whole transport and
-  // leaves base64 in place. So the promised fallback is real.
-  try {
-    auto buffer = std::make_shared<SlotBuffer>(static_cast<size_t>(length));
-    if (length > 0) {
-      // GetByteArrayRegion, not GetPrimitiveArrayCritical: the critical variants
-      // suspend GC for their duration and this is a 4 MiB copy on a worker
-      // thread, which is exactly the shape of call that should not be holding the
-      // collector still.
-      env->GetByteArrayRegion(
-          data, 0, length, reinterpret_cast<jbyte*>(buffer->data()));
-    }
-    std::lock_guard<std::mutex> lock(g_slotsMutex);
-    // Left as an overwriting assignment, deliberately: this is the FALLBACK
-    // transport and the instrumented suite proves its current behaviour. It does
-    // not go through publishSlot's refusal, which is new-path-only.
-    g_slots[static_cast<int64_t>(slot)] = std::move(buffer);
-  } catch (...) {
-    throwJava(
-        env,
-        "java/lang/OutOfMemoryError",
-        "nativeStore: could not park the raster in native memory.");
-  }
-}
-
-/**
- * THE ONE-COPY PATH: a `Bitmap`'s pixels straight into a `SlotBuffer`.
- *
- * Deletes, per tile, one full-raster `new byte[]` on the ART heap and one
- * full-raster memcpy out of it. What is left is the single `memcpy` below, which
- * is the same copy `Bitmap.copyPixelsToBuffer` would have performed — it too is
- * a `memcpy` from `bitmap.getPixels()` through Skia's `AutoBufferPointer`.
- *
- * FAILS BY RETURNING FALSE, NEVER BY THROWING. Every refusal here is a tile that
- * goes out on the `byte[]` path instead, which is the transport that has always
- * worked; `PdfCanvasRasterizer.extract` treats false as "use the heap" and does
- * not distinguish the reasons. So an allocation failure becomes a slower correct
- * tile rather than a `PdfErrorCode`, and if the heap allocation then fails too,
- * THAT is what maps to `OUT_OF_MEMORY` — the same mapping as before this path
- * existed.
- *
- * WHY byteCount IS PASSED IN AND ALSO CROSS-CHECKED. Java has already validated
- * `rowBytes >= width*4` and `byteCount >= rowBytes*height` against the Bitmap's
- * own reported layout, and that validation must stay where it is (before any
- * allocation). `AndroidBitmap_getInfo` reports the stride a SECOND time, from the
- * NDK side, and a disagreement between the two would mean copying a number of
- * bytes the source does not have — a short read at best, a shear at worst. So
- * `stride * height` must equal the count Java asked for, exactly; a mismatch is
- * refused rather than reconciled, because guessing which of the two is right is
- * how a plausible-looking skew ships.
- *
- * The format is checked for the same reason. `Bitmap.Config.ARGB_8888` is named
- * for a packed int and laid out R,G,B,A in memory, which is what the NDK calls
- * `ANDROID_BITMAP_FORMAT_RGBA_8888` and what `RasterPixels.FORMAT_RGBA_8888`
- * declares to the TS side. Asserting it here is what stops that agreement from
- * being an assumption.
- */
-JNIEXPORT jboolean JNICALL
-Java_tools_reekon_pdfcanvas_jsi_PdfCanvasPixelBridge_nativeStoreFromBitmap(
-    JNIEnv* env,
-    jclass,
-    jlong slot,
-    jobject bitmap,
-    jint width,
-    jint height,
-    jint byteCount) {
-  if (bitmap == nullptr || width <= 0 || height <= 0 || byteCount <= 0) {
-    return JNI_FALSE;
-  }
-
-  AndroidBitmapInfo info;
-  if (AndroidBitmap_getInfo(env, bitmap, &info) != ANDROID_BITMAP_RESULT_SUCCESS) {
-    return JNI_FALSE;
-  }
-  if (info.format != ANDROID_BITMAP_FORMAT_RGBA_8888) {
-    return JNI_FALSE;
-  }
-  // The shape the caller is about to DECLARE to the TS side, against the shape
-  // the NDK says this bitmap has. They cannot differ today — the bitmap was
-  // created at exactly pxW x pxH — and checking costs two comparisons, which
-  // is a better price than a raster that is described as one size and holds
-  // another.
-  if (info.width != static_cast<uint32_t>(width) ||
-      info.height != static_cast<uint32_t>(height)) {
-    return JNI_FALSE;
-  }
-  // In 64-bit arithmetic on purpose: stride and height are uint32_t, and a
-  // 32-bit product would wrap before it could disagree with byteCount.
-  const uint64_t reported =
-      static_cast<uint64_t>(info.stride) * static_cast<uint64_t>(info.height);
-  if (reported != static_cast<uint64_t>(byteCount)) {
-    return JNI_FALSE;
-  }
-
-  std::shared_ptr<SlotBuffer> buffer;
-  try {
-    buffer = std::make_shared<SlotBuffer>(static_cast<size_t>(byteCount));
-  } catch (...) {
-    // `std::bad_alloc` for a 4 MiB raster under pressure. A C++ exception must
-    // never unwind out of a JNI method — the ART frame below is not
-    // exception-aware and the unwind reaches `std::terminate` — so it stops here
-    // and becomes a `false`.
-    return JNI_FALSE;
-  }
-
-  void* pixels = nullptr;
-  if (AndroidBitmap_lockPixels(env, bitmap, &pixels) != ANDROID_BITMAP_RESULT_SUCCESS ||
-      pixels == nullptr) {
-    // Nothing to unlock: a failed lock is not balanced by an unlock. `buffer`
-    // is freed by its shared_ptr on the way out and no slot was published.
-    return JNI_FALSE;
-  }
-  std::memcpy(buffer->data(), pixels, static_cast<size_t>(byteCount));
-  // Balanced immediately, and before anything that could throw or return early.
-  // A leaked lock would pin the Bitmap's pixels for the life of the process.
-  AndroidBitmap_unlockPixels(env, bitmap);
-
-  try {
-    // PUBLISHED LAST. Until this line the buffer is reachable only from this
-    // stack frame, so `nativeReleaseAll` on another thread cannot free memory
-    // this method is still writing into. See the header note.
-    if (!publishSlot(static_cast<int64_t>(slot), std::move(buffer))) {
-      return JNI_FALSE;
-    }
-  } catch (...) {
-    // The map node allocation can throw too, and it is inside the lock.
-    return JNI_FALSE;
-  }
-  return JNI_TRUE;
-}
-
-JNIEXPORT void JNICALL
-Java_tools_reekon_pdfcanvas_jsi_PdfCanvasPixelBridge_nativeRelease(
-    JNIEnv*,
-    jclass,
-    jlong slot) {
-  takeSlot(static_cast<int64_t>(slot));
-}
-
-JNIEXPORT void JNICALL
-Java_tools_reekon_pdfcanvas_jsi_PdfCanvasPixelBridge_nativeReleaseAll(
-    JNIEnv*,
-    jclass) {
-  std::unordered_map<int64_t, std::shared_ptr<SlotBuffer>> drained;
-  {
-    std::lock_guard<std::mutex> lock(g_slotsMutex);
-    drained.swap(g_slots);
-  }
-  // Freed outside the lock. Dropping several megabytes of vectors is not
-  // something to do while the JS thread might be waiting on the same mutex.
-}
-
-JNIEXPORT jint JNICALL
-Java_tools_reekon_pdfcanvas_jsi_PdfCanvasPixelBridge_nativeSlotCount(
-    JNIEnv*,
-    jclass) {
-  std::lock_guard<std::mutex> lock(g_slotsMutex);
-  return static_cast<jint>(g_slots.size());
-}
-
-/**
- * The test seam, and the reason the standalone build compiles this file at all.
- *
- * Takes a slot back out as a Java `byte[]` through the SAME storage the
- * ArrayBuffer would have wrapped. An instrumented test can therefore render a
- * tile, store it, take it back, and compare against `Base64.decode` of the same
- * pixels — proving the transport moves the bytes the base64 path moved, without
- * needing a JS runtime or a whole app around it.
- */
-JNIEXPORT jbyteArray JNICALL
-Java_tools_reekon_pdfcanvas_jsi_PdfCanvasPixelBridge_nativeTakeForTest(
-    JNIEnv* env,
-    jclass,
-    jlong slot) {
-  std::shared_ptr<SlotBuffer> buffer = takeSlot(static_cast<int64_t>(slot));
-  if (buffer == nullptr) {
-    return nullptr;
-  }
-  const jsize length = static_cast<jsize>(buffer->size());
-  jbyteArray out = env->NewByteArray(length);
-  if (out == nullptr) {
-    return nullptr;
-  }
-  if (length > 0) {
-    env->SetByteArrayRegion(
-        out, 0, length, reinterpret_cast<const jbyte*>(buffer->data()));
-  }
-  return out;
-}
-
-JNIEXPORT jboolean JNICALL
-Java_tools_reekon_pdfcanvas_jsi_PdfCanvasPixelBridge_nativeInstall(
-    JNIEnv*,
-    jclass,
-    jlong runtimePointer) {
-#ifdef PDFCANVAS_WITH_JSI
-  if (runtimePointer == 0) {
-    return JNI_FALSE;
-  }
-  auto& runtime = *reinterpret_cast<facebook::jsi::Runtime*>(runtimePointer);
-  try {
-    auto name =
-        facebook::jsi::PropNameID::forAscii(runtime, "__pdfCanvasTakePixels");
-    auto take = facebook::jsi::Function::createFromHostFunction(
-        runtime,
-        name,
-        1,
-        [](facebook::jsi::Runtime& rt,
-           const facebook::jsi::Value&,
-           const facebook::jsi::Value* args,
-           size_t count) -> facebook::jsi::Value {
-          if (count < 1 || !args[0].isNumber()) {
-            throw facebook::jsi::JSError(
-                rt, "__pdfCanvasTakePixels(slot): slot must be a number.");
-          }
-          const auto slot = static_cast<int64_t>(args[0].asNumber());
-          std::shared_ptr<SlotBuffer> buffer = takeSlot(slot);
-          if (buffer == nullptr) {
-            // Every slot is taken exactly once, so this means the render that
-            // filled it was torn down (a reload drains every slot) or the same
-            // slot was taken twice. Named rather than silently empty: an empty
-            // ArrayBuffer would reach Skia and draw a black tile.
-            throw facebook::jsi::JSError(
-                rt,
-                "__pdfCanvasTakePixels: no raster is waiting in slot " +
-                    std::to_string(slot) +
-                    ". It was already taken, or the module was invalidated.");
-          }
-          // The ArrayBuffer BORROWS this vector and the shared_ptr keeps it
-          // alive; the slot map has already dropped its reference, so JS is now
-          // the sole owner and the GC is what frees it.
-          return facebook::jsi::Value(
-              rt, facebook::jsi::ArrayBuffer(rt, std::move(buffer)));
-        });
-    runtime.global().setProperty(runtime, name, take);
-    return JNI_TRUE;
-  } catch (...) {
-    // A runtime that refuses to install a host function is a runtime this
-    // package will not use. The JS side falls back to base64.
-    return JNI_FALSE;
-  }
-#else
-  (void)runtimePointer;
-  return JNI_FALSE;
-#endif
-}
-
-}  // extern "C"

package/android/src/jsi/java/tools/reekon/pdfcanvas/jsi/PdfCanvasPixelBridge.java

@@ -1,140 +0,0 @@
-package tools.reekon.pdfcanvas.jsi;
-
-import android.graphics.Bitmap;
-
-/**
- * The Java face of the raster transport — see {@code android/src/jsi/cpp/pdfcanvas-jsi.cpp}.
- *
- * <h3>Why this is its own source set</h3>
- *
- * It is compiled by BOTH builds. {@code src/main} is the React-free rasterizer
- * core and {@code src/reactnative} is the React binding; this is a third thing —
- * React-free like the core, but native, and only half of it is reachable without
- * a React Native runtime. Keeping it separate is what lets the standalone build
- * (which has no ReactAndroid, no libjsi.so, and is the build that runs the
- * instrumented suite) compile the slot storage and prove its byte fidelity,
- * while the autolinked build additionally gets {@link #nativeInstall}.
- *
- * <h3>The contract</h3>
- *
- * A slot is a monotonically increasing id chosen by the caller. The pixels reach
- * C++-owned memory on whatever thread stores them — the render executor, never
- * the JS thread — and are taken exactly once, either by the JS host function
- * {@code __pdfCanvasTakePixels} (which wraps them in a zero-copy ArrayBuffer) or
- * by {@link #nativeTakeForTest}. Taking removes the slot; a slot that is never
- * taken is freed by {@link #nativeReleaseAll}.
- *
- * <p>TWO WAYS IN, and they are not equivalent.
- * {@link #nativeStoreFromBitmap} is the one-copy path: it allocates the native
- * buffer and fills it from the {@code Bitmap}'s own pixels, so no {@code byte[]}
- * is ever allocated. {@link #nativeStore} is the two-copy path, kept because the
- * base64 fallback needs that {@code byte[]} regardless. Prefer the former; use
- * the latter when the bytes are already in a Java array.
- *
- * <h3>Degrading</h3>
- *
- * {@link #isLoaded()} is false when {@code libpdfcanvasjsi.so} is absent from the
- * APK — an older app binary, a build that skipped the native build, an ABI with
- * no artifact. Every caller must treat that as "use base64", because rendering
- * correctly matters more than rendering fast. Nothing here throws to say so.
- */
-public final class PdfCanvasPixelBridge {
-
-  /**
-   * The self-test payload.
-   *
-   * Stored by the module during install and taken by JS before the transport is
-   * enabled, so the first bytes to cross are ones both sides already agree on.
-   * It contains 0x00, 0xFF and a byte above 0x7F on purpose: Java's `byte` is
-   * signed, and a sign-extension slip in the JNI copy or in the ArrayBuffer view
-   * shows up here rather than as a discoloured tile.
-   */
-  public static final byte[] PROBE_BYTES = {
-    0x00, 0x01, 0x02, (byte) 0xFD, (byte) 0xFE, (byte) 0xFF, 0x2A, 0x07
-  };
-
-  private static final boolean LOADED = load();
-
-  private PdfCanvasPixelBridge() {}
-
-  private static boolean load() {
-    try {
-      System.loadLibrary("pdfcanvasjsi");
-      return true;
-    } catch (Throwable t) {
-      // UnsatisfiedLinkError on a build without the native library, and
-      // deliberately not rethrown: the package must still render.
-      return false;
-    }
-  }
-
-  /** Whether {@code libpdfcanvasjsi.so} loaded. False means base64. */
-  public static boolean isLoaded() {
-    return LOADED;
-  }
-
-  /**
-   * Installs {@code globalThis.__pdfCanvasTakePixels} into the JSI runtime.
-   *
-   * MUST be called on the JS thread with a live runtime pointer. Returns false
-   * — never throws — when the library was built without JSI (the standalone
-   * build), when the pointer is null, or when the runtime refuses the host
-   * function.
-   */
-  public static native boolean nativeInstall(long runtimePointer);
-
-  /**
-   * Copies {@code bytes} into C++-owned memory under {@code slot}.
-   *
-   * The bytes are already on the Java heap by the time this is called, so this
-   * is the SECOND full-raster copy of that raster. Use
-   * {@link #nativeStoreFromBitmap} where the source is still a {@code Bitmap}.
-   */
-  public static native void nativeStore(long slot, byte[] bytes);
-
-  /**
-   * Copies a {@code Bitmap}'s pixels DIRECTLY into C++-owned memory under
-   * {@code slot} — one memcpy, and not one byte of Java heap.
-   *
-   * <p>{@code width}, {@code height} and {@code byteCount} are the caller's
-   * already-validated view of the bitmap, and every one of them is cross-checked
-   * against what {@code AndroidBitmap_getInfo} reports for the SAME bitmap. A
-   * disagreement is a refusal rather than a reconciliation: copying a length the
-   * source does not have, or describing a raster as a shape it is not, would
-   * shear the image — which reads as a plausible skew rather than an error.
-   *
-   * <p>RETURNS FALSE INSTEAD OF THROWING, for every failure — a native
-   * allocation that could not be had, a bitmap that would not lock, a format or
-   * stride that did not match, an id already occupied. False means "the raster
-   * is NOT in the slot; fall back to the {@code byte[]} path", and no slot is
-   * left behind to release. The caller must not treat it as an error: the
-   * fallback is the transport that has always worked.
-   *
-   * <p>MUST NOT be called when {@link #isLoaded()} is false — like every native
-   * method here, that is an {@code UnsatisfiedLinkError}, not a {@code false}.
-   *
-   * @param bitmap a mutable, non-recycled {@code ARGB_8888} bitmap. It is locked
-   *     for the duration of the copy and unlocked before this returns.
-   */
-  public static native boolean nativeStoreFromBitmap(
-      long slot, Bitmap bitmap, int width, int height, int byteCount);
-
-  /** Drops one slot if it is still there. */
-  public static native void nativeRelease(long slot);
-
-  /** Drops every slot. Called from {@code PdfCanvasModule.invalidate()}. */
-  public static native void nativeReleaseAll();
-
-  /** Slots currently waiting to be taken. For assertions, not for logic. */
-  public static native int nativeSlotCount();
-
-  /**
-   * Takes a slot back out as a Java array, through the identical storage the
-   * ArrayBuffer would have wrapped. Null when the slot is empty.
-   *
-   * The instrumented suite's only way to check the transport without a JS
-   * runtime, which is why it ships rather than living in androidTest: the JNI
-   * copy under test is the production one.
-   */
-  public static native byte[] nativeTakeForTest(long slot);
-}