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

package/README.md

@@ -50,15 +50,16 @@ and drawing review, and form overlays.
 
 The package supplies no viewer chrome — no scroll view, page controls or navigation — and
 deliberately requires the host to provide the canvas, the gesture handling and the page layout.
-It does not extract text, perform search, or modify documents; its function is rasterization.
+It does not extract text or modify documents. Beyond finding text on a page (see "Text search"),
+its function is rasterization.
 
 ## Project status
 
-Version 0.2.0 is a pre-release. The core, the cadence controller, the React layer and a
-deterministic fake backend are implemented and tested. All three platform backends render with
-PDFium, so annotations, form fields, passwords and page rotation behave identically on each. The
-native core is covered by a host-machine C++ suite, and the web backend by 45 tests driving real
-PDFium WebAssembly under Node.
+Version 0.4.0 is a pre-release. The core, the cadence controller, the React layer and a
+deterministic fake backend are implemented and tested. All three platform backends render and
+search with PDFium, so annotations, form fields, passwords, page rotation and text search behave
+identically on each. The native core is covered by a host-machine C++ suite, and the web backend
+by suites driving real PDFium WebAssembly under Node.
 
 Two areas remain unverified: the web backend has not yet been exercised in a browser, and the
 iOS binding requires a device pass.
@@ -250,6 +251,60 @@ usePdfLayer({document, policy: {sharpnessBand: 1.2, quietZoomMs: 400}});
 observed p95 raster time. A value set too low permits a user adjusting the zoom to supersede
 each render before it completes.
 
+### Page rotation
+
+A host may show a page turned a quarter, half or three-quarter turn clockwise on top of the
+document's own `/Rotate`, per page:
+
+```ts
+// Page 0 shown turned 90° clockwise; pages without an entry stay upright.
+usePdfLayer({document, rotations: [90]});
+// A matching thumbnail. `widthPx` is the width of the TURNED raster.
+document.renderPage(0, {widthPx: 160, rotation: 90});
+```
+
+Doc space for a turned page is the turned page's: a 612x792 page at 90 is laid out as 792x612,
+`content.pages[i].pageRect` reports that rect, and anything the host draws over the page is
+positioned in the same space. Changing a page's rotation rebuilds the layer's raster cache,
+exactly as changing `annotations` does.
+
+### Text search
+
+`PdfDocument.searchPage` finds every occurrence of a string on one page, in reading order:
+
+```tsx
+const controller = new AbortController(); // abort it on the next keystroke
+const hits = await document.searchPage(pageIndex, query, {
+  wholeWord: true, // default false; `matchCase` likewise
+  rotation: 90, // the SAME rotation the page's layer uses; default 0
+  signal: controller.signal,
+});
+
+// Inside the same <Group transform={worldTransform}> as the PdfContentView.
+// Rects are PAGE-LOCAL: offset them by the page's rect in the layout.
+const {pageRect} = content.pages[pageIndex];
+hits
+  .flatMap(hit => hit.rects)
+  .map((r, i) => (
+    <Rect
+      key={i}
+      x={pageRect.x + r.x}
+      y={pageRect.y + r.y}
+      width={r.width}
+      height={r.height}
+      color="rgba(255, 200, 0, 0.35)"
+    />
+  ));
+```
+
+Each `TextMatch` carries `charIndex` / `charCount` (PDFium's character offsets on the page),
+`context` (about 40 characters either side, whitespace collapsed, for a results list) and `rects`:
+one per text line the match spans, in PDF points with the origin at the **displayed** page's
+top-left and y pointing down, with the host rotation applied. That is the space the page's own
+rasters are drawn in, so a highlight lands on the glyphs with no conversion. An empty or
+whitespace-only query resolves `[]` without asking the backend. Every shipped backend declares
+`capabilities.search`, and the fake searches the per-page `text` it is given.
+
 ## Platform support
 
 | Platform | Engine                                        | Backend identifier |

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

@@ -102,7 +102,7 @@ public class PdfCanvasNativeTest {
 
     long[] shape = new long[4];
     byte[] bytes = PdfCanvasNative.render(
-        service, handle, 0, 0, 0, 200, 100, 2, false, false, 1, false, shape);
+        service, handle, 0, 0, 0, 200, 100, 2, 0, false, false, 1, false, shape);
     assertNotNull("a heap render returns bytes", bytes);
     assertEquals(0L, shape[0]);
     assertEquals(400L, shape[1]);
@@ -122,14 +122,68 @@ public class PdfCanvasNativeTest {
   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);
+    byte[] with = PdfCanvasNative.render(service, handle, 0, 0, 0, 200, 200, 1, 0, true, false, 1, false, shape);
+    byte[] without = PdfCanvasNative.render(service, handle, 0, 0, 0, 200, 200, 1, 0, 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);
   }
 
+  /**
+   * CATCHES: the rotation not surviving the JNI int hop, or landing in the
+   * wrong argument slot (a swapped {@code annotations} would still compile).
+   * Doc top-left is blue and bottom-left red; a quarter turn clockwise puts
+   * the bottom-left at the top-left and the top-left at the top-right. The
+   * rect is the TURNED page's: 100x200 for a 200x100 page.
+   */
+  @Test
+  public void rotationReachesTheCore() throws Exception {
+    int handle = open(TestPdfs.quadrants(ctx(), "jni-rotated.pdf", 200, 100));
+    long[] shape = new long[4];
+    byte[] bytes =
+        PdfCanvasNative.render(service, handle, 0, 0, 0, 100, 200, 2, 90, false, false, 1, false, shape);
+    assertNotNull(bytes);
+    assertEquals(200L, shape[1]);
+    assertEquals(400L, shape[2]);
+    int rowBytes = (int) shape[3];
+    assertPixel(bytes, rowBytes, 20, 20, 255, 0, 0);     // red: doc bottom-left, now top-left
+    assertPixel(bytes, rowBytes, 180, 20, 0, 0, 255);    // blue: doc top-left, now top-right
+    assertPixel(bytes, rowBytes, 180, 380, 0, 0, 0);     // black: doc top-right, now bottom-right
+    assertPixel(bytes, rowBytes, 20, 380, 0, 255, 0);    // green: doc bottom-right, now bottom-left
+    PdfCanvasNative.close(service, handle);
+  }
+
+  /**
+   * CATCHES: the query mangled crossing JNI (it goes as UTF-16 via
+   * {@code GetStringRegion}, never modified UTF-8), a flag or the rotation in
+   * the wrong argument slot, and the JSON not surviving {@code NewStringUTF}.
+   * The match itself — index, rects, geometry — is proven by {@code native/tests};
+   * this checks the values cross.
+   */
+  @Test
+  public void searchCrossesJni() throws Exception {
+    int handle = open(TestPdfs.text(ctx(), "jni-text.pdf"));
+    PdfCanvasNative.registerCancellation(service, handle, 1);
+    String json = PdfCanvasNative.search(service, handle, 0, "MEASURED", false, false, 0, 1);
+    assertTrue(json, json.startsWith("[{\"page\":0,\"charIndex\":6,\"charCount\":8,\"rects\":[{"));
+    assertTrue(json, json.contains("\"context\":\"Hello measured world\""));
+    // matchCase lands in its own slot: the same query now finds nothing.
+    assertEquals("[]", PdfCanvasNative.search(service, handle, 0, "MEASURED", true, false, 0, 2));
+    // wholeWord likewise.
+    assertEquals("[]", PdfCanvasNative.search(service, handle, 0, "meas", false, true, 0, 3));
+    // A supplementary character crosses intact and simply matches nothing.
+    assertEquals("[]", PdfCanvasNative.search(service, handle, 0, "\uD83D\uDE00", false, false, 0, 4));
+    // A refused rotation comes back as a typed error, not a crash.
+    try {
+      PdfCanvasNative.search(service, handle, 0, "measured", false, false, 45, 5);
+      fail("a 45-degree rotation must be refused");
+    } catch (PdfRasterException e) {
+      assertEquals(PdfErrorCode.BACKEND_FAILURE, e.code());
+    }
+    PdfCanvasNative.close(service, handle);
+  }
+
   /* ================================================================ *
    * 2. The transport
    * ================================================================ */
@@ -144,11 +198,11 @@ public class PdfCanvasNativeTest {
   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);
+    byte[] heap = PdfCanvasNative.render(service, handle, 0, 37, 23, 64, 41, 4, 0, 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);
+    byte[] none = PdfCanvasNative.render(service, handle, 0, 37, 23, 64, 41, 4, 0, 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]);
@@ -215,7 +269,7 @@ public class PdfCanvasNativeTest {
     }
     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]);
+      PdfCanvasNative.render(service, handle, 7, 0, 0, 10, 10, 1, 0, false, false, 1, false, new long[4]);
       fail("an out-of-range page must throw");
     } catch (PdfRasterException e) {
       assertEquals(PdfErrorCode.NOT_FOUND, e.code());
@@ -228,24 +282,24 @@ public class PdfCanvasNativeTest {
     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]);
+      PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, 0, 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]));
+    assertNotNull(PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, 0, 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]);
+    PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, 0, 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]);
+      PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, 0, false, false, 2, false, new long[4]);
       fail("a render after invalidate must throw");
     } catch (PdfRasterException e) {
       assertEquals(PdfErrorCode.BACKEND_FAILURE, e.code());

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

@@ -18,9 +18,9 @@ import java.util.List;
  * laptop by {@code native/tests} against the same PDFium build, with a much
  * richer fixture set. What is left to prove ON DEVICE is that the bytes cross
  * JNI intact and the transport's slot store hands back what PDFium wrote, and
- * two fixtures are enough for that: one whose channels are all saturated (a
- * channel swap or a stride shear cannot hide) and one whose green exists only
- * inside an annotation.
+ * three fixtures are enough for that: one whose channels are all saturated (a
+ * channel swap or a stride shear cannot hide), one whose green exists only
+ * inside an annotation, and one line of text for the search seam.
  */
 final class TestPdfs {
 
@@ -124,6 +124,25 @@ final class TestPdfs {
     return writeFile(ctx, name, wr.finish(catalog));
   }
 
+  /**
+   * "Hello measured world" in unembedded 24pt Helvetica at (72, 700) on a
+   * 612x792 page — the same bytes {@code native/tests} searches.
+   */
+  static File text(Context ctx, String name) throws IOException {
+    Writer wr = new Writer();
+    int contents = wr.add(stream("BT /F1 24 Tf 72 700 Td (Hello measured world) Tj ET\n"));
+    int font = wr.add("<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>");
+    int pagesNumber = wr.count() + 2;
+    int page = wr.add("<< /Type /Page /Parent " + pagesNumber + " 0 R /MediaBox [0 0 612 792] /Contents "
+        + contents + " 0 R /Resources << /Font << /F1 " + font + " 0 R >> >> >>");
+    int pages = wr.add("<< /Type /Pages /Kids [" + page + " 0 R] /Count 1 >>");
+    int catalog = wr.add("<< /Type /Catalog /Pages " + pages + " 0 R >>");
+    if (pages != pagesNumber) {
+      throw new IllegalStateException("Pages object is " + pages + ", not " + pagesNumber);
+    }
+    return writeFile(ctx, name, wr.finish(catalog));
+  }
+
   /** No %PDF header and no recoverable objects. */
   static File notAPdf(Context ctx, String name) throws IOException {
     StringBuilder sb = new StringBuilder();

package/android/src/main/cpp/pdfcanvas-jni.cpp

@@ -13,7 +13,7 @@
  * `PdfError` into a `PdfRasterException` carrying the same wire code, and
  * anything else into `backend-failure`.
  *
- * PLAIN JNI, NO FBJNI. The whole surface is a dozen static methods on one
+ * PLAIN JNI, NO FBJNI. The whole surface is fourteen static methods on one
  * class; fbjni would add a dependency and a registration dance to express
  * `SetByteArrayRegion`.
  */
@@ -94,6 +94,21 @@ std::vector<uint8_t> toBytes(JNIEnv* env, jbyteArray value) {
   return out;
 }
 
+/// UTF-16 straight out of the Java string, with no transcoding. NOT
+/// `GetStringUTFChars`: that is "modified UTF-8", which encodes a
+/// supplementary character as two three-byte surrogates and U+0000 as two
+/// bytes, so a query containing either would reach PDFium as something else.
+std::u16string toUtf16(JNIEnv* env, jstring value) {
+  if (value == nullptr) return {};
+  const jsize length = env->GetStringLength(value);
+  std::u16string out(static_cast<size_t>(length), u'\0');
+  if (length > 0) {
+    static_assert(sizeof(jchar) == sizeof(char16_t), "jchar is a UTF-16 unit");
+    env->GetStringRegion(value, 0, length, reinterpret_cast<jchar*>(&out[0]));
+  }
+  return out;
+}
+
 jbyteArray toJavaBytes(JNIEnv* env, const std::vector<uint8_t>& bytes) {
   const jsize length = static_cast<jsize>(bytes.size());
   jbyteArray out = env->NewByteArray(length);
@@ -172,8 +187,8 @@ JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_registerCance
 
 JNIEXPORT jbyteArray JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_render(
     JNIEnv* env, jclass, jlong service, jint handle, jint page, jdouble x, jdouble y, jdouble width,
-    jdouble height, jdouble scale, jboolean annotations, jboolean transparent, jlong token,
-    jboolean useSlot, jlongArray out) {
+    jdouble height, jdouble scale, jint rotation, jboolean annotations, jboolean transparent,
+    jlong token, jboolean useSlot, jlongArray out) {
   return guarded<jbyteArray>(env, nullptr, [&]() -> jbyteArray {
     Service* s = serviceOf(service);
     if (s == nullptr) throw PdfError(ErrorCode::BackendFailure, "The native service is gone.");
@@ -188,6 +203,8 @@ JNIEXPORT jbyteArray JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_render(
     request.width = width;
     request.height = height;
     request.scale = scale;
+    // Degrees clockwise on top of the page's /Rotate; the core validates it.
+    request.rotation = rotation;
     request.annotations = annotations == JNI_TRUE;
     request.background = transparent == JNI_TRUE ? pdfcanvas::Background::Transparent
                                                  : pdfcanvas::Background::White;
@@ -207,6 +224,33 @@ JNIEXPORT jbyteArray JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_render(
   });
 }
 
+JNIEXPORT jstring JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_search(
+    JNIEnv* env, jclass, jlong service, jint handle, jint page, jstring query, jboolean matchCase,
+    jboolean wholeWord, jint rotation, jlong token) {
+  return guarded<jstring>(env, nullptr, [&]() -> jstring {
+    Service* s = serviceOf(service);
+    if (s == nullptr) throw PdfError(ErrorCode::BackendFailure, "The native service is gone.");
+
+    pdfcanvas::TextSearchRequest request;
+    request.page = page;
+    request.query = toUtf16(env, query);
+    request.matchCase = matchCase == JNI_TRUE;
+    request.wholeWord = wholeWord == JNI_TRUE;
+    // Degrees clockwise, as for render; the core validates it.
+    request.rotation = rotation;
+
+    // PURE ASCII by construction (`textMatchesToJson`), which is the one input
+    // on which NewStringUTF's "modified UTF-8" and real UTF-8 agree.
+    const std::string json = s->searchJson(handle, request, token);
+    jstring out = env->NewStringUTF(json.c_str());
+    if (out == nullptr) {
+      throw PdfError(ErrorCode::OutOfMemory, "Could not allocate a Java string for " +
+                                                 std::to_string(json.size()) + " bytes of search results.");
+    }
+    return out;
+  });
+}
+
 JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_cancel(JNIEnv* env, jclass, jlong service,
                                                                          jint handle, jlong token) {
   guarded<int>(env, 0, [&] {

package/android/src/main/java/tools/reekon/pdfcanvas/PdfCanvasNative.java

@@ -107,6 +107,10 @@ public final class PdfCanvasNative {
   /**
    * Renders one raster on the calling thread.
    *
+   * @param rotation the HOST's rotation on top of the page's {@code /Rotate},
+   *     in degrees clockwise: 0, 90, 180 or 270. The rect is in the TURNED
+   *     page's doc space — extents swapped for a quarter turn. The core refuses
+   *     anything else.
    * @param useSlot ask for the zero-copy transport. The store may still refuse,
    *     so the result says where the pixels ARE: a non-null return is heap
    *     bytes, a null return means {@code out[0]} names a slot.
@@ -122,6 +126,7 @@ public final class PdfCanvasNative {
       double width,
       double height,
       double scale,
+      int rotation,
       boolean annotations,
       boolean transparent,
       long token,
@@ -129,7 +134,32 @@ public final class PdfCanvasNative {
       long[] out)
       throws PdfRasterException;
 
-  /** Sets the signal a render polls, including mid-draw. A pure lookup. */
+  /**
+   * Finds every occurrence of {@code query} on one page, on the calling thread.
+   * Register the token with {@link #registerCancellation} first, exactly as for
+   * a render: {@link #cancel} then stops the search between matches.
+   *
+   * @param query crosses JNI as UTF-16, untranscoded.
+   * @param rotation the HOST's rotation, as for {@link #render}: the rects come
+   *     back in the TURNED page's doc space. The core refuses anything but 0,
+   *     90, 180 or 270.
+   * @return {@code TextMatch[]} as ONE JSON string, pure ASCII, written by the
+   *     core ({@code textMatchesToJson}) — handed to JS as it is, and checked
+   *     there by {@code parseTextMatches}.
+   * @throws PdfRasterException with the failure's {@link PdfErrorCode}.
+   */
+  public static native String search(
+      long service,
+      int handle,
+      int page,
+      String query,
+      boolean matchCase,
+      boolean wholeWord,
+      int rotation,
+      long token)
+      throws PdfRasterException;
+
+  /** Sets the signal a render (or a search) polls. A pure lookup. */
   public static native void cancel(long service, int handle, long token);
 
   /** Closes one document. Idempotent. */

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

@@ -60,10 +60,10 @@ import tools.reekon.pdfcanvas.PdfRasterException;
  * <h3>Threading</h3>
  *
  * {@code @ReactMethod} runs on the bridge's native-modules thread and a render
- * is a long synchronous call, so every open and render is handed to ONE worker.
- * One, because PDFium is not thread-safe and the core serialises every call
- * behind a process-wide lock anyway; a second worker would only queue behind
- * the first while holding a promise open.
+ * is a long synchronous call, so every open, render and search is handed to ONE
+ * worker. One, because PDFium is not thread-safe and the core serialises every
+ * call behind a process-wide lock anyway; a second worker would only queue
+ * behind the first while holding a promise open.
  *
  * <p>EVERY {@code ReadableMap} IS DRAINED ON THE CALLING THREAD, before the
  * worker is handed anything: on the legacy bridge a {@code ReadableNativeMap} is
@@ -294,7 +294,7 @@ public class PdfCanvasModule extends ReactContextBaseJavaModule {
       return;
     }
     // The whole request is turned into plain values HERE, on the bridge thread.
-    final int page;
+    final int page, rotation;
     final double x, y, width, height, scale;
     final boolean annotations, transparent;
     try {
@@ -304,6 +304,13 @@ public class PdfCanvasModule extends ReactContextBaseJavaModule {
       width = request.getDouble("width");
       height = request.getDouble("height");
       scale = request.getDouble("scale");
+      // OPTIONAL, DEFAULTING TO 0: a JS bundle older than this binary never
+      // sends it, and a page must not turn because a key is missing. The core
+      // validates the value; this only decides what "absent" means.
+      rotation =
+          request.hasKey("rotation") && !request.isNull("rotation")
+              ? request.getInt("rotation")
+              : 0;
       annotations = !request.hasKey("annotations") || request.getBoolean("annotations");
       transparent = "transparent".equals(request.getString("background"));
     } catch (RuntimeException e) {
@@ -329,8 +336,8 @@ public class PdfCanvasModule extends ReactContextBaseJavaModule {
               final long[] shape = new long[4];
               final byte[] bytes =
                   PdfCanvasNative.render(
-                      service, handle, page, x, y, width, height, scale, annotations, transparent,
-                      token, fast, shape);
+                      service, handle, page, x, y, width, height, scale, rotation, annotations,
+                      transparent, token, fast, shape);
               slot = shape[0];
 
               WritableMap result = Arguments.createMap();
@@ -371,11 +378,74 @@ public class PdfCanvasModule extends ReactContextBaseJavaModule {
     }
   }
 
+  /* ---------------------------------------------------------------- *
+   * search
+   * ---------------------------------------------------------------- */
+
+  /**
+   * Finds text on one page and resolves with the core's JSON — ONE string,
+   * however many hits, so a find pass over a dense drawing is one bridge value
+   * rather than thousands of maps. {@code native-bridge.ts} parses and checks
+   * it.
+   *
+   * <p>THE SAME WORKER AS RENDER, deliberately: PDFium is not thread-safe and
+   * the core serialises everything behind one lock anyway, and a search that
+   * jumped the queue would only wait on that lock while holding the text page
+   * a render is about to want. The same (handle, token) registry too, so
+   * {@link #cancel} stops a superseded search between matches.
+   */
+  @ReactMethod
+  public void search(int handle, ReadableMap request, int token, Promise promise) {
+    if (!requireService(promise)) {
+      return;
+    }
+    // Drained HERE, on the bridge thread, like render's request.
+    final int page, rotation;
+    final String query;
+    final boolean matchCase, wholeWord;
+    try {
+      page = request.getInt("page");
+      query = request.hasKey("query") && !request.isNull("query") ? request.getString("query") : "";
+      matchCase = request.hasKey("matchCase") && request.getBoolean("matchCase");
+      wholeWord = request.hasKey("wholeWord") && request.getBoolean("wholeWord");
+      // OPTIONAL, DEFAULTING TO 0, for the reason render's is.
+      rotation =
+          request.hasKey("rotation") && !request.isNull("rotation")
+              ? request.getInt("rotation")
+              : 0;
+    } catch (RuntimeException e) {
+      reject(promise, PdfErrorCode.BACKEND_FAILURE, e);
+      return;
+    }
+
+    // Registered BEFORE the worker runs — see render.
+    PdfCanvasNative.registerCancellation(service, handle, token);
+
+    try {
+      worker.execute(
+          () -> {
+            try {
+              promise.resolve(
+                  PdfCanvasNative.search(
+                      service, handle, page, query, matchCase, wholeWord, rotation, token));
+            } catch (PdfRasterException e) {
+              reject(promise, e);
+            } catch (Throwable t) {
+              reject(promise, PdfErrorCode.BACKEND_FAILURE, t);
+            }
+          });
+    } catch (RejectedExecutionException e) {
+      // invalidate() shut the worker down between the register and here.
+      reject(promise, PdfErrorCode.BACKEND_FAILURE, e);
+    }
+  }
+
   /**
    * Genuinely mid-render now, not best-effort: the core polls the signal from
    * PDFium's progressive renderer between batches of page objects, so a
-   * superseded tile stops drawing within one batch. A pure lookup — a cancel
-   * for a token whose render already finished finds nothing and does nothing.
+   * superseded tile stops drawing within one batch — and a search between
+   * matches. A pure lookup — a cancel for a token whose job already finished
+   * finds nothing and does nothing.
    */
   @ReactMethod
   public void cancel(int handle, int token) {

package/android/tools/compile-gate.sh

@@ -177,10 +177,12 @@ if [ -n "$CLANG" ] && [ -f "$PDFIUM/include/fpdfview.h" ]; then
   if [ -n "$NM" ] && [ -f "$OUT/lib-aarch64-linux-android24.so" ]; then
     exported=$("$NM" -D --defined-only "$OUT/lib-aarch64-linux-android24.so" 2>/dev/null \
       | grep -c 'Java_tools_reekon_pdfcanvas_PdfCanvasNative_')
-    if [ "${exported:-0}" -ge 13 ]; then
+    # 14 since 0.4.0 (`search`). A floor, not an equality: the prototype gate
+    # below is what pins declarations and definitions to each other.
+    if [ "${exported:-0}" -ge 14 ]; then
       echo "PASS  the linked .so exports $exported Java_tools_reekon_pdfcanvas_PdfCanvasNative_* symbols"
     else
-      echo "FAIL  the linked .so exports only ${exported:-0} JNI symbols (expected >= 13)"; fail=1
+      echo "FAIL  the linked .so exports only ${exported:-0} JNI symbols (expected >= 14)"; fail=1
     fi
   else
     say_skip "exported JNI symbols" "no llvm-nm, or nothing linked"
@@ -249,8 +251,8 @@ if [ -n "$JAVAC" ] && [ -n "$AJAR" ] && [ -n "$CLANG" ] && [ -f "$PDFIUM/include
       n=$((n + 1))
       grep -q "${m}(" "$JNI_SRC" || missing="$missing $m"
     done
-    if [ "$n" -lt 13 ]; then
-      echo "FAIL  the JNI gate found only $n declared native methods (expected >= 13)"; fail=1
+    if [ "$n" -lt 14 ]; then
+      echo "FAIL  the JNI gate found only $n declared native methods (expected >= 14)"; fail=1
     elif [ -n "$missing" ]; then
       echo "FAIL  declared native in Java, undefined in C++:$missing"; fail=1
     else

package/dist/controller.d.ts

@@ -37,7 +37,7 @@
  * which key comes from `./planner.js`. A private copy of either is how the two
  * silently drift until the tested one is testing nothing that runs.
  */
-import type { DocRect, PageGeometry, PdfContent, PdfController, PdfDiagnostic, PdfRaster, RasterizerHandle, RasterPixels, RasterPolicy, RasterRole } from './types.js';
+import type { DocRect, PageGeometry, PageRotation, PdfContent, PdfController, PdfDiagnostic, PdfRaster, RasterizerHandle, RasterPixels, RasterPolicy, RasterRole } from './types.js';
 import type { RasterCache } from './cache.js';
 export interface ScheduledHandle {
     cancel(): void;
@@ -62,6 +62,28 @@ export interface PdfControllerOptions {
     pageRects: DocRect[];
     /** Parallel to `pageRects`. Every page, in page order. */
     pages: PageGeometry[];
+    /**
+     * The HOST's per-page rotation on top of the document's `/Rotate`, indexed
+     * by page like `pageRects`; a missing or undefined entry is 0. Stamped onto
+     * every `RasterRequest` for that page as `rotation` — and only that. The
+     * controller does no rotation arithmetic of its own.
+     *
+     * WHY A PARALLEL ARRAY AND NOT A FIELD ON `PageGeometry`. `PageGeometry` is
+     * the backend's statement of a page's intrinsic size, and its `rotation` is
+     * already taken: it is the document's own `/Rotate`. A host preference on
+     * the same object would give the type two rotations with different meanings,
+     * and would ride into every backend that constructs one (the fake, the web
+     * engine, the native bridge) for a value none of them produce. This
+     * controller already takes its per-page inputs as parallel arrays, so a
+     * third costs nothing new and touches nothing outside this file.
+     *
+     * THE GEOMETRY MUST ALREADY BE ROTATED. For a page turned 90 or 270, `pages`
+     * and `pageRects` must both carry the SWAPPED extents — see `../rotation.ts`
+     * — because `layoutScale` is `pageRect.width / geometry.width` and is only
+     * right when both sides describe the same orientation. `usePdfLayer` does
+     * the swap; a host driving this directly must too.
+     */
+    rotations?: readonly PageRotation[];
     policy: RasterPolicy;
     ingest: (pixels: RasterPixels, meta: RasterIngestMeta) => PdfRaster;
     cache: RasterCache;