@reekon-tools/react-native-pdf-canvas 0.3.0 → 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.
@@ -267,6 +268,43 @@ Doc space for a turned page is the turned page's: a 612x792 page at 90 is laid o
 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

@@ -154,6 +154,36 @@ public class PdfCanvasNativeTest {
     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
    * ================================================================ */

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);
@@ -209,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

@@ -134,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
@@ -378,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.js

@@ -148,6 +148,9 @@ export function createPdfController(options) {
         pages: Object.freeze(pageInfos.map(info => Object.freeze({
             page: info.page,
             pageRect: info.pageRect,
+            // Fixed for the controller's lifetime: the allow-list is a
+            // construction option, and a change to it rebuilds the controller.
+            drawable: allowedPages === undefined || allowedPages.has(info.page),
             base: EMPTY_RASTERS,
             detail: EMPTY_RASTERS,
             retiring: EMPTY_RASTERS,
@@ -831,6 +834,7 @@ export function createPdfController(options) {
             return Object.freeze({
                 page: previous.page,
                 pageRect: previous.pageRect,
+                drawable: previous.drawable,
                 base,
                 detail,
                 retiring,
@@ -999,6 +1003,7 @@ export function createPdfController(options) {
                 pages: Object.freeze(content.pages.map(page => Object.freeze({
                     page: page.page,
                     pageRect: page.pageRect,
+                    drawable: page.drawable,
                     base: EMPTY_RASTERS,
                     detail: EMPTY_RASTERS,
                     retiring: EMPTY_RASTERS,

package/dist/rasterizer/fake.d.ts

@@ -26,7 +26,7 @@
  * Everything here is a pure function of the request, so the same request always
  * produces byte-identical output.
  */
-import type { DocRect, DocSize, PageRasterizer, PageRotation, PdfErrorCode, PixelFormat, PixelSize, RasterPixels, RasterRequest } from '../types.js';
+import type { DocRect, DocSize, PageRasterizer, PageRotation, PdfErrorCode, PixelFormat, PixelSize, RasterPixels, RasterRequest, TextMatch, TextSearchRequest } from '../types.js';
 export declare const LETTER: DocSize;
 /** ARCH D, 24x36in — the sheet the base-raster sizing rule is calibrated on. */
 export declare const ARCH_D: DocSize;
@@ -53,10 +53,18 @@ export interface FakeRasterizerOptions {
      * height are already post-rotation, so the fake does not swap them.
      */
     pageRotations?: readonly PageRotation[];
+    /**
+     * The text `searchText` searches, one entry per page (`text[page]`). NOT
+     * cycled: a page with no entry has no text and every search of it answers
+     * `[]`, which is also the default. The pixels never show it — the fake
+     * draws a checkerboard — so this is what lets a controller or host test
+     * drive "find" without an engine.
+     */
+    text?: readonly string[];
     /** Checker cell size in DOC units. */
     checkerDocSize?: number;
     format?: PixelFormat;
-    /** Artificial delay on `render()` only; `open()` always resolves promptly. */
+    /** Artificial delay on `render()` and `searchText()`; `open()` always resolves promptly. */
     latencyMs?: number;
     /** When set, `open()` enforces it against `source.password`. */
     password?: string;
@@ -101,4 +109,18 @@ export declare function decodeFakeDocRect(pixels: RasterPixels): DocRect | null;
  * controller's stamp reached the backend.
  */
 export declare function decodeFakeRotation(pixels: RasterPixels): PageRotation | null;
+/** Where the fake puts the i-th match's rect: a 10x10 box at (10 + 20i, 10). */
+export declare const FAKE_MATCH_RECT_SIZE = 10;
+export declare const FAKE_MATCH_RECT_ORIGIN = 10;
+export declare const FAKE_MATCH_RECT_STRIDE = 20;
+/**
+ * Every occurrence of `query` in `text`, PDFium-shaped: non-overlapping,
+ * left to right, case-folded unless `matchCase`, and — under `wholeWord` —
+ * only where neither neighbour is a word character. Rects are DETERMINISTIC
+ * and say nothing about where the text would be drawn (the fake draws no
+ * text), which is exactly what a pipeline test wants: the i-th match of any
+ * query on any page is at the same place, so a test can assert a hit was
+ * drawn there without a raster in the loop.
+ */
+export declare function searchFakeText(text: string, request: TextSearchRequest): TextMatch[];
 export declare function createFakeRasterizer(options?: FakeRasterizerOptions): PageRasterizer;

package/dist/rasterizer/fake.js

@@ -27,6 +27,7 @@
  * produces byte-identical output.
  */
 import { isPageRotation } from '../rotation.js';
+import { contextAround } from './text-search.js';
 import { PdfError } from '../types.js';
 /* ------------------------------------------------------------------ *
  * Page sizes, in PDF points (1pt = 1/72in)
@@ -62,6 +63,7 @@ function resolveConfig(options) {
     return {
         id: options.id ?? 'fake',
         pages,
+        text: options.text ?? [],
         checkerDocSize: options.checkerDocSize ?? DEFAULT_CHECKER_DOC_SIZE,
         format: options.format ?? 'rgba8888',
         latencyMs: options.latencyMs ?? 0,
@@ -355,6 +357,58 @@ function renderPixels(request, cfg, geometry) {
         alpha: FAKE_ALPHA,
     };
 }
+/* ------------------------------------------------------------------ *
+ * Text search
+ * ------------------------------------------------------------------ */
+/** Where the fake puts the i-th match's rect: a 10x10 box at (10 + 20i, 10). */
+export const FAKE_MATCH_RECT_SIZE = 10;
+export const FAKE_MATCH_RECT_ORIGIN = 10;
+export const FAKE_MATCH_RECT_STRIDE = 20;
+const isWordChar = (ch) => ch !== undefined && /[\p{L}\p{N}_]/u.test(ch);
+/**
+ * Every occurrence of `query` in `text`, PDFium-shaped: non-overlapping,
+ * left to right, case-folded unless `matchCase`, and — under `wholeWord` —
+ * only where neither neighbour is a word character. Rects are DETERMINISTIC
+ * and say nothing about where the text would be drawn (the fake draws no
+ * text), which is exactly what a pipeline test wants: the i-th match of any
+ * query on any page is at the same place, so a test can assert a hit was
+ * drawn there without a raster in the loop.
+ */
+export function searchFakeText(text, request) {
+    const query = request.query;
+    if (query.length === 0 || text.length === 0)
+        return [];
+    const haystack = request.matchCase ? text : text.toLowerCase();
+    const needle = request.matchCase ? query : query.toLowerCase();
+    const matches = [];
+    let from = 0;
+    for (;;) {
+        const at = haystack.indexOf(needle, from);
+        if (at < 0)
+            break;
+        from = at + needle.length;
+        if (request.wholeWord &&
+            (isWordChar(text[at - 1]) || isWordChar(text[at + needle.length]))) {
+            continue;
+        }
+        const i = matches.length;
+        matches.push({
+            page: request.page,
+            charIndex: at,
+            charCount: needle.length,
+            rects: [
+                {
+                    x: FAKE_MATCH_RECT_ORIGIN + FAKE_MATCH_RECT_STRIDE * i,
+                    y: FAKE_MATCH_RECT_ORIGIN,
+                    width: FAKE_MATCH_RECT_SIZE,
+                    height: FAKE_MATCH_RECT_SIZE,
+                },
+            ],
+            context: contextAround(text, at, needle.length),
+        });
+    }
+    return matches;
+}
 /* ------------------------------------------------------------------ *
  * Cancellation
  * ------------------------------------------------------------------ */
@@ -455,6 +509,23 @@ function createHandle(cfg) {
             }
             return renderPixels(request, cfg, geometry);
         },
+        async searchText(request, signal) {
+            throwIfAborted(signal);
+            requireOpen();
+            requirePage(request.page);
+            // Validated as every real backend validates it, even though the fake's
+            // rects do not turn: a request that asked for a bad turn must not
+            // quietly answer as if it were upright.
+            if (!isPageRotation(request.rotation)) {
+                throw new PdfError('backend-failure', `Fake rasterizer: rotation must be 0, 90, 180 or 270, got ${String(request.rotation)}.`);
+            }
+            if (cfg.latencyMs > 0) {
+                await delay(cfg.latencyMs, signal);
+            }
+            throwIfAborted(signal);
+            requireOpen();
+            return searchFakeText(cfg.text[request.page] ?? '', request);
+        },
         close() {
             closed = true;
         },
@@ -470,7 +541,9 @@ export function createFakeRasterizer(options = {}) {
         // which is to say, between requests only.
         interruptibleRender: cfg.latencyMs > 0,
         text: false,
-        search: false,
+        // True even with no `text` configured: the seam is implemented, and a
+        // page with nothing on it genuinely has no matches.
+        search: true,
         links: false,
         maxConcurrentRenders: cfg.maxConcurrentRenders,
     };

package/dist/rasterizer/native-bridge.d.ts

@@ -23,7 +23,7 @@
  * carries on.
  */
 import { PdfError } from '../types.js';
-import type { AlphaEncoding, PageGeometry, PageRasterizer, PdfSource, PixelFormat, RasterizerCapabilities, RasterizerHandle, RasterTransport } from '../types.js';
+import type { AlphaEncoding, PageGeometry, PageRasterizer, PdfSource, PixelFormat, RasterizerCapabilities, RasterizerHandle, RasterTransport, TextMatch } from '../types.js';
 export interface NativePdfPage {
     index: number;
     /** Post-rotation, in PDF points. A double: A4 is 595.276 wide. */
@@ -98,9 +98,35 @@ export interface NativeSource {
     base64?: string;
     password?: string;
 }
+/**
+ * `TextSearchRequest` as it crosses the bridge — the same five fields, every
+ * one present, so neither binding has a default that could drift from
+ * `PdfDocument.searchPage`'s. `rotation` is degrees clockwise like the render
+ * request's, and the core refuses anything but the four values.
+ */
+export interface NativeSearchRequest {
+    page: number;
+    query: string;
+    matchCase: boolean;
+    wholeWord: boolean;
+    rotation: number;
+}
 export interface PdfCanvasNativeModule {
     open(source: NativeSource): Promise<NativeOpenResult>;
     render(handle: number, request: NativeRenderRequest, token: number): Promise<NativeRenderResult>;
+    /**
+     * Resolves with ONE JSON string — `TextMatch[]`, built in the C++ core —
+     * rather than a bridge array of maps. A find-in-document pass on a dense
+     * page is hundreds of matches with several rects each, and one string is
+     * one bridge value where the map form is thousands; `parseTextMatches`
+     * checks the shape on the way in. The same (handle, token) registry as
+     * `render`, so `cancel` stops a search between matches.
+     *
+     * OPTIONAL IN THIS TYPE because it is optional in the wild: a JS bundle
+     * shipped over the air can be newer than the binary under it, and a
+     * 0.3.x binary has no such method. `searchText` checks for it and says so.
+     */
+    search?(handle: number, request: NativeSearchRequest, token: number): Promise<string>;
     /**
      * Sets the signal the render polls — including MID-RENDER, through PDFium's
      * progressive API — so a superseded tile stops within one batch of page
@@ -211,6 +237,16 @@ export interface NativeTransport {
  * do this fast renders exactly as it did before.
  */
 export declare function negotiateTransport(native: PdfCanvasNativeModule, lookup?: () => TakePixels | null): NativeTransport;
+/**
+ * The core's JSON, checked field by field into `TextMatch[]`.
+ *
+ * Checked rather than cast because the string was built by hand in C++
+ * (`native/core/src/text_search.cpp`) with no JSON library on either side of
+ * it, and a host drawing hits from a `rects` entry that is `undefined` would
+ * fail inside its own draw code with no mention of this package. Every
+ * failure here is `backend-failure` naming what was wrong.
+ */
+export declare function parseTextMatches(json: string): TextMatch[];
 export declare function toPageGeometry(page: NativePdfPage): PageGeometry;
 /**
  * Turns one native render result into bytes, on whichever transport produced it.