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

package/android/build.gradle

@@ -1,29 +1,33 @@
 /*
  * The Android half of @reekon-tools/react-native-pdf-canvas.
  *
+ * WHAT IS BUILT. One shared library, `libpdfcanvas.so`, from the C++ core in
+ * `native/core` plus the JNI surface in `src/main/cpp`, linked against the
+ * prebuilt PDFium this package pins (`scripts/pdfium-manifest.json`). Java is a
+ * thin `PdfCanvasNative` over it, and `PdfCanvasModule` is marshalling over
+ * that. There is no Java rasterizer any more: `android.graphics.pdf.PdfRenderer`
+ * was PDFium behind a wrapper that hid annotations, passwords and cancel, and
+ * the core now talks to PDFium directly — the same release iOS and the web
+ * backend use.
+ *
  * TWO BUILDS, ONE FILE.
  *
  *   standalone  — `cd android && ./gradlew connectedDebugAndroidTest`. Compiles
- *                 `src/main` (the rasterizer core) and `src/androidTest`. There
- *                 is no React Native on the classpath and nothing here asks for
- *                 one. This is the build that PROVES the backend.
+ *                 the core, the JNI and `src/androidTest` with no React Native
+ *                 on the classpath. What it proves is the JNI seam and the
+ *                 transport's byte fidelity on a device; rendering itself is
+ *                 proven on a laptop by `native/tests`.
  *
  *   autolinked  — a React Native app pulls this directory in. `src/reactnative`
- *                 joins the source set and the React dependency is added.
- *
- * The split is not cosmetic. `src/main` is the half that can be tested today on
- * a bare emulator; the moment a React import lands in it, that stops being true
- * and the only way to run the rasterizer is to build a whole app around it.
+ *                 joins the source set, the React dependency is added, and the
+ *                 native build gets `-DPDFCANVAS_WITH_JSI=ON` so the JSI raster
+ *                 transport is compiled in and linked against ReactAndroid's
+ *                 prefab `jsi`.
  *
- * `src/jsi` is a THIRD source set and it joins BOTH builds. It holds the raster
- * transport — a JNI slot store whose contents become a JS ArrayBuffer with no
- * base64 in between. It is React-free like `src/main`, but native, so it is
- * compiled twice with different capabilities: the autolinked build passes
- * `-DPDFCANVAS_WITH_JSI=ON` and links ReactAndroid's prefab `jsi` target, while
- * the standalone build compiles the same file with the JSI half `#ifdef`'d out.
- * That is deliberate rather than a convenience: it is what lets the instrumented
- * suite prove ON DEVICE that the bytes entering the transport are byte-identical
- * to the ones the base64 path produced, with no app anywhere in the picture.
+ * PDFIUM IS FETCHED, NOT VENDORED. `fetchPdfium` runs `scripts/fetch-pdfium.mjs`
+ * before anything native is configured; it downloads exactly the ABIs the app
+ * asked for, verifies each against a pinned SHA-256, and is a stat when done.
+ * See the script for the offline/mirror knobs.
  */
 
 buildscript {
@@ -48,16 +52,12 @@ apply plugin: 'com.android.library'
 def standalone = gradle.ext.has('pdfCanvasStandalone')
 
 /**
- * Which ABIs the transport's .so is built for.
- *
- * Autolinked: whatever the app asked for, so the library never ships an ABI the
- * app does not — a missing .so is a silent fall back to base64 on that device,
- * which is the one failure this list can cause.
+ * Which ABIs are built — and therefore which PDFium binaries are fetched.
  *
- * Standalone: the two the instrumented suite can actually run on. Building four
- * to run one is a minute of NDK time per test cycle for nothing.
+ * Autolinked: whatever the app asked for, so the AAR never carries an ABI the
+ * app does not. Standalone: the two the instrumented suite can actually run on.
  */
-def transportAbis() {
+def targetAbis() {
   if (!gradle.ext.has('pdfCanvasStandalone')) {
     def requested = rootProject.properties.get('reactNativeArchitectures')
     if (requested) {
@@ -68,6 +68,24 @@ def transportAbis() {
   return ['arm64-v8a', 'x86_64']
 }
 
+def packageRoot = file("${projectDir}/..")
+def pdfiumRoot = new File(packageRoot, 'native/.pdfium/android')
+
+/**
+ * Downloads + verifies the pinned PDFium build for `targetAbis()`.
+ *
+ * Runs every build, deliberately: the script checks a stamp and exits in
+ * milliseconds when the right release is already there, and a Gradle
+ * up-to-date check would have to re-derive exactly that logic to be correct.
+ */
+tasks.register('fetchPdfium', Exec) {
+  description = 'Fetches the pinned PDFium binaries for the ABIs being built (scripts/fetch-pdfium.mjs).'
+  workingDir packageRoot
+  commandLine(System.getenv('PDFCANVAS_NODE') ?: 'node',
+      'scripts/fetch-pdfium.mjs', 'android', '--abis', targetAbis().join(','))
+  outputs.upToDateWhen { false }
+}
+
 android {
   namespace 'tools.reekon.pdfcanvas'
   compileSdk 34
@@ -75,8 +93,6 @@ android {
   if (!standalone && rootProject.hasProperty('ndkVersion')) {
     // Mirrors what every other autolinked native module does: take the app's
     // pinned NDK when it has one, and let AGP pick its default when it does not.
-    // Pinning a version here that the machine has not installed is a build
-    // failure in somebody else's project.
     ndkVersion rootProject.ext.ndkVersion
   }
 
@@ -88,28 +104,22 @@ android {
   }
 
   defaultConfig {
-    // 24 is the floor spike S1 measured against. PdfRenderer itself is API 21+,
-    // but 24 is the package's declared minimum and S1 confirmed the off-page
-    // -origin transform is honoured identically there.
+    // PDFium's own floor is far lower; 24 is this package's declared minimum
+    // and what the retired core measured against.
     minSdk 24
     testInstrumentationRunner 'androidx.test.runner.AndroidJUnitRunner'
-    // One test deliberately triggers the API 24 PDFium poisoning (see
-    // PdfCanvasPoisonGuardTest). Once it has, every test scheduled after it in
-    // the same process dies — so it is excluded here and run on its own. The
-    // exclusion is by annotation rather than by class name so that moving the
-    // test cannot silently re-admit it.
-    testInstrumentationRunnerArguments notAnnotation: 'tools.reekon.pdfcanvas.PoisonsTheProcess'
     consumerProguardFiles 'consumer-rules.pro'
 
     externalNativeBuild {
       cmake {
-        // -frtti and -fexceptions are not optional: jsi.h uses both, and a
-        // host function reports failure by throwing jsi::JSError.
+        // -frtti and -fexceptions are not optional: the core throws PdfError,
+        // jsi.h uses both, and a host function reports failure by throwing.
         cppFlags '-O2', '-frtti', '-fexceptions', '-Wall', '-std=c++17'
         arguments "-DANDROID_STL=c++_shared",
             "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON",
+            "-DPDFCANVAS_PDFIUM_ROOT=${pdfiumRoot.absolutePath.replace('\\', '/')}".toString(),
             "-DPDFCANVAS_WITH_JSI=${standalone ? 'OFF' : 'ON'}".toString()
-        abiFilters(*transportAbis())
+        abiFilters(*targetAbis())
       }
     }
   }
@@ -121,19 +131,14 @@ android {
 
   externalNativeBuild {
     cmake {
-      path 'src/jsi/cpp/CMakeLists.txt'
+      path 'src/main/cpp/CMakeLists.txt'
     }
   }
 
   sourceSets {
     main {
-      // The transport is React-free and joins BOTH builds — the standalone one
-      // compiles it with the JSI half switched off and exercises the slot store
-      // directly from androidTest.
-      java.srcDirs += 'src/jsi/java'
       // The React binding is additive. On the standalone path it is not
-      // compiled at all, which is what keeps `src/main` provably React-free:
-      // if a core file ever imports com.facebook.*, this build stops compiling.
+      // compiled at all, which is what keeps `src/main` provably React-free.
       if (!standalone) {
         java.srcDirs += 'src/reactnative/java'
       }
@@ -143,15 +148,13 @@ android {
   if (!standalone) {
     packagingOptions {
       // Everything below is already in the app, shipped by React Native itself.
-      // Packaging a second copy out of this AAR is at best duplicate-file noise
-      // and at worst two libjsi.so with different ABIs in one process.
+      // libjsi.so arrives because AGP packages every IMPORTED shared library a
+      // target links — which is also how libpdfium.so gets in, and that one
+      // must NOT be excluded.
       //
-      // ONLY on the autolinked path. `-DANDROID_STL=c++_shared` means
-      // libpdfcanvasjsi.so has a hard dependency on libc++_shared.so, and the
-      // standalone test APK has no React Native to supply it — excluding it
-      // there makes `System.loadLibrary` fail, `isLoaded()` return false, and
-      // the whole transport silently degrade. Which is precisely the failure
-      // `nativeTransportLibraryIsPresent` exists to catch, and did.
+      // ONLY on the autolinked path: `-DANDROID_STL=c++_shared` gives
+      // libpdfcanvas.so a hard dependency on libc++_shared.so, and the
+      // standalone test APK has no React Native to supply it.
       excludes += ['**/libjsi.so', '**/libc++_shared.so', '**/libreactnative.so']
     }
   }
@@ -161,6 +164,16 @@ android {
   }
 }
 
+afterEvaluate {
+  // PDFium must exist before CMake CONFIGURES (the IMPORTED_LOCATION is checked
+  // then), not merely before it builds. AGP's task names vary by version, so
+  // every native-build task is matched by prefix, and preBuild is wired too.
+  tasks.named('preBuild') { dependsOn(tasks.named('fetchPdfium')) }
+  tasks.matching { task ->
+    ['configureCMake', 'generateJsonModel', 'buildCMake', 'externalNativeBuild'].any { task.name.startsWith(it) }
+  }.configureEach { dependsOn(tasks.named('fetchPdfium')) }
+}
+
 dependencies {
   if (!standalone) {
     // Supplied by the consuming app's React Native version. Never pinned here:

package/android/consumer-rules.pro

@@ -1,3 +1,10 @@
 # The React binding is reached reflectively by React Native's module registry,
 # so R8 cannot see the call site and would strip it from a release build.
 -keep class tools.reekon.pdfcanvas.rn.** { *; }
+
+# JNI resolves `native` methods by their mangled Java name, and the C++ side
+# raises `PdfRasterException.fromWire` by signature. Neither call site is
+# visible to R8, so both names have to survive minification.
+-keepclasseswithmembers class tools.reekon.pdfcanvas.PdfCanvasNative { native <methods>; }
+-keep class tools.reekon.pdfcanvas.PdfRasterException { *; }
+-keep class tools.reekon.pdfcanvas.PdfErrorCode { *; }

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

@@ -0,0 +1,254 @@
+package tools.reekon.pdfcanvas;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertNull;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+
+import android.content.Context;
+
+import androidx.test.ext.junit.runners.AndroidJUnit4;
+import androidx.test.platform.app.InstrumentationRegistry;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+
+import java.io.File;
+
+/**
+ * The JNI seam, on device.
+ *
+ * <h3>What this proves, and what it leaves to the laptop</h3>
+ *
+ * Rendering is proven by {@code native/tests} — 50-odd cases against the same
+ * PDFium build, on a laptop, in under a second. This suite exists for the two
+ * things a laptop cannot show: that {@code libpdfcanvas.so} and the
+ * {@code libpdfium.so} it links load on a real Android runtime for this ABI,
+ * and that bytes cross JNI intact in both directions — a document path in, a
+ * raster out on both transports, an error code out with its type. Every
+ * failure below is either an {@code UnsatisfiedLinkError} or a plausible wrong
+ * image, and neither shows up anywhere but a device.
+ *
+ * <p>This is the STANDALONE build: no React Native, no Hermes, no libjsi.so, so
+ * {@link PdfCanvasNative#installJsi} honestly reports false and the slot store
+ * is exercised through {@link PdfCanvasNative#takeSlotForTest} — the identical
+ * storage the ArrayBuffer would have wrapped.
+ */
+@RunWith(AndroidJUnit4.class)
+public class PdfCanvasNativeTest {
+
+  private long service;
+
+  private static Context ctx() {
+    return InstrumentationRegistry.getInstrumentation().getTargetContext();
+  }
+
+  @Before
+  public void setUp() {
+    assertTrue("libpdfcanvas.so (and the libpdfium.so it links) must load", PdfCanvasNative.isLoaded());
+    PdfCanvasNative.releaseAllSlots();
+    service = PdfCanvasNative.createService();
+    assertTrue(service != 0L);
+  }
+
+  @After
+  public void tearDown() {
+    PdfCanvasNative.invalidateService(service);
+    PdfCanvasNative.releaseAllSlots();
+  }
+
+  private static int channel(byte[] bytes, int rowBytes, int x, int y, int c) {
+    return bytes[y * rowBytes + x * 4 + c] & 0xff;
+  }
+
+  private static void assertPixel(byte[] bytes, int rowBytes, int x, int y, int r, int g, int b) {
+    String actual = "[" + channel(bytes, rowBytes, x, y, 0) + "," + channel(bytes, rowBytes, x, y, 1)
+        + "," + channel(bytes, rowBytes, x, y, 2) + "," + channel(bytes, rowBytes, x, y, 3) + "]";
+    assertTrue("(" + x + "," + y + ") is " + actual + ", expected [" + r + "," + g + "," + b + ",255]",
+        Math.abs(channel(bytes, rowBytes, x, y, 0) - r) <= 4
+            && Math.abs(channel(bytes, rowBytes, x, y, 1) - g) <= 4
+            && Math.abs(channel(bytes, rowBytes, x, y, 2) - b) <= 4
+            && channel(bytes, rowBytes, x, y, 3) == 255);
+  }
+
+  private int open(File file) throws PdfRasterException {
+    double[] opened = PdfCanvasNative.open(service, file.getAbsolutePath(), null, null);
+    assertNotNull(opened);
+    return (int) opened[0];
+  }
+
+  /* ================================================================ *
+   * 1. Bytes in, bytes out
+   * ================================================================ */
+
+  /**
+   * CATCHES: a channel swap (BGRA arriving where RGBA is declared), a stride
+   * shear, a y-flip, or a page geometry that did not survive the double[] hop.
+   * The quadrants are saturated so each of those moves whole pixels.
+   */
+  @Test
+  public void quadrantsCrossJniInRgbaOrder() throws Exception {
+    File pdf = TestPdfs.quadrants(ctx(), "jni-quadrants.pdf", 200, 100);
+    double[] opened = PdfCanvasNative.open(service, pdf.getAbsolutePath(), null, null);
+    assertEquals(1, (int) opened[1]);
+    assertEquals(200.0, opened[2], 0.01);
+    assertEquals(100.0, opened[3], 0.01);
+    int handle = (int) opened[0];
+
+    long[] shape = new long[4];
+    byte[] bytes = PdfCanvasNative.render(
+        service, handle, 0, 0, 0, 200, 100, 2, false, false, 1, false, shape);
+    assertNotNull("a heap render returns bytes", bytes);
+    assertEquals(0L, shape[0]);
+    assertEquals(400L, shape[1]);
+    assertEquals(200L, shape[2]);
+    assertEquals(1600L, shape[3]);
+    assertEquals(1600 * 200, bytes.length);
+    int rowBytes = (int) shape[3];
+    assertPixel(bytes, rowBytes, 20, 20, 0, 0, 255);      // blue: doc top-left
+    assertPixel(bytes, rowBytes, 380, 20, 0, 0, 0);       // black: doc top-right
+    assertPixel(bytes, rowBytes, 20, 180, 255, 0, 0);     // red: doc bottom-left
+    assertPixel(bytes, rowBytes, 380, 180, 0, 255, 0);    // green: doc bottom-right
+    PdfCanvasNative.close(service, handle);
+  }
+
+  /** CATCHES: the annotations flag not surviving the JNI boolean hop. */
+  @Test
+  public void annotationsFlagReachesTheCore() throws Exception {
+    int handle = open(TestPdfs.annotated(ctx(), "jni-annotated.pdf"));
+    long[] shape = new long[4];
+    byte[] with = PdfCanvasNative.render(service, handle, 0, 0, 0, 200, 200, 1, true, false, 1, false, shape);
+    byte[] without = PdfCanvasNative.render(service, handle, 0, 0, 0, 200, 200, 1, false, false, 2, false, shape);
+    int rowBytes = (int) shape[3];
+    assertPixel(with, rowBytes, 100, 100, 0, 255, 0);
+    assertPixel(without, rowBytes, 100, 100, 255, 255, 255);
+    PdfCanvasNative.close(service, handle);
+  }
+
+  /* ================================================================ *
+   * 2. The transport
+   * ================================================================ */
+
+  /**
+   * THE HEADLINE: bytes taken out of a slot are byte-identical to the same
+   * raster rendered to the heap. PDFium wrote the tile straight into the slot
+   * buffer, so a wrong buffer, stride or publish would be a plausible-looking
+   * wrong image rather than an error.
+   */
+  @Test
+  public void slotBytesEqualHeapBytesForARealRaster() throws Exception {
+    int handle = open(TestPdfs.quadrants(ctx(), "jni-slot.pdf", 300, 200));
+    long[] heapShape = new long[4];
+    byte[] heap = PdfCanvasNative.render(service, handle, 0, 37, 23, 64, 41, 4, false, false, 1, false, heapShape);
+    assertNotNull(heap);
+
+    long[] slotShape = new long[4];
+    byte[] none = PdfCanvasNative.render(service, handle, 0, 37, 23, 64, 41, 4, false, false, 2, true, slotShape);
+    assertNull("a slot render returns no bytes", none);
+    assertTrue("a slot render names a slot", slotShape[0] > 0);
+    assertEquals(heapShape[1], slotShape[1]);
+    assertEquals(heapShape[2], slotShape[2]);
+    assertEquals(heapShape[3], slotShape[3]);
+    assertEquals(1, PdfCanvasNative.slotCount());
+
+    byte[] taken = PdfCanvasNative.takeSlotForTest(slotShape[0]);
+    assertNotNull(taken);
+    assertArrayEquals(heap, taken);
+    assertEquals(0, PdfCanvasNative.slotCount());
+    assertNull("a slot is taken exactly once", PdfCanvasNative.takeSlotForTest(slotShape[0]));
+    PdfCanvasNative.close(service, handle);
+  }
+
+  /** The probe the JS side negotiates with round-trips through the real store. */
+  @Test
+  public void probeBytesRoundTrip() {
+    long slot = PdfCanvasNative.storeProbe();
+    assertTrue(slot > 0);
+    byte[] taken = PdfCanvasNative.takeSlotForTest(slot);
+    assertArrayEquals(PdfCanvasNative.PROBE_BYTES, taken);
+  }
+
+  @Test
+  public void releaseDropsASlotAndReleaseAllDrainsEverything() {
+    long a = PdfCanvasNative.storeProbe();
+    long b = PdfCanvasNative.storeProbe();
+    assertEquals(2, PdfCanvasNative.slotCount());
+    PdfCanvasNative.releaseSlot(a);
+    PdfCanvasNative.releaseSlot(a);
+    assertEquals(1, PdfCanvasNative.slotCount());
+    assertNotNull(PdfCanvasNative.takeSlotForTest(b));
+    for (int i = 0; i < 8; i++) {
+      PdfCanvasNative.storeProbe();
+    }
+    PdfCanvasNative.releaseAllSlots();
+    assertEquals(0, PdfCanvasNative.slotCount());
+  }
+
+  /** In the standalone build there is no JSI, and the install must say so rather than dereference. */
+  @Test
+  public void installJsiReportsFalseWithoutAJsiRuntime() {
+    assertFalse(PdfCanvasNative.installJsi(0L));
+  }
+
+  /* ================================================================ *
+   * 3. Errors and cancellation cross with their codes
+   * ================================================================ */
+
+  @Test
+  public void errorsArriveAsTypedExceptions() throws Exception {
+    try {
+      PdfCanvasNative.open(service, TestPdfs.missing(ctx(), "jni-missing.pdf").getAbsolutePath(), null, null);
+      fail("a missing file must throw");
+    } catch (PdfRasterException e) {
+      assertEquals(PdfErrorCode.NOT_FOUND, e.code());
+    }
+    try {
+      PdfCanvasNative.open(service, TestPdfs.notAPdf(ctx(), "jni-not-a-pdf.pdf").getAbsolutePath(), null, null);
+      fail("a non-PDF must throw");
+    } catch (PdfRasterException e) {
+      assertEquals(PdfErrorCode.CORRUPT, e.code());
+    }
+    int handle = open(TestPdfs.quadrants(ctx(), "jni-range.pdf", 40, 40));
+    try {
+      PdfCanvasNative.render(service, handle, 7, 0, 0, 10, 10, 1, false, false, 1, false, new long[4]);
+      fail("an out-of-range page must throw");
+    } catch (PdfRasterException e) {
+      assertEquals(PdfErrorCode.NOT_FOUND, e.code());
+    }
+  }
+
+  @Test
+  public void aRegisteredCancellationIsHonoured() throws Exception {
+    int handle = open(TestPdfs.quadrants(ctx(), "jni-cancel.pdf", 40, 40));
+    PdfCanvasNative.registerCancellation(service, handle, 5);
+    PdfCanvasNative.cancel(service, handle, 5);
+    try {
+      PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, false, false, 5, false, new long[4]);
+      fail("a cancelled render must throw");
+    } catch (PdfRasterException e) {
+      assertEquals(PdfErrorCode.CANCELLED, e.code());
+    }
+    // The signal was consumed: the same token renders fine afterwards.
+    assertNotNull(PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, false, false, 5, false, new long[4]));
+  }
+
+  @Test
+  public void invalidateClosesEverythingAndRefusesAfterwards() throws Exception {
+    int handle = open(TestPdfs.quadrants(ctx(), "jni-invalidate.pdf", 40, 40));
+    PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, false, false, 1, true, new long[4]);
+    assertEquals(1, PdfCanvasNative.slotCount());
+    PdfCanvasNative.invalidateService(service);
+    assertEquals("invalidate drains parked slots", 0, PdfCanvasNative.slotCount());
+    try {
+      PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, false, false, 2, false, new long[4]);
+      fail("a render after invalidate must throw");
+    } catch (PdfRasterException e) {
+      assertEquals(PdfErrorCode.BACKEND_FAILURE, e.code());
+    }
+  }
+}