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

package/android/src/reactnative/java/tools/reekon/pdfcanvas/rn/PdfCanvasModule.java

@@ -0,0 +1,626 @@
+package tools.reekon.pdfcanvas.rn;
+
+import android.content.ContentResolver;
+import android.net.Uri;
+import android.os.ParcelFileDescriptor;
+import android.util.Base64;
+
+import com.facebook.react.bridge.JavaScriptContextHolder;
+import com.facebook.react.bridge.Promise;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.ReadableMap;
+import com.facebook.react.bridge.WritableArray;
+import com.facebook.react.bridge.WritableMap;
+import com.facebook.react.bridge.Arguments;
+
+import java.io.File;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.RejectedExecutionException;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.concurrent.atomic.AtomicLong;
+
+import tools.reekon.pdfcanvas.jsi.PdfCanvasPixelBridge;
+import tools.reekon.pdfcanvas.PageGeometry;
+import tools.reekon.pdfcanvas.PdfCanvasRasterizer;
+import tools.reekon.pdfcanvas.PdfErrorCode;
+import tools.reekon.pdfcanvas.PdfPlatformQuirks;
+import tools.reekon.pdfcanvas.PdfRasterException;
+import tools.reekon.pdfcanvas.RasterCancellation;
+import tools.reekon.pdfcanvas.RasterPixels;
+import tools.reekon.pdfcanvas.RasterRequest;
+
+/**
+ * MARSHALLING ONLY.
+ *
+ * Every line here converts a type, resolves a URI, picks a thread or rejects a
+ * promise. Not one of them decides anything about rasterizing — that all lives
+ * in {@code tools.reekon.pdfcanvas}, which has no React imports and is proven on
+ * device by {@code ./gradlew connectedDebugAndroidTest} with no app in the
+ * picture. Keeping the split sharp is the point: this file cannot be tested
+ * without building a whole React Native app, so it must not be somewhere
+ * behaviour hides.
+ *
+ * <h3>The transport</h3>
+ *
+ * TWO OF THEM, chosen at runtime, and the fast one has to earn it.
+ *
+ * <p>BASE64 is the original and is still the fallback. It is the honest cost of a
+ * classic bridge module: neither the legacy bridge nor new-architecture codegen
+ * has a binary type. Measured on an LG V60, one 1024x1024 tile costs 19.88 ms to
+ * encode here, ~72.6 ms of string marshalling, and <b>1005.46 ms</b> of
+ * {@code decodeBase64} in Hermes — 90.6% of the tile, spent undoing an encode
+ * that finished a moment earlier.
+ *
+ * <p>JSI ARRAYBUFFER is the fast one. The raster is written STRAIGHT from the
+ * {@code Bitmap} into C++-owned memory on this render's worker thread — see
+ * {@link PdfCanvasRasterizer#renderToNativeSlot}, which asks
+ * {@link PdfCanvasPixelBridge#nativeStoreFromBitmap} to do it in one memcpy — the
+ * promise resolves with a {@code pixelsSlot} number instead of a string, and JS
+ * calls the installed {@code __pdfCanvasTakePixels(slot)} host function to
+ * receive an ArrayBuffer that WRAPS that memory. No string, no decode, nothing
+ * copied on the JS thread, and no {@code byte[]} on the Java heap at all.
+ *
+ * <p>THE SLOT IS ASKED FOR BEFORE THE RASTER EXISTS, which is what makes that
+ * possible: the bitmap is alive only inside the rasterizer, so the decision of
+ * where the pixels land has to travel down rather than the pixels travelling up.
+ * The consequence is that this file, not the rasterizer, owns every path where a
+ * FILLED slot is abandoned — and each one must release it or leak a whole raster
+ * of native memory. They are enumerated at {@link #render}.
+ *
+ * <p>It is selected by {@link #installJsiTransport} + {@link #enableJsiTransport},
+ * never assumed: install returns a probe slot, JS takes it and checks the bytes
+ * against {@link PdfCanvasPixelBridge#PROBE_BYTES}, and only a JS-side match
+ * turns {@link #jsiEnabled} on. A build with no {@code libpdfcanvasjsi.so}, a
+ * runtime that refuses the host function, or a Hermes that will not make an
+ * ArrayBuffer out of a {@code MutableBuffer} all leave the flag off and every
+ * render goes back to base64. Rendering correctly is worth more than rendering
+ * fast.
+ *
+ * <h3>Threading</h3>
+ *
+ * {@code @ReactMethod} runs on the bridge's native-modules thread, and
+ * {@code PdfRenderer.render} is a long synchronous call, so every render is
+ * handed to an executor sized to the renderer pool. Rendering on the caller's
+ * thread would block every other native module for the length of an ARCH-D
+ * raster.
+ *
+ * EVERY {@code ReadableMap} IS DRAINED ON THE CALLING THREAD, before the
+ * executor is handed anything. On the legacy bridge a {@code ReadableNativeMap}
+ * is a thin Java shell over C++ memory that is only contractually valid for the
+ * duration of the {@code @ReactMethod} call; reading it from a worker after the
+ * method has returned is a use-after-free that presents as garbage values or a
+ * native crash, and never as an exception you could map to a
+ * {@code PdfErrorCode}. So each method marshals to plain Java values first and
+ * the lambda closes over those.
+ *
+ * <h3>UNVERIFIED</h3>
+ *
+ * Nothing in this file has ever been compiled or run — that needs a build of a
+ * consuming app. The three fixes marked {@code UNVERIFIED FIX} below were made
+ * by inspection against the bridge's documented contracts, not observed. Treat
+ * them, and the rest of this file, as unreviewed code that happens to be
+ * type-correct.
+ */
+public class PdfCanvasModule extends ReactContextBaseJavaModule {
+
+  public static final String NAME = "PdfCanvas";
+
+  /** Mirrors the native pool ceiling; see PdfRendererPool.MAX_POOL_SIZE. */
+  private static final int MAX_POOL_SIZE = 4;
+
+  private final ReactApplicationContext reactContext;
+  private final Map<Integer, PdfCanvasRasterizer> handles = new ConcurrentHashMap<>();
+  /** Keyed by (handle, token) so a token is only meaningful with its handle. */
+  private final Map<Long, RasterCancellation> signals = new ConcurrentHashMap<>();
+  private final AtomicInteger nextHandle = new AtomicInteger(1);
+  private final ExecutorService renderExecutor =
+      Executors.newFixedThreadPool(MAX_POOL_SIZE);
+
+  /**
+   * Slot ids for the JSI transport. Monotonic and deliberately NOT keyed by
+   * handle: a slot is written and taken within one render, and reusing ids would
+   * let a late take collect a live raster.
+   *
+   * STATIC, because the map it keys is static. The slots live in one
+   * process-wide {@code std::unordered_map} in {@code pdfcanvas-jsi.cpp}, so a
+   * per-instance counter starting at 1 would hand the SAME id to two module
+   * instances — and RN builds a fresh set of native modules for every reload
+   * while the outgoing one may still have rasters parked. The second store then
+   * silently replaces the first module's buffer, and that module's take returns
+   * ANOTHER tile's pixels: a wrong image, not an error. One counter per process
+   * is what makes "taken exactly once" true of the storage rather than of a
+   * single module.
+   */
+  private static final AtomicLong nextSlot = new AtomicLong(1);
+
+  /**
+   * Whether renders return a slot instead of a base64 string.
+   *
+   * Volatile because it is written on the JS thread (by {@link
+   * #enableJsiTransport}, and by a render worker that just watched the native
+   * store fail) and read on the bridge thread by every {@link #render}.
+   *
+   * FALSE UNTIL PROVEN. It is never set by this class deciding the fast path
+   * looks available; it is set by JS after a byte-for-byte round trip of {@link
+   * PdfCanvasPixelBridge#PROBE_BYTES}.
+   */
+  private volatile boolean jsiEnabled = false;
+
+  public PdfCanvasModule(ReactApplicationContext context) {
+    super(context);
+    this.reactContext = context;
+  }
+
+  @Override
+  public String getName() {
+    return NAME;
+  }
+
+  @Override
+  public void invalidate() {
+    // FIRST, before the executor is touched, so no render that has not yet
+    // STARTED can ask for a slot.
+    //
+    // IT NO LONGER DIVERTS A RENDER ALREADY IN FLIGHT, and it used to. The flag
+    // was read AFTER the raster came back (the old putPixelsSlot), so clearing
+    // it here made an in-flight worker fall back to base64 and strand nothing.
+    // render() now reads it BEFORE the draw, because the fill happens inside the
+    // rasterizer while the Bitmap is still alive — so a worker already inside
+    // PdfRenderer.render (uninterruptible; shutdownNow only sets the flag) holds
+    // a slot id already, and will publish its raster after the nativeReleaseAll
+    // below has run past. Nothing takes it, and it is freed by the NEXT
+    // invalidate() rather than by this one.
+    //
+    // Bounded — at most one raster per busy lane, dev-only (Fast Refresh), and
+    // reclaimed on the following reload. NOT closed by re-reading the flag after
+    // the render: negotiateTransport in a SECOND JS runtime calls
+    // enableJsiTransport(false) on this same shared flag while the first
+    // runtime's renders are in flight, so freeing on a cleared flag would hand
+    // that runtime an unredeemable slot instead of a tile. Closing it properly
+    // needs a teardown epoch the rasterizer can see, which is not this change.
+    jsiEnabled = false;
+    // A reload drops the JS side without ever calling close(), so every open
+    // document would otherwise keep its file descriptors and parsed pages until
+    // the process dies. Fast Refresh makes that happen dozens of times a day.
+    for (PdfCanvasRasterizer rasterizer : handles.values()) {
+      rasterizer.close();
+    }
+    handles.clear();
+    signals.clear();
+    renderExecutor.shutdownNow();
+    // A reload also strands any slot whose promise resolved but whose JS
+    // continuation never ran. Each one is a whole raster — megabytes — held in
+    // C++ with nothing left that could ever take it.
+    if (PdfCanvasPixelBridge.isLoaded()) {
+      PdfCanvasPixelBridge.nativeReleaseAll();
+    }
+    super.invalidate();
+  }
+
+  /* ---------------------------------------------------------------- *
+   * transport
+   * ---------------------------------------------------------------- */
+
+  /**
+   * Installs the JSI host function and parks one probe raster for JS to take.
+   *
+   * SYNCHRONOUS on purpose, and that is load-bearing twice over. A blocking
+   * synchronous {@code @ReactMethod} executes ON THE JS THREAD, which is the
+   * only thread where {@code JavaScriptContextHolder.get()} is a live pointer
+   * rather than a value that may already have been torn down. It also means the
+   * whole probe — install, take, enable — completes before the JS module that
+   * called it finishes evaluating, so no render can ever race the decision.
+   *
+   * <h3>What the probe covers, and what it does not</h3>
+   *
+   * It round-trips {@link PdfCanvasPixelBridge#PROBE_BYTES} through
+   * {@code nativeStore} — the {@code byte[]} store — because a probe needs bytes
+   * both sides already agree on and there is no Bitmap at install time. So it
+   * proves the JS HALF: the library loaded, the host function is installed,
+   * Hermes will build an ArrayBuffer over a {@code MutableBuffer}, and byte
+   * values survive the view unmangled.
+   *
+   * <p>It does NOT exercise the fill every subsequent raster uses.
+   * {@code nativeStoreFromBitmap} is a different memcpy from a different source,
+   * and its fidelity is proven on device by
+   * {@code PdfCanvasJsiTransportTest.directFillBytesEqualTheHeapPathForARealRaster}
+   * instead — in the standalone build, with no app around it. Worth knowing when
+   * reading a bug report: a passing probe says nothing about the fill.
+   *
+   * @return the probe slot id, or -1 if the fast path is unavailable. Never
+   *     throws: every failure here is a fallback, not an error.
+   */
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  public double installJsiTransport() {
+    try {
+      if (!PdfCanvasPixelBridge.isLoaded()) {
+        return -1;
+      }
+      JavaScriptContextHolder holder = getReactApplicationContext().getJavaScriptContextHolder();
+      if (holder == null || holder.get() == 0) {
+        return -1;
+      }
+      if (!PdfCanvasPixelBridge.nativeInstall(holder.get())) {
+        return -1;
+      }
+      long slot = nextSlot.getAndIncrement();
+      PdfCanvasPixelBridge.nativeStore(slot, PdfCanvasPixelBridge.PROBE_BYTES);
+      return (double) slot;
+    } catch (Throwable t) {
+      return -1;
+    }
+  }
+
+  /**
+   * Turns the fast transport on, once JS has verified the probe bytes.
+   *
+   * Synchronous for the same reason as {@link #installJsiTransport}: an async
+   * call would be ordered before any render, but "ordered before" is a property
+   * of the bridge queue, and this decision is too cheap to make it depend on one.
+   *
+   * @return the flag as it now stands, so the caller reports what is really live
+   *     rather than what it asked for.
+   */
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  public boolean enableJsiTransport(boolean enabled) {
+    jsiEnabled = enabled && PdfCanvasPixelBridge.isLoaded();
+    return jsiEnabled;
+  }
+
+  /* ---------------------------------------------------------------- *
+   * open
+   * ---------------------------------------------------------------- */
+
+  @ReactMethod
+  public void open(ReadableMap source, int poolSize, Promise promise) {
+    // UNVERIFIED FIX (1 of 3): drained HERE, on the bridge thread, not inside
+    // the executor lambda. `source` is a ReadableNativeMap whose backing native
+    // data is only guaranteed valid for the duration of this call.
+    final String password = source.hasKey("password") ? source.getString("password") : null;
+    final String base64 = source.hasKey("base64") ? source.getString("base64") : null;
+    final String uri = source.hasKey("uri") ? source.getString("uri") : null;
+    final int clamped = Math.max(1, Math.min(MAX_POOL_SIZE, poolSize));
+
+    try {
+      renderExecutor.execute(
+          () -> {
+            PdfCanvasRasterizer rasterizer = null;
+            boolean published = false;
+            try {
+              if (base64 != null) {
+                byte[] data = Base64.decode(base64, Base64.DEFAULT);
+                rasterizer =
+                    PdfCanvasRasterizer.openBytes(
+                        reactContext.getCacheDir(), data, password, clamped);
+              } else {
+                rasterizer = PdfCanvasRasterizer.openFile(resolve(uri), password, clamped);
+              }
+
+              // UNVERIFIED FIX (2 of 3): everything that can still throw happens
+              // BEFORE the rasterizer is published to `handles` and before the
+              // promise is resolved. It used to be registered immediately after
+              // opening, so a throw in the geometry loop (or an OOM building the
+              // result map) rejected the promise while leaving an open rasterizer
+              // — file descriptors and parsed pages — that JS had no handle for
+              // and could never close. The `published` flag is what makes the
+              // finally able to tell "handed over" from "still ours".
+              WritableArray pages = Arguments.createArray();
+              for (int i = 0; i < rasterizer.pageCount(); i++) {
+                PageGeometry g = rasterizer.pageGeometry(i);
+                WritableMap page = Arguments.createMap();
+                page.putInt("index", g.index);
+                page.putInt("width", g.widthPoints);
+                page.putInt("height", g.heightPoints);
+                page.putInt("rotation", g.rotationDegrees);
+                pages.pushMap(page);
+              }
+
+              WritableMap result = Arguments.createMap();
+              result.putInt("pageCount", rasterizer.pageCount());
+              result.putArray("pages", pages);
+              result.putString(
+                  "rotationSupport",
+                  PdfCanvasRasterizer.rotationSupport(reactContext.getCacheDir())
+                      .name()
+                      .toLowerCase(java.util.Locale.US));
+
+              int handle = nextHandle.getAndIncrement();
+              result.putInt("handle", handle);
+              handles.put(handle, rasterizer);
+              published = true;
+              promise.resolve(result);
+            } catch (PdfRasterException e) {
+              reject(promise, e);
+            } catch (Throwable t) {
+              reject(promise, PdfErrorCode.BACKEND_FAILURE, t);
+            } finally {
+              if (rasterizer != null && !published) {
+                rasterizer.close();
+              }
+            }
+          });
+    } catch (RejectedExecutionException e) {
+      // invalidate() shut the executor down. Without this the task never runs
+      // and the promise never settles, which on the JS side is an `await` that
+      // hangs for the life of the app rather than an error anyone can see.
+      reject(promise, PdfErrorCode.BACKEND_FAILURE, e);
+    }
+  }
+
+  /**
+   * Accepts a plain path, a {@code file://} URI, or a {@code content://} URI.
+   *
+   * A content URI has no path this process can open, so it is copied into the
+   * cache first. That copy is deliberate and unavoidable: {@code PdfRenderer}
+   * needs a SEEKABLE descriptor, and a document provider is free to hand back a
+   * pipe. It is also why a host that already has a file path should pass one.
+   */
+  private File resolve(String uri) throws PdfRasterException {
+    if (uri == null || uri.isEmpty()) {
+      throw new PdfRasterException(PdfErrorCode.NOT_FOUND, "No document uri was given.");
+    }
+    if (uri.startsWith("content://")) {
+      return copyContentUri(Uri.parse(uri));
+    }
+    if (uri.startsWith("file://")) {
+      return new File(Uri.parse(uri).getPath());
+    }
+    return new File(uri);
+  }
+
+  private File copyContentUri(Uri uri) throws PdfRasterException {
+    ContentResolver resolver = reactContext.getContentResolver();
+    File out;
+    try {
+      out = File.createTempFile("pdfcanvas-content-", ".pdf", reactContext.getCacheDir());
+      try (ParcelFileDescriptor pfd = resolver.openFileDescriptor(uri, "r");
+          InputStream in = new ParcelFileDescriptor.AutoCloseInputStream(pfd);
+          FileOutputStream fos = new FileOutputStream(out)) {
+        byte[] buffer = new byte[64 * 1024];
+        int n;
+        while ((n = in.read(buffer)) > 0) {
+          fos.write(buffer, 0, n);
+        }
+      }
+    } catch (SecurityException e) {
+      throw new PdfRasterException(
+          PdfErrorCode.NOT_FOUND, "No permission to read " + uri + ".", e);
+    } catch (IOException e) {
+      throw new PdfRasterException(PdfErrorCode.NOT_FOUND, "Could not read " + uri + ".", e);
+    }
+    return out;
+  }
+
+  /* ---------------------------------------------------------------- *
+   * render
+   * ---------------------------------------------------------------- */
+
+  @ReactMethod
+  public void render(int handle, ReadableMap request, int token, Promise promise) {
+    PdfCanvasRasterizer rasterizer = handles.get(handle);
+    if (rasterizer == null) {
+      promise.reject(
+          PdfErrorCode.BACKEND_FAILURE.wire(), "No open document for handle " + handle + ".");
+      return;
+    }
+
+    // UNVERIFIED FIX (1 of 3, second half): the whole request is turned into a
+    // plain Java object HERE, on the bridge thread. Reading `request` inside the
+    // executor lambda meant touching a ReadableNativeMap after the
+    // @ReactMethod had returned and its native backing was free to go.
+    final RasterRequest req;
+    try {
+      req =
+          new RasterRequest(
+              request.getInt("page"),
+              (float) request.getDouble("x"),
+              (float) request.getDouble("y"),
+              (float) request.getDouble("width"),
+              (float) request.getDouble("height"),
+              (float) request.getDouble("scale"),
+              !request.hasKey("annotations") || request.getBoolean("annotations"),
+              "transparent".equals(request.getString("background"))
+                  ? RasterRequest.BACKGROUND_TRANSPARENT
+                  : RasterRequest.BACKGROUND_WHITE);
+    } catch (RuntimeException e) {
+      // A malformed request map (missing key, wrong type) now fails here rather
+      // than on a worker, which is where it belongs: nothing has been allocated
+      // and no signal has been registered yet, so there is nothing to unwind.
+      reject(promise, PdfErrorCode.BACKEND_FAILURE, e);
+      return;
+    }
+
+    long key = signalKey(handle, token);
+    // Registered BEFORE the executor runs, and synchronously on the bridge
+    // thread. That ordering is what lets cancel() be a pure lookup: bridge calls
+    // for one module are executed in the order JS made them, and JS cannot
+    // cancel a token before the render() that issued it, so by the time any
+    // cancel for this key arrives this entry already exists.
+    final RasterCancellation signal = new RasterCancellation();
+    signals.put(key, signal);
+
+    try {
+      renderExecutor.execute(
+          () -> {
+            RasterPixels pixels = null;
+            boolean handedOff = false;
+            try {
+              // Read ONCE. `jsiEnabled` is volatile and invalidate() clears it,
+              // so reading it twice could ask for a slot and then decide not to
+              // look for one — which is exactly how a filled slot is stranded.
+              final boolean fast = jsiEnabled;
+              pixels =
+                  fast
+                      ? rasterizer.renderToNativeSlot(req, signal, nextSlot.getAndIncrement())
+                      : rasterizer.render(req, signal);
+
+              WritableMap result = Arguments.createMap();
+              // ONE of the two, never both — `android.ts` branches on which key
+              // is present, and sending both would mean paying for the encode
+              // this whole path exists to delete.
+              //
+              // The branch is on WHERE THE PIXELS ARE, not on what was asked
+              // for: renderToNativeSlot falls back to the heap whenever the
+              // native store refuses, and that tile still has to go out.
+              if (pixels.isInNativeSlot()) {
+                // A double, because that is what a WritableMap number is on the
+                // way to JS. Slots are consumed within one render, so the 2^53
+                // exact-integer ceiling is not reachable in any session that
+                // could also survive the file descriptors.
+                result.putDouble("pixelsSlot", (double) pixels.slot);
+              } else {
+                result.putString("base64", Base64.encodeToString(pixels.bytes, Base64.NO_WRAP));
+              }
+              result.putInt("width", pixels.width);
+              result.putInt("height", pixels.height);
+              // Passed through, never recomputed as width*4 on either side of
+              // the bridge. A wrong stride shears the image rather than failing.
+              result.putInt("rowBytes", pixels.rowBytes);
+              result.putString("format", pixels.format);
+              promise.resolve(result);
+              // ONLY NOW. Everything that could throw is behind us and the slot
+              // id has reached JS, so from here the ArrayBuffer's take is what
+              // frees it and this thread must not.
+              handedOff = true;
+            } catch (PdfRasterException e) {
+              reject(promise, e);
+            } catch (Throwable t) {
+              reject(promise, PdfErrorCode.BACKEND_FAILURE, t);
+            } finally {
+              // THE ABANDON PATHS, all three of them, and each one leaks a whole
+              // raster of native memory without this:
+              //
+              //   1. Arguments.createMap() or a put* throws (OOM, or a bridge
+              //      torn down under us) after the slot was filled.
+              //   2. promise.resolve throws, or the promise was already settled.
+              //   3. NOT the render throwing after it filled the slot: `pixels`
+              //      is still null on that path, so this cannot release it. The
+              //      rasterizer owns that one — the post-draw cancellation check
+              //      releases its own slot before rethrowing.
+              //
+              // Also NOT covered, and the two cases differ by WHEN the reload
+              // lands: a slot id that reaches JS whose continuation never runs
+              // is reclaimed by nativeReleaseAll() in invalidate(); a slot
+              // published AFTER that nativeReleaseAll — this worker was already
+              // mid-draw when the reload started — waits for the NEXT one. See
+              // the note at invalidate().
+              if (pixels != null && !handedOff) {
+                pixels.release();
+              }
+              signals.remove(key);
+            }
+          });
+    } catch (RejectedExecutionException e) {
+      // invalidate() shut the executor down between the handle lookup and here.
+      // The task will never run, so its finally will never remove the entry —
+      // the same leak the cancel() fix closes, reached from the other side.
+      signals.remove(key);
+      reject(promise, PdfErrorCode.BACKEND_FAILURE, e);
+    }
+  }
+
+  /**
+   * Best-effort, and the JS side is told so via
+   * {@code capabilities.interruptibleRender: false}. This can stop a queued
+   * render starting and can discard a finished one; it cannot interrupt
+   * {@code PdfRenderer.render}.
+   *
+   * UNVERIFIED FIX (3 of 3): a pure LOOKUP. It used to do
+   * {@code signals.putIfAbsent(key, cancelled)} when no signal was registered,
+   * on the theory that the cancel had beaten its render across the bridge — but
+   * "no signal registered" is also, and far more commonly, what a cancel that
+   * arrives AFTER its render finished and cleaned up looks like. The two are
+   * indistinguishable from here, so every late cancel — and a superseded raster
+   * epoch produces a stream of them — planted an entry that nothing ever removed.
+   * {@code signals} grew for the life of the module.
+   *
+   * The speculative branch is not needed anyway: {@link #render} registers its
+   * signal synchronously on this same bridge thread before returning, calls from
+   * one JS module execute in the order they were made, and a token only exists
+   * because a render() issued it. A cancel therefore cannot arrive before the
+   * entry it is looking for. If that ordering assumption is ever wrong the cost
+   * is one missed cancel on a render that was about to be discarded anyway —
+   * which is what "best-effort" already promises — and not unbounded growth.
+   */
+  @ReactMethod
+  public void cancel(int handle, int token) {
+    RasterCancellation signal = signals.get(signalKey(handle, token));
+    if (signal != null) {
+      signal.cancel();
+    }
+  }
+
+  @ReactMethod
+  public void close(int handle) {
+    PdfCanvasRasterizer rasterizer = handles.remove(handle);
+    if (rasterizer != null) {
+      rasterizer.close();
+    }
+  }
+
+  /** Exposed so a host can warn before showing a rotated page wrongly. */
+  @ReactMethod
+  public void rotationSupport(Promise promise) {
+    promise.resolve(
+        PdfCanvasRasterizer.rotationSupport(reactContext.getCacheDir())
+            .name()
+            .toLowerCase(java.util.Locale.US));
+  }
+
+  /** True once this process has hit the API 24 PDFium poisoning. */
+  @ReactMethod
+  public void isBackendPoisoned(Promise promise) {
+    promise.resolve(PdfPlatformQuirks.isBackendPoisoned());
+  }
+
+  /*
+   * WHY THERE IS NO LONGER A putPixelsSlot().
+   *
+   * It used to park a finished {@code byte[]} in a slot AFTER the render
+   * returned, which is the only place it could: the module had pixels, not a
+   * bitmap. That cost a full-raster ART allocation and a full-raster memcpy per
+   * tile, both on the render executor — the serialised bottleneck. The slot is
+   * now requested BEFORE the raster is drawn (see {@link #render}) so the fill
+   * happens once, straight out of the Bitmap.
+   *
+   * ONE BEHAVIOUR WENT WITH IT, deliberately. That method latched
+   * {@code jsiEnabled = false} on any failure, reasoning that a store which threw
+   * once will throw again. The new path does not: a refusal is reported as a
+   * heap-backed raster that has ALREADY gone out correctly on base64, so there is
+   * nothing to salvage by downgrading the whole session. Latching on a transient
+   * allocation failure would trade one slow tile for every subsequent tile being
+   * slow — and the base64 tile that prompted it costs ~1 s of Hermes on the
+   * measured device, which is a cliff worth not falling off twice. A permanent
+   * refusal (a format or stride the native side rejects) costs one cheap failed
+   * JNI call per tile, not a copy.
+   */
+
+  /* ---------------------------------------------------------------- */
+
+  private static long signalKey(int handle, int token) {
+    return (((long) handle) << 32) | (token & 0xffffffffL);
+  }
+
+  /**
+   * The error CODE is the promise's rejection code, verbatim from
+   * {@link PdfErrorCode#wire()} — which is the TypeScript {@code PdfErrorCode}
+   * union member. React Native surfaces it as {@code error.code}, and
+   * {@code src/rasterizer/android.ts} reconstructs a {@code PdfError} from it
+   * with no translation table in between.
+   */
+  private static void reject(Promise promise, PdfRasterException e) {
+    promise.reject(e.code().wire(), e.getMessage(), e);
+  }
+
+  private static void reject(Promise promise, PdfErrorCode code, Throwable t) {
+    promise.reject(code.wire(), String.valueOf(t.getMessage()), t);
+  }
+}

package/android/src/reactnative/java/tools/reekon/pdfcanvas/rn/PdfCanvasPackage.java

@@ -0,0 +1,33 @@
+package tools.reekon.pdfcanvas.rn;
+
+import com.facebook.react.ReactPackage;
+import com.facebook.react.bridge.NativeModule;
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.uimanager.ViewManager;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+
+/**
+ * Autolinking entry point.
+ *
+ * No view managers: the package owns no canvas. Pages come back as pixels and
+ * the HOST draws them inside its own Skia scene — that is the whole premise of
+ * `@reekon-tools/react-native-pdf-canvas`, and a native view here would quietly
+ * contradict it.
+ */
+public class PdfCanvasPackage implements ReactPackage {
+
+  @Override
+  public List<NativeModule> createNativeModules(ReactApplicationContext context) {
+    List<NativeModule> modules = new ArrayList<>();
+    modules.add(new PdfCanvasModule(context));
+    return modules;
+  }
+
+  @Override
+  public List<ViewManager> createViewManagers(ReactApplicationContext context) {
+    return Collections.emptyList();
+  }
+}