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

package/dist/rasterizer/web/pdfium.d.ts

@@ -46,6 +46,9 @@ import type { PdfErrorCode } from '../../types.js';
 export declare const FPDF_BITMAP_BGRA = 4;
 /** Draw PDF-embedded annotations. Answers `RasterRequest.annotations`. */
 export declare const FPDF_ANNOT = 1;
+/** `FPDFText_FindStart` flags. Answer `TextSearchRequest.matchCase` / `.wholeWord`. */
+export declare const FPDF_MATCHCASE = 1;
+export declare const FPDF_MATCHWHOLEWORD = 2;
 /**
  * Write RGBA instead of BGRA.
  *
@@ -95,11 +98,18 @@ export interface PdfiumHeap {
     free(pointer: number): void;
     /** Reads an `FS_SIZEF` component — PDFium's float32. */
     getFloat(pointer: number): number;
+    /** Reads a `double*` out-parameter — `FPDFText_GetRect`'s four edges. */
+    getDouble(pointer: number): number;
+    /** Reads an `int*` out-parameter — `FPDF_PageToDevice`'s two coordinates. */
+    getInt32(pointer: number): number;
 }
 /**
  * Exactly the PDFium entry points this backend calls. Nothing speculative:
- * text, search, links and form filling are all absent because none of them is
- * implemented, and `RasterizerCapabilities` says so.
+ * links and form filling are absent because neither is implemented, and
+ * `RasterizerCapabilities` says so. The `FPDFText_*` group is the text search
+ * surface (`RasterizerHandle.searchText`), and `FPDF_PageToDevice` is how its
+ * rects are mapped into the displayed page's doc space — see `search` in
+ * `./engine.ts`.
  */
 export interface PdfiumBinding extends PdfiumHeap {
     /**
@@ -149,6 +159,40 @@ export interface PdfiumBinding extends PdfiumHeap {
     FPDFBitmap_GetBuffer(bitmap: number): number;
     FPDFBitmap_GetStride(bitmap: number): number;
     FPDF_RenderPageBitmap(bitmap: number, page: number, startX: number, startY: number, sizeX: number, sizeY: number, rotate: number, flags: number): void;
+    /**
+     * Maps a point in the page's USER space onto a device box. `sizeX`/`sizeY`
+     * are the box the page is displayed INTO after `rotate` — the same box the
+     * render call takes, extents swapped for a quarter turn — and the output is
+     * ROUNDED TO WHOLE DEVICE UNITS by PDFium (`FXSYS_roundf` on both), which is
+     * why `search` scales the box up before calling it.
+     */
+    FPDF_PageToDevice(page: number, startX: number, startY: number, sizeX: number, sizeY: number, rotate: number, pageX: number, pageY: number, deviceXOut: number, deviceYOut: number): boolean;
+    /** Parses the page's text. Balanced by `FPDFText_ClosePage`. */
+    FPDFText_LoadPage(page: number): number;
+    FPDFText_ClosePage(textPage: number): void;
+    FPDFText_CountChars(textPage: number): number;
+    /**
+     * Writes `count` UTF-16 code units plus a terminating 0 to `buffer` (which
+     * must hold `count + 1` units) and returns how many units it wrote, the
+     * terminator included.
+     */
+    FPDFText_GetText(textPage: number, startIndex: number, count: number, buffer: number): number;
+    /**
+     * `findWhat` is an `FPDF_WIDESTRING`: UTF-16LE code units in the heap with a
+     * terminating 0. Returns a search handle, or 0 for an empty query.
+     */
+    FPDFText_FindStart(textPage: number, findWhat: number, flags: number, startIndex: number): number;
+    FPDFText_FindNext(handle: number): boolean;
+    FPDFText_FindClose(handle: number): void;
+    FPDFText_GetSchResultIndex(handle: number): number;
+    FPDFText_GetSchCount(handle: number): number;
+    /** Counts the rects a char range occupies and caches them for `GetRect`. */
+    FPDFText_CountRects(textPage: number, startIndex: number, count: number): number;
+    /**
+     * One cached rect, as four `double*` out-parameters in the page's USER space
+     * (y up, so `top > bottom`).
+     */
+    FPDFText_GetRect(textPage: number, rectIndex: number, leftOut: number, topOut: number, rightOut: number, bottomOut: number): boolean;
 }
 /**
  * The shape of `@embedpdf/pdfium`'s `WrappedPdfiumModule`, restated as the
@@ -189,6 +233,24 @@ export interface PdfiumWasmModule {
     FPDFBitmap_GetBuffer(bitmap: number): number;
     FPDFBitmap_GetStride(bitmap: number): number;
     FPDF_RenderPageBitmap(bitmap: number, page: number, startX: number, startY: number, sizeX: number, sizeY: number, rotate: number, flags: number): null;
+    FPDF_PageToDevice(page: number, startX: number, startY: number, sizeX: number, sizeY: number, rotate: number, pageX: number, pageY: number, deviceXOut: number, deviceYOut: number): boolean;
+    FPDFText_LoadPage(page: number): number;
+    FPDFText_ClosePage(textPage: number): null;
+    FPDFText_CountChars(textPage: number): number;
+    FPDFText_GetText(textPage: number, startIndex: number, count: number, buffer: number): number;
+    /**
+     * `findWhat` is a POINTER (`number`), not a JS string: the real module's
+     * signature is `["number", "number", "number", "number"]`, so the UTF-16LE
+     * query is written into the heap by the caller. A `"string"` here would
+     * have `tsc` accept a call the wasm would read as a garbage pointer.
+     */
+    FPDFText_FindStart(textPage: number, findWhat: number, flags: number, startIndex: number): number;
+    FPDFText_FindNext(handle: number): boolean;
+    FPDFText_FindClose(handle: number): null;
+    FPDFText_GetSchResultIndex(handle: number): number;
+    FPDFText_GetSchCount(handle: number): number;
+    FPDFText_CountRects(textPage: number, startIndex: number, count: number): number;
+    FPDFText_GetRect(textPage: number, rectIndex: number, leftOut: number, topOut: number, rightOut: number, bottomOut: number): boolean;
 }
 /**
  * Turn an initialised `@embedpdf/pdfium` module into a `PdfiumBinding`.

package/dist/rasterizer/web/pdfium.js

@@ -48,6 +48,9 @@ import { PdfError } from '../../types.js';
 export const FPDF_BITMAP_BGRA = 4;
 /** Draw PDF-embedded annotations. Answers `RasterRequest.annotations`. */
 export const FPDF_ANNOT = 0x01;
+/** `FPDFText_FindStart` flags. Answer `TextSearchRequest.matchCase` / `.wholeWord`. */
+export const FPDF_MATCHCASE = 0x01;
+export const FPDF_MATCHWHOLEWORD = 0x02;
 /**
  * Write RGBA instead of BGRA.
  *
@@ -96,6 +99,8 @@ export function bindPdfium(module) {
         malloc: byteLength => pdfium.wasmExports.malloc(byteLength),
         free: pointer => pdfium.wasmExports.free(pointer),
         getFloat: pointer => Number(pdfium.getValue(pointer, 'float')),
+        getDouble: pointer => Number(pdfium.getValue(pointer, 'double')),
+        getInt32: pointer => Number(pdfium.getValue(pointer, 'i32')),
         FPDF_LoadMemDocument: (pointer, byteLength, password) => module.FPDF_LoadMemDocument(pointer, byteLength, password),
         FPDF_CloseDocument: document => {
             module.FPDF_CloseDocument(document);
@@ -118,6 +123,22 @@ export function bindPdfium(module) {
         FPDF_RenderPageBitmap: (bitmap, page, startX, startY, sizeX, sizeY, rotate, flags) => {
             module.FPDF_RenderPageBitmap(bitmap, page, startX, startY, sizeX, sizeY, rotate, flags);
         },
+        FPDF_PageToDevice: (page, startX, startY, sizeX, sizeY, rotate, pageX, pageY, deviceXOut, deviceYOut) => module.FPDF_PageToDevice(page, startX, startY, sizeX, sizeY, rotate, pageX, pageY, deviceXOut, deviceYOut),
+        FPDFText_LoadPage: page => module.FPDFText_LoadPage(page),
+        FPDFText_ClosePage: textPage => {
+            module.FPDFText_ClosePage(textPage);
+        },
+        FPDFText_CountChars: textPage => module.FPDFText_CountChars(textPage),
+        FPDFText_GetText: (textPage, startIndex, count, buffer) => module.FPDFText_GetText(textPage, startIndex, count, buffer),
+        FPDFText_FindStart: (textPage, findWhat, flags, startIndex) => module.FPDFText_FindStart(textPage, findWhat, flags, startIndex),
+        FPDFText_FindNext: handle => module.FPDFText_FindNext(handle),
+        FPDFText_FindClose: handle => {
+            module.FPDFText_FindClose(handle);
+        },
+        FPDFText_GetSchResultIndex: handle => module.FPDFText_GetSchResultIndex(handle),
+        FPDFText_GetSchCount: handle => module.FPDFText_GetSchCount(handle),
+        FPDFText_CountRects: (textPage, startIndex, count) => module.FPDFText_CountRects(textPage, startIndex, count),
+        FPDFText_GetRect: (textPage, rectIndex, leftOut, topOut, rightOut, bottomOut) => module.FPDFText_GetRect(textPage, rectIndex, leftOut, topOut, rightOut, bottomOut),
     };
 }
 /* ------------------------------------------------------------------ *

package/dist/rasterizer/web/protocol.d.ts

@@ -21,7 +21,7 @@
  * exists but has not been told where its wasm is" — that could otherwise be
  * observed by a `render` arriving first.
  */
-import type { AlphaEncoding, PageGeometry, PdfErrorCode, PixelFormat, RasterRequest } from '../../types.js';
+import type { AlphaEncoding, PageGeometry, PdfErrorCode, PixelFormat, RasterRequest, TextMatch, TextSearchRequest } from '../../types.js';
 /**
  * Where the worker gets `pdfium.wasm`.
  *
@@ -65,11 +65,22 @@ export interface RenderRequest {
     request: RasterRequest;
 }
 /**
- * Drop a render that has not started yet.
+ * Find text on one page. Routed exactly as a render is — the same queue, the
+ * same yield, the same `cancel` by id — so a search never overtakes a render
+ * that was posted before it and a superseded search can still be dropped
+ * before it starts.
+ */
+export interface SearchRequest {
+    kind: 'search';
+    id: number;
+    request: TextSearchRequest;
+}
+/**
+ * Drop a render or a search that has not started yet.
  *
  * BEST EFFORT AND HONEST ABOUT IT. The worker renders synchronously, so a
- * `cancel` can only ever be delivered BETWEEN renders — never into one. What it
- * genuinely does is stop a QUEUED render from starting, which is why the worker
+ * `cancel` can only ever be delivered BETWEEN jobs — never into one. What it
+ * genuinely does is stop a QUEUED job from starting, which is why the worker
  * yields to its event loop between jobs (see `./session.ts`): without that
  * yield, messages queued behind a burst of renders would not be read until the
  * burst had finished and this message would be worthless.
@@ -94,7 +105,7 @@ export interface CancelRequest {
 export interface CloseRequest {
     kind: 'close';
 }
-export type WorkerRequest = OpenRequest | RenderRequest | CancelRequest | CloseRequest;
+export type WorkerRequest = OpenRequest | RenderRequest | SearchRequest | CancelRequest | CloseRequest;
 export interface OpenedResponse {
     kind: 'opened';
     id: number;
@@ -119,6 +130,12 @@ export interface RenderedResponse {
      */
     alpha: AlphaEncoding;
 }
+/** Plain data, structured-cloned whole: `DocRect`s and strings. */
+export interface SearchedResponse {
+    kind: 'searched';
+    id: number;
+    matches: TextMatch[];
+}
 export interface ErrorResponse {
     kind: 'error';
     /** Null for a failure that belongs to no single request. */
@@ -126,7 +143,7 @@ export interface ErrorResponse {
     code: PdfErrorCode;
     message: string;
 }
-export type WorkerResponse = OpenedResponse | RenderedResponse | ErrorResponse;
+export type WorkerResponse = OpenedResponse | RenderedResponse | SearchedResponse | ErrorResponse;
 /**
  * Is this a message from our worker?
  *

package/dist/rasterizer/web/protocol.js

@@ -33,5 +33,8 @@ export function isWorkerResponse(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const kind = value.kind;
-    return kind === 'opened' || kind === 'rendered' || kind === 'error';
+    return (kind === 'opened' ||
+        kind === 'rendered' ||
+        kind === 'searched' ||
+        kind === 'error');
 }

package/dist/rasterizer/web/session.js

@@ -180,6 +180,13 @@ export function createWorkerSession(deps) {
     let opening = null;
     let document = null;
     let disposed = false;
+    /**
+     * Renders AND searches, one queue. A search is a synchronous PDFium call
+     * like a render, wants the same between-jobs cancel window, and must not
+     * overtake a render posted before it — a page's text is parsed from the
+     * same loaded page the render uses, so keeping them in order keeps the
+     * engine's one-page cache hot for both.
+     */
     const queue = [];
     /**
      * Ids the main thread has given up on.
@@ -286,18 +293,27 @@ export function createWorkerSession(deps) {
                     if (cancelled.delete(job.id))
                         continue;
                     try {
-                        const raster = target.render(job.request);
-                        const buffer = raster.bytes.buffer;
-                        deps.post({
-                            kind: 'rendered',
-                            id: job.id,
-                            bytes: buffer,
-                            width: raster.width,
-                            height: raster.height,
-                            rowBytes: raster.rowBytes,
-                            format: raster.format,
-                            alpha: raster.alpha,
-                        }, [buffer]);
+                        if (job.kind === 'search') {
+                            deps.post({
+                                kind: 'searched',
+                                id: job.id,
+                                matches: target.search(job.request),
+                            });
+                        }
+                        else {
+                            const raster = target.render(job.request);
+                            const buffer = raster.bytes.buffer;
+                            deps.post({
+                                kind: 'rendered',
+                                id: job.id,
+                                bytes: buffer,
+                                width: raster.width,
+                                height: raster.height,
+                                rowBytes: raster.rowBytes,
+                                format: raster.format,
+                                alpha: raster.alpha,
+                            }, [buffer]);
+                        }
                     }
                     catch (error) {
                         postError(job.id, error);
@@ -387,7 +403,8 @@ export function createWorkerSession(deps) {
                     });
                     return;
                 }
-                case 'render': {
+                case 'render':
+                case 'search': {
                     queue.push(request);
                     void drain();
                     return;

package/dist/react/PdfContentView.js

@@ -158,6 +158,11 @@ export function PdfContentView({ content, zIndex, sampling = 'linear', paperColo
         const out = [];
         if (paperColor != null) {
             for (const page of content.pages) {
+                // A page outside the allow-list holds nothing and gets no paper: in a
+                // stacked layout its sheet would sit at the origin beside the one page
+                // that is meant to show (see PdfPageContent.drawable).
+                if (!page.drawable)
+                    continue;
                 const { pageRect } = page;
                 out.push(_jsx(Rect, { x: pageRect.x, y: pageRect.y, width: pageRect.width, height: pageRect.height, color: paperColor }, `paper:${page.page}`));
             }

package/dist/react/usePdfDocument.d.ts

@@ -16,7 +16,7 @@
  */
 import type { SkImage } from '@shopify/react-native-skia';
 import { PdfError } from '../types.js';
-import type { DocRect, DocSize, PageGeometry, PageRasterizer, PageRotation, PdfSource, PixelSize, RasterPixels, RasterizerCapabilities, RasterizerHandle } from '../types.js';
+import type { DocRect, DocSize, PageGeometry, PageRasterizer, PageRotation, PdfSource, PixelSize, RasterPixels, RasterizerCapabilities, RasterizerHandle, TextMatch, TextSearchOptions } from '../types.js';
 /** Install the rasterizer used when `usePdfDocument` / `openPdfDocument` are not
  * given one explicitly. Returns the previous value so a test can restore it. */
 export declare function setDefaultRasterizer(rasterizer: PageRasterizer | null): PageRasterizer | null;
@@ -83,7 +83,22 @@ export interface PdfDocument {
     /** Intrinsic sizes of every page, in the order a `PdfPageLayout` expects. */
     pageSizes(): DocSize[];
     renderPage(index: number, options?: PdfRenderOptions): Promise<PdfPageRender>;
-    /** True once `close()` has run. Every further call rejects with `cancelled`. */
+    /**
+     * Every occurrence of `query` on one page, in reading order.
+     *
+     * `TextMatch.rects` are in the page's doc space — PDF points, origin at the
+     * DISPLAYED page's top-left, y down — with `options.rotation` applied, so
+     * pass the same rotation the page's layer or `renderPage` uses and a hit
+     * drawn at a rect lands on the glyphs. An empty or whitespace-only query
+     * resolves `[]` without asking the backend. Rejects `backend-failure` for a
+     * page index out of range or a closed document, `cancelled` when
+     * `options.signal` aborts.
+     */
+    searchPage(page: number, query: string, options?: TextSearchOptions): Promise<TextMatch[]>;
+    /**
+     * True once `close()` has run. Every further `renderPage` rejects with
+     * `cancelled`, every further `searchPage` with `backend-failure`.
+     */
     readonly closed: boolean;
     /**
      * Release the underlying file handle. `usePdfDocument` owns this for documents

package/dist/react/usePdfDocument.js

@@ -210,6 +210,50 @@ export async function openPdfDocument(source, rasterizer) {
                 },
             };
         },
+        async searchPage(page, query, options) {
+            // `backend-failure`, not `renderPage`'s `cancelled`: nothing was
+            // superseded — the caller asked a closed document a question, which is
+            // a bug in the caller, and "cancelled" is the one code a host is
+            // expected to swallow silently.
+            if (closed) {
+                throw new PdfError('backend-failure', 'searchPage called on a closed PdfDocument');
+            }
+            if (!Number.isInteger(page) || page < 0 || page >= handle.pageCount) {
+                throw new PdfError('backend-failure', `page index ${page} is out of range (pageCount ${handle.pageCount})`);
+            }
+            // Nothing to find, and every engine would either refuse the query or
+            // answer it with nothing — so neither is asked. This is also what makes
+            // a find box that clears itself free.
+            if (query.trim().length === 0) {
+                return [];
+            }
+            if (isAborted(options?.signal)) {
+                throw new PdfError('cancelled', 'searchPage aborted before it started');
+            }
+            // RESOLVED HERE, once, for every backend: a backend is handed the three
+            // options with no defaults of its own left to drift.
+            const request = {
+                page,
+                query,
+                matchCase: options?.matchCase ?? false,
+                wholeWord: options?.wholeWord ?? false,
+                rotation: options?.rotation ?? 0,
+            };
+            let matches;
+            try {
+                matches = await handle.searchText(request, options?.signal);
+            }
+            catch (cause) {
+                throw toPdfError(cause, `Failed to search page ${page}`);
+            }
+            // A backend that answered anyway — the web worker cannot interrupt a
+            // search it has started — must not hand hits to a caller that already
+            // moved on to the next keystroke.
+            if (isAborted(options?.signal)) {
+                throw new PdfError('cancelled', 'searchPage aborted');
+            }
+            return matches;
+        },
         close() {
             if (closed) {
                 return;

package/dist/testing/index.d.ts

@@ -8,7 +8,7 @@
  * directly and never `../rasterizer/index.js`, which pulls in the Skia ingest
  * path.
  */
-export { ARCH_D, ARCH_E, LETTER, createFakeRasterizer, decodeFakeDocRect, fakePageColor, fakePixelSize, } from '../rasterizer/fake.js';
+export { ARCH_D, ARCH_E, FAKE_MATCH_RECT_ORIGIN, FAKE_MATCH_RECT_SIZE, FAKE_MATCH_RECT_STRIDE, LETTER, createFakeRasterizer, decodeFakeDocRect, decodeFakeRotation, fakePageColor, fakePixelSize, searchFakeText, } from '../rasterizer/fake.js';
 export type { FakeFailureModes, FakeRasterizerOptions, } from '../rasterizer/fake.js';
 /**
  * The reference scenes BUILD STEP 1 produced: the composition contract as data,

package/dist/testing/index.js

@@ -8,7 +8,7 @@
  * directly and never `../rasterizer/index.js`, which pulls in the Skia ingest
  * path.
  */
-export { ARCH_D, ARCH_E, LETTER, createFakeRasterizer, decodeFakeDocRect, fakePageColor, fakePixelSize, } from '../rasterizer/fake.js';
+export { ARCH_D, ARCH_E, FAKE_MATCH_RECT_ORIGIN, FAKE_MATCH_RECT_SIZE, FAKE_MATCH_RECT_STRIDE, LETTER, createFakeRasterizer, decodeFakeDocRect, decodeFakeRotation, fakePageColor, fakePixelSize, searchFakeText, } from '../rasterizer/fake.js';
 /**
  * The reference scenes BUILD STEP 1 produced: the composition contract as data,
  * for a backend suite to replay against its own rasterizer. Pure — it reaches

package/dist/types.d.ts

@@ -247,6 +247,13 @@ export interface RasterizerCapabilities {
     /** Honours the abort signal mid-render, not merely between requests. */
     interruptibleRender: boolean;
     text: boolean;
+    /**
+     * `RasterizerHandle.searchText` finds text and returns glyph rects. TRUE for
+     * every shipped backend since 0.4.0 — they are all PDFium, and its text API
+     * is what implements it — and for the fake, which searches a declared
+     * per-page text. False only for the self-describing missing-backend
+     * placeholder, whose `open()` never succeeds anyway.
+     */
     search: boolean;
     links: boolean;
     /**
@@ -298,8 +305,57 @@ export interface RasterizerHandle {
     /** Cheap: must not load a page. */
     pageGeometry(index: number): PageGeometry;
     render(request: RasterRequest, signal?: AbortSignal): Promise<RasterPixels>;
+    /**
+     * Find every occurrence of `request.query` on one page.
+     *
+     * REQUIRED ON THE SEAM, and every shipped backend implements it (the fake
+     * included), so a host can build "find in document" on any of them. The
+     * rects come back in the same doc space the page's rasters use — see
+     * `TextMatch.rects` for the contract — which is what lets a host draw a hit
+     * over the page with the transform it already has. An empty query is the
+     * document's business to short-circuit (`PdfDocument.searchPage` does);
+     * a backend handed one may answer `[]` or search for nothing, both of which
+     * are `[]`.
+     */
+    searchText(request: TextSearchRequest, signal?: AbortSignal): Promise<TextMatch[]>;
     close(): void;
 }
+export interface TextSearchOptions {
+    /** Case-sensitive match. Default false. */
+    matchCase?: boolean;
+    /** Whole-word match. Default false. */
+    wholeWord?: boolean;
+    /**
+     * The HOST's rotation for this page (see RasterRequest.rotation), so rects
+     * come back in the TURNED page's doc space — the space its rasters use.
+     * Default 0.
+     */
+    rotation?: PageRotation;
+    signal?: AbortSignal;
+}
+export interface TextMatch {
+    page: number;
+    /** PDFium character index of the match start on the page, and its length. */
+    charIndex: number;
+    charCount: number;
+    /**
+     * Bounding boxes of the matched glyphs, one per text line the match spans,
+     * in the page's doc space: PDF points, origin at the DISPLAYED page's
+     * top-left, y down, host rotation applied. Empty only for a match PDFium
+     * reports no rects for.
+     */
+    rects: DocRect[];
+    /** The page text around the match, roughly 40 chars each side, whitespace collapsed. */
+    context: string;
+}
+/**
+ * What a backend is handed: the options RESOLVED, so no backend has a default
+ * of its own that could drift from `PdfDocument.searchPage`'s.
+ */
+export interface TextSearchRequest extends Required<Pick<TextSearchOptions, 'matchCase' | 'wholeWord' | 'rotation'>> {
+    page: number;
+    query: string;
+}
 export type RasterRole = 'base' | 'detail';
 /**
  * One rasterized piece, ready to draw.
@@ -337,6 +393,16 @@ export interface PdfPageContent {
     readonly page: number;
     /** Where this page sits in doc space, per the layout function. */
     readonly pageRect: DocRect;
+    /**
+     * Whether this page may be painted at all — false for a page outside the
+     * controller's `allowedPages`. Such a page never holds a raster, and
+     * `PdfContentView` paints NO PAPER for it either: under a stacked layout
+     * (`singlePage()`) every page's rect sits at the origin, so paper for an
+     * unselected page of different extents (a page the host turned a quarter)
+     * would show through beside the selected one. The entry stays in `pages`
+     * so the array remains index-aligned with page numbers.
+     */
+    readonly drawable: boolean;
     /**
      * The whole page at fit scale, as one or more pieces whose union is exactly
      * `pageRect`.

package/ios/Sources/PdfCanvasBridge/PdfCanvasModule.mm

@@ -397,11 +397,75 @@ RCT_EXPORT_METHOD(render
   }];
 }
 
+/* ---------------------------------------------------------------- *
+ * 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 dictionaries. `native-bridge.ts` parses and checks it.
+ *
+ * THE SAME QUEUE AS RENDER, deliberately: PDFium is not thread-safe and the core
+ * serialises everything behind one lock anyway. The same (handle, token) registry
+ * too, so `cancel` stops a superseded search between matches.
+ */
+RCT_EXPORT_METHOD(search
+                  : (double)handle request
+                  : (NSDictionary *)request token
+                  : (double)token resolve
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  pdfcanvas::TextSearchRequest req;
+  req.page = [request[@"page"] intValue];
+  // UTF-16 straight out of the NSString, which already is UTF-16 — no UTF-8 step
+  // that could mangle a supplementary character on the way to PDFium.
+  NSString *query = [request[@"query"] isKindOfClass:NSString.class] ? request[@"query"] : @"";
+  req.query.resize(query.length);
+  if (query.length > 0) {
+    static_assert(sizeof(unichar) == sizeof(char16_t), "unichar is a UTF-16 unit");
+    [query getCharacters:reinterpret_cast<unichar *>(&req.query[0]) range:NSMakeRange(0, query.length)];
+  }
+  req.matchCase = [request[@"matchCase"] isKindOfClass:NSNumber.class] && [request[@"matchCase"] boolValue];
+  req.wholeWord = [request[@"wholeWord"] isKindOfClass:NSNumber.class] && [request[@"wholeWord"] boolValue];
+  // OPTIONAL, DEFAULTING TO 0, for the reason render's is.
+  req.rotation = [request[@"rotation"] isKindOfClass:NSNumber.class] ? [request[@"rotation"] intValue] : 0;
+  const int nativeHandle = static_cast<int>(handle);
+  const int64_t nativeToken = static_cast<int64_t>(token);
+
+  // Registered BEFORE the operation runs — see render.
+  _service->registerCancellation(nativeHandle, nativeToken);
+
+  std::shared_ptr<pdfcanvas::Service> service = _service;
+  [_renderQueue addOperationWithBlock:^{
+    @try {
+      std::string json;
+      try {
+        json = service->searchJson(nativeHandle, req, nativeToken);
+      } catch (const pdfcanvas::PdfError &error) {
+        RejectWithPdfError(reject, error);
+        return;
+      } catch (const std::exception &error) {
+        RejectWith(reject, pdfcanvas::ErrorCode::BackendFailure,
+                   [NSString stringWithUTF8String:error.what()]);
+        return;
+      }
+      // PURE ASCII by construction (`textMatchesToJson`), so UTF-8 decoding it is
+      // the identity.
+      resolve([NSString stringWithUTF8String:json.c_str()]);
+    } @catch (NSException *exception) {
+      RejectWith(reject, pdfcanvas::ErrorCode::BackendFailure,
+                 [NSString stringWithFormat:@"%@: %@", exception.name, exception.reason]);
+    }
+  }];
+}
+
 /**
  * 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.
+ * 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.
  */
 RCT_EXPORT_METHOD(cancel : (double)handle token : (double)token) {
   _service->cancel(static_cast<int>(handle), static_cast<int64_t>(token));

package/native/core/include/pdfcanvas/document.h

@@ -74,6 +74,23 @@ class Document {
   RasterPixels render(const RasterRequest& request, Cancellation* signal,
                       PixelSink* sink);
 
+  /// Every occurrence of `request.query` on one page, in reading order.
+  ///
+  /// PDFium's own search (`FPDFText_FindStart` / `FindNext`), on a text page
+  /// parsed once and cached with the page it belongs to — a find box searches
+  /// again on every keystroke, and `FPDFText_LoadPage` is the call that walks
+  /// the content stream. Each match's rects are mapped through the SAME
+  /// display matrix the rasters use (`FPDF_PageToDevice` with the displayed
+  /// box and the host's rotate), so a hit drawn at a rect lands on the glyphs.
+  ///
+  /// `signal` may be null. It is observed before the lock, after it, and
+  /// between matches — a superseded search holds the lock for at most one
+  /// more match. An empty query answers `{}` without touching the page.
+  /// Throws `not-found` for a missing page, `backend-failure` for a closed
+  /// document or a rotation that is not a quarter turn, `corrupt` when PDFium
+  /// cannot read the page's text, `cancelled`.
+  std::vector<TextMatch> searchText(const TextSearchRequest& request, Cancellation* signal);
+
   /// Releases every PDFium object. Blocks until an in-flight render on this
   /// document finishes (it holds the library lock), and is therefore free of
   /// the use-after-free window the Android pool's close had. Idempotent.

package/native/core/include/pdfcanvas/service.h

@@ -16,6 +16,7 @@
 #include <cstdint>
 #include <memory>
 #include <mutex>
+#include <string>
 #include <unordered_map>
 #include <vector>
 
@@ -55,7 +56,15 @@ class Service {
   RasterPixels render(int handle, const RasterRequest& request, int64_t token,
                       bool useSlot);
 
-  /// Best-effort, and genuinely mid-render: sets the signal a render polls.
+  /// Searches one page on the calling thread and returns the WIRE FORM — the
+  /// JSON `textMatchesToJson` writes, pure ASCII, one bridge value however
+  /// many hits there are. The SAME (handle, token) registry as `render`:
+  /// register first, and `cancel` stops the search between matches. The
+  /// signal is consumed and unregistered on every path out.
+  std::string searchJson(int handle, const TextSearchRequest& request, int64_t token);
+
+  /// Best-effort, and genuinely mid-render: sets the signal a render (or a
+  /// search) polls.
   void cancel(int handle, int64_t token);
 
   /// Closes one document. Blocks until its in-flight render finishes.
@@ -74,6 +83,10 @@ class Service {
   size_t openCount() const;
 
  private:
+  /// One job's (signal, document) pair, unregistering the signal on
+  /// destruction. Shared by `render` and `searchJson`.
+  struct Lease;
+
   static int64_t signalKey(int handle, int64_t token) noexcept;
   std::shared_ptr<Document> documentFor(int handle);