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

package/dist/controller.js

@@ -137,6 +137,7 @@ export function createPdfController(options) {
             page,
             pageRect,
             layoutScale: Number.isFinite(raw) && raw > 0 ? raw : 1,
+            rotation: options.rotations?.[page] ?? 0,
         };
     });
     const listeners = new Set();
@@ -147,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,
@@ -405,24 +409,35 @@ export function createPdfController(options) {
         };
         const renderOne = async (item, slot, info) => {
             const startedAt = now();
+            const request = {
+                page: item.page,
+                // Page-LOCAL rect: the planner works in LAYOUT space, but a backend
+                // renders a page and knows nothing about where the layout put it.
+                // For a page the host has turned this is the ROTATED page's space:
+                // `pageRects` and `pages` both carry the swapped extents, which is
+                // what keeps `layoutScale` at 1 and lets the backend slide the whole
+                // turned page exactly as it slides an upright one.
+                docRect: {
+                    x: (item.docRect.x - info.pageRect.x) / info.layoutScale,
+                    y: (item.docRect.y - info.pageRect.y) / info.layoutScale,
+                    width: item.docRect.width / info.layoutScale,
+                    height: item.docRect.height / info.layoutScale,
+                },
+                scale: item.scale * info.layoutScale,
+                // See `PdfControllerOptions.annotations`: true unless the host
+                // draws the PDF's annotations itself.
+                annotations: drawAnnotations,
+                background: 'white',
+            };
+            // STAMPED ONLY WHEN IT IS NOT THE DEFAULT. A host that never rotates
+            // hands its backend the exact request it always did, key for key — a
+            // host-injected backend that compares requests structurally sees no
+            // change at all — and every shipped backend reads `rotation ?? 0`.
+            if (info.rotation !== 0)
+                request.rotation = info.rotation;
             let pixels;
             try {
-                pixels = await handle.render({
-                    page: item.page,
-                    // Page-LOCAL rect: the planner works in LAYOUT space, but a backend
-                    // renders a page and knows nothing about where the layout put it.
-                    docRect: {
-                        x: (item.docRect.x - info.pageRect.x) / info.layoutScale,
-                        y: (item.docRect.y - info.pageRect.y) / info.layoutScale,
-                        width: item.docRect.width / info.layoutScale,
-                        height: item.docRect.height / info.layoutScale,
-                    },
-                    scale: item.scale * info.layoutScale,
-                    // See `PdfControllerOptions.annotations`: true unless the host
-                    // draws the PDF's annotations itself.
-                    annotations: drawAnnotations,
-                    background: 'white',
-                }, state.abort.signal);
+                pixels = await handle.render(request, state.abort.signal);
             }
             catch (error) {
                 missing.push(item.key);
@@ -819,6 +834,7 @@ export function createPdfController(options) {
             return Object.freeze({
                 page: previous.page,
                 pageRect: previous.pageRect,
+                drawable: previous.drawable,
                 base,
                 detail,
                 retiring,
@@ -987,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

@@ -14,13 +14,19 @@
  *     checks and an accidental clip is visible as a blank margin;
  *   - each piece carries a 1px border, so a piece that has been inset or
  *     stretched shows its border in the wrong place;
- *   - each piece encodes its own doc rect into a corner swatch, so a test can
- *     read back what a raster BELIEVES it is without any Skia in the loop.
+ *   - each piece encodes its own doc rect AND its rotation into a corner
+ *     swatch, so a test can read back what a raster BELIEVES it is without any
+ *     Skia in the loop;
+ *   - the checker is drawn in the PAGE's own space and turned by the request's
+ *     `rotation`, the way a real engine turns its page — so a raster at 90 is
+ *     the raster at 0 turned a quarter clockwise, pixel for pixel outside the
+ *     border and swatch, and a pipeline that rotated its geometry but forgot
+ *     to stamp the request shows an unturned board in a turned frame.
  *
  * 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;
@@ -47,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;
@@ -89,4 +103,24 @@ export declare function fakePageColor(page: number): [number, number, number];
  * was too small to carry a swatch.
  */
 export declare function decodeFakeDocRect(pixels: RasterPixels): DocRect | null;
+/**
+ * Read the rotation a fake raster was rendered at, or null when the raster was
+ * too small to carry a swatch. What a pipeline test reads to prove the
+ * 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

@@ -14,12 +14,20 @@
  *     checks and an accidental clip is visible as a blank margin;
  *   - each piece carries a 1px border, so a piece that has been inset or
  *     stretched shows its border in the wrong place;
- *   - each piece encodes its own doc rect into a corner swatch, so a test can
- *     read back what a raster BELIEVES it is without any Skia in the loop.
+ *   - each piece encodes its own doc rect AND its rotation into a corner
+ *     swatch, so a test can read back what a raster BELIEVES it is without any
+ *     Skia in the loop;
+ *   - the checker is drawn in the PAGE's own space and turned by the request's
+ *     `rotation`, the way a real engine turns its page — so a raster at 90 is
+ *     the raster at 0 turned a quarter clockwise, pixel for pixel outside the
+ *     border and swatch, and a pipeline that rotated its geometry but forgot
+ *     to stamp the request shows an unturned board in a turned frame.
  *
  * Everything here is a pure function of the request, so the same request always
  * 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)
@@ -55,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,
@@ -171,9 +180,10 @@ function writePixel(out, offset, r, g, b, a, format) {
  * The corner swatch
  * ------------------------------------------------------------------ */
 /**
- * The swatch is RAW BYTES, not a colour: four pixels, each carrying one doc
- * rect component as a 24-bit fixed-point value in channels 0..2 with channel 3
- * held at 255. Because it is written without the format swizzle, the decoder is
+ * The swatch is RAW BYTES, not a colour: five pixels, each carrying one value
+ * as a 24-bit fixed-point number in channels 0..2 with channel 3 held at 255 —
+ * the four doc rect components, then the request's rotation in degrees.
+ * Because it is written without the format swizzle, the decoder is
  * format-independent — it reads back the same numbers from an RGBA and a BGRA
  * raster.
  */
@@ -182,7 +192,9 @@ const SWATCH_FIXED_POINT = 16;
 const SWATCH_BIAS = 0x800000;
 const SWATCH_ORIGIN_X = 1;
 const SWATCH_ROW = 1;
-const SWATCH_PIXELS = 4;
+const SWATCH_PIXELS = 5;
+/** Index of the rotation value within the swatch, after x, y, width, height. */
+const SWATCH_ROTATION = 4;
 /** Smallest raster that has room for the swatch inside its border. */
 const SWATCH_MIN_WIDTH = SWATCH_ORIGIN_X + SWATCH_PIXELS + 1;
 const SWATCH_MIN_HEIGHT = SWATCH_ROW + 2;
@@ -194,7 +206,7 @@ function encodeSwatchValue(out, offset, value) {
     out[offset + 2] = clamped & 0xff;
     out[offset + 3] = 255;
 }
-function encodeSwatch(out, rowBytes, width, height, docRect) {
+function encodeSwatch(out, rowBytes, width, height, docRect, rotation) {
     if (width < SWATCH_MIN_WIDTH || height < SWATCH_MIN_HEIGHT) {
         return;
     }
@@ -203,39 +215,81 @@ function encodeSwatch(out, rowBytes, width, height, docRect) {
     encodeSwatchValue(out, base + BYTES_PER_PIXEL, docRect.y);
     encodeSwatchValue(out, base + BYTES_PER_PIXEL * 2, docRect.width);
     encodeSwatchValue(out, base + BYTES_PER_PIXEL * 3, docRect.height);
+    encodeSwatchValue(out, base + BYTES_PER_PIXEL * SWATCH_ROTATION, rotation);
+}
+/** One swatch value back out, or null when the raster is too small to carry a
+ * swatch at all. `component` is the pixel index within the swatch. */
+function decodeSwatchValue(pixels, component) {
+    const { bytes, width, height, rowBytes } = pixels;
+    if (width < SWATCH_MIN_WIDTH || height < SWATCH_MIN_HEIGHT) {
+        return null;
+    }
+    const o = SWATCH_ROW * rowBytes + (SWATCH_ORIGIN_X + component) * BYTES_PER_PIXEL;
+    // In range by the size guard above; `?? 0` satisfies
+    // noUncheckedIndexedAccess on TypedArray indexing.
+    const raw = ((bytes[o] ?? 0) << 16) | ((bytes[o + 1] ?? 0) << 8) | (bytes[o + 2] ?? 0);
+    return (raw - SWATCH_BIAS) / SWATCH_FIXED_POINT;
 }
 /**
  * Read the doc rect a fake raster believes it covers, or null when the raster
  * was too small to carry a swatch.
  */
 export function decodeFakeDocRect(pixels) {
-    const { bytes, width, height, rowBytes } = pixels;
-    if (width < SWATCH_MIN_WIDTH || height < SWATCH_MIN_HEIGHT) {
+    const x = decodeSwatchValue(pixels, 0);
+    const y = decodeSwatchValue(pixels, 1);
+    const width = decodeSwatchValue(pixels, 2);
+    const height = decodeSwatchValue(pixels, 3);
+    if (x === null || y === null || width === null || height === null) {
         return null;
     }
-    const base = SWATCH_ROW * rowBytes + SWATCH_ORIGIN_X * BYTES_PER_PIXEL;
-    const read = (component) => {
-        const o = base + component * BYTES_PER_PIXEL;
-        // In range by the size guard above; `?? 0` satisfies
-        // noUncheckedIndexedAccess on TypedArray indexing.
-        const raw = ((bytes[o] ?? 0) << 16) |
-            ((bytes[o + 1] ?? 0) << 8) |
-            (bytes[o + 2] ?? 0);
-        return (raw - SWATCH_BIAS) / SWATCH_FIXED_POINT;
-    };
-    return {
-        x: read(0),
-        y: read(1),
-        width: read(2),
-        height: read(3),
-    };
+    return { x, y, width, height };
+}
+/**
+ * Read the rotation a fake raster was rendered at, or null when the raster was
+ * too small to carry a swatch. What a pipeline test reads to prove the
+ * controller's stamp reached the backend.
+ */
+export function decodeFakeRotation(pixels) {
+    const rotation = decodeSwatchValue(pixels, SWATCH_ROTATION);
+    if (rotation === null)
+        return null;
+    return isPageRotation(rotation) ? rotation : null;
 }
 /* ------------------------------------------------------------------ *
  * Rendering
  * ------------------------------------------------------------------ */
-function renderPixels(request, cfg) {
+/**
+ * The inverse of the request's rotation: a point in the TURNED page's doc space
+ * back to the page's own. `pageWidth` / `pageHeight` are the page's intrinsic
+ * (unturned) extents.
+ *
+ * These are the inverses of PDFium's `CPDF_Page::GetDisplayMatrix` for rotate
+ * 1..3, restated in y-down doc units — the same mapping the real backends'
+ * tests hold a turned render to, so the fake and the engine agree on what "90
+ * clockwise" means.
+ */
+function unrotate(rotation, pageWidth, pageHeight) {
+    switch (rotation) {
+        case 90:
+            return (x, y) => [y, pageHeight - x];
+        case 180:
+            return (x, y) => [pageWidth - x, pageHeight - y];
+        case 270:
+            return (x, y) => [pageWidth - y, x];
+        default:
+            return (x, y) => [x, y];
+    }
+}
+function renderPixels(request, cfg, geometry) {
     const { docRect, scale, page, background } = request;
     const { width, height } = fakePixelSize(request);
+    // Read as `?? 0` and then VALIDATED, as every real backend does: the fake
+    // stands in for them in the controller suite, so it must refuse what they
+    // refuse rather than quietly draw an upright page.
+    const rotation = request.rotation ?? 0;
+    if (!isPageRotation(rotation)) {
+        throw new PdfError('backend-failure', `Fake rasterizer: rotation must be 0, 90, 180 or 270, got ${String(rotation)}.`);
+    }
     if (width * height > cfg.maxPixels) {
         throw new PdfError('out-of-memory', `Fake rasterizer refused a ${width}x${height} raster ` +
             `(${width * height} pixels > maxPixels ${cfg.maxPixels}).`);
@@ -256,18 +310,23 @@ function renderPixels(request, cfg) {
             writePixel(bytes, o, tintR, tintG, tintB, 255, cfg.format);
         }
     }
-    // Dark checker cells, in DOC space. Pixel CENTRES are converted to doc
-    // coordinates — a corner-based conversion puts the sample exactly on a cell
-    // boundary whenever the piece origin happens to align with one, and the
-    // parity then flips on a floating-point tie.
+    // Dark checker cells, in the PAGE's DOC space. Pixel CENTRES are converted
+    // to doc coordinates — a corner-based conversion puts the sample exactly on
+    // a cell boundary whenever the piece origin happens to align with one, and
+    // the parity then flips on a floating-point tie. The request's rect is in
+    // the TURNED page's space, so each centre is mapped back through the inverse
+    // rotation before its cell is looked up: that is what makes the board turn
+    // with the request, the way a real engine's page does.
     const cell = cfg.checkerDocSize;
+    const toPage = unrotate(rotation, geometry.width, geometry.height);
     for (let py = 0; py < height; py++) {
-        const docY = docRect.y + (py + 0.5) / scale;
-        const cellY = Math.floor(docY / cell);
+        const turnedY = docRect.y + (py + 0.5) / scale;
         let offset = py * rowBytes;
         for (let px = 0; px < width; px++, offset += BYTES_PER_PIXEL) {
-            const docX = docRect.x + (px + 0.5) / scale;
+            const turnedX = docRect.x + (px + 0.5) / scale;
+            const [docX, docY] = toPage(turnedX, turnedY);
             const cellX = Math.floor(docX / cell);
+            const cellY = Math.floor(docY / cell);
             if (((cellX + cellY) & 1) === 1) {
                 writePixel(bytes, offset, r, g, b, 255, cfg.format);
             }
@@ -288,7 +347,7 @@ function renderPixels(request, cfg) {
             writePixel(bytes, row + lastCol, 0, 0, 0, 255, cfg.format);
         }
     }
-    encodeSwatch(bytes, rowBytes, width, height, docRect);
+    encodeSwatch(bytes, rowBytes, width, height, docRect, rotation);
     return {
         bytes,
         width,
@@ -298,6 +357,58 @@ function renderPixels(request, cfg) {
         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
  * ------------------------------------------------------------------ */
@@ -384,7 +495,7 @@ function createHandle(cfg) {
         async render(request, signal) {
             throwIfAborted(signal);
             requireOpen();
-            requirePage(request.page);
+            const geometry = requirePage(request.page);
             if (cfg.latencyMs > 0) {
                 await delay(cfg.latencyMs, signal);
             }
@@ -396,7 +507,24 @@ function createHandle(cfg) {
             if (failure) {
                 throw new PdfError(failure, `Fake rasterizer failed page ${request.page} by configuration.`);
             }
-            return renderPixels(request, 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;
@@ -413,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. */
@@ -81,15 +81,52 @@ export interface NativeRenderRequest {
     scale: number;
     annotations: boolean;
     background: 'white' | 'transparent';
+    /**
+     * Degrees clockwise, 0 / 90 / 180 / 270, on top of the page's `/Rotate`.
+     *
+     * ALWAYS PRESENT on the wire — 0 when the `RasterRequest` carried none —
+     * while both native modules read it as optional-defaulting-to-0. That pair
+     * is what makes a version skew safe in both directions: a JS bundle newer
+     * than its binary sends a key the binary never looks for, and a binary newer
+     * than its bundle reads 0 for a key that never arrives. Neither can turn a
+     * page by accident.
+     */
+    rotation: number;
 }
 export interface NativeSource {
     uri?: string;
     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
@@ -200,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.

package/dist/rasterizer/native-bridge.js

@@ -227,6 +227,63 @@ export function negotiateTransport(native, lookup = lookupTakePixels) {
         return BASE64_TRANSPORT;
     }
 }
+/* ------------------------------------------------------------------ *
+ * Text matches
+ * ------------------------------------------------------------------ */
+const isFiniteNumber = (value) => typeof value === 'number' && Number.isFinite(value);
+function toDocRect(value, where) {
+    const rect = value;
+    if (rect === null ||
+        typeof rect !== 'object' ||
+        !isFiniteNumber(rect.x) ||
+        !isFiniteNumber(rect.y) ||
+        !isFiniteNumber(rect.width) ||
+        !isFiniteNumber(rect.height)) {
+        throw new PdfError('backend-failure', `The native module's search result has a malformed rect at ${where}.`);
+    }
+    return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+}
+/**
+ * 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 function parseTextMatches(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        throw new PdfError('backend-failure', `The native module's search result is not JSON: ` +
+            `${error?.message ?? String(error)}`, { cause: error });
+    }
+    if (!Array.isArray(parsed)) {
+        throw new PdfError('backend-failure', "The native module's search result is not an array.");
+    }
+    return parsed.map((entry, i) => {
+        const match = entry;
+        if (match === null ||
+            typeof match !== 'object' ||
+            !isFiniteNumber(match.page) ||
+            !isFiniteNumber(match.charIndex) ||
+            !isFiniteNumber(match.charCount) ||
+            !Array.isArray(match.rects) ||
+            typeof match.context !== 'string') {
+            throw new PdfError('backend-failure', `The native module's search result has a malformed match at [${i}].`);
+        }
+        return {
+            page: match.page,
+            charIndex: match.charIndex,
+            charCount: match.charCount,
+            rects: match.rects.map((rect, j) => toDocRect(rect, `[${i}].rects[${j}]`)),
+            context: match.context,
+        };
+    });
+}
 /* ------------------------------------------------------------------ *
  * Geometry
  * ------------------------------------------------------------------ */
@@ -343,6 +400,7 @@ export function createNativeHandle(native, opened, transport, alpha, label) {
                     scale: request.scale,
                     annotations: request.annotations,
                     background: request.background,
+                    rotation: request.rotation ?? 0,
                 }, token);
             }
             catch (error) {
@@ -386,6 +444,44 @@ export function createNativeHandle(native, opened, transport, alpha, label) {
                 },
             };
         },
+        async searchText(request, signal) {
+            if (closed) {
+                throw new PdfError('backend-failure', `${label} rasterizer handle is closed.`);
+            }
+            requirePage(request.page);
+            if (signal?.aborted) {
+                throw new PdfError('cancelled', 'Search was aborted before it started.');
+            }
+            // The capability says true for this binary's JS, but an OTA bundle can
+            // be newer than the binary under it, and `NativeModules.PdfCanvas` only
+            // has the methods that binary exports. Named here rather than left as
+            // "native.search is not a function" from inside the bridge.
+            if (typeof native.search !== 'function') {
+                throw new PdfError('unsupported', 'This app binary predates text search in the PdfCanvas native ' +
+                    'module (0.4.0). A native rebuild is needed; an OTA update ' +
+                    'cannot add it.');
+            }
+            const token = nextToken++;
+            const onAbort = () => native.cancel(opened.handle, token);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            let json;
+            try {
+                json = await native.search(opened.handle, {
+                    page: request.page,
+                    query: request.query,
+                    matchCase: request.matchCase,
+                    wholeWord: request.wholeWord,
+                    rotation: request.rotation,
+                }, token);
+            }
+            catch (error) {
+                throw toPdfError(error, `Could not search page ${request.page}`);
+            }
+            finally {
+                signal?.removeEventListener('abort', onAbort);
+            }
+            return parseTextMatches(json);
+        },
         close() {
             if (closed)
                 return;

package/dist/rasterizer/native.d.ts

@@ -22,8 +22,8 @@
  */
 import type { TakePixels } from './native-bridge.js';
 import type { PageRasterizer, RasterizerCapabilities } from '../types.js';
-export { TRANSPORT_PROBE_BYTES, bytesFromResult, decodeBase64, encodeBase64, lookupTakePixels, negotiateTransport, toPageGeometry, } from './native-bridge.js';
-export type { NativeOpenResult, NativePdfPage, NativeRenderRequest, NativeRenderResult, NativeSource, NativeTransport, PdfCanvasNativeModule, TakePixels, } from './native-bridge.js';
+export { TRANSPORT_PROBE_BYTES, bytesFromResult, decodeBase64, encodeBase64, lookupTakePixels, negotiateTransport, parseTextMatches, toPageGeometry, } from './native-bridge.js';
+export type { NativeOpenResult, NativePdfPage, NativeRenderRequest, NativeRenderResult, NativeSearchRequest, NativeSource, NativeTransport, PdfCanvasNativeModule, TakePixels, } from './native-bridge.js';
 export type NativePlatform = 'ios' | 'android';
 export declare const NATIVE_CAPABILITIES: RasterizerCapabilities;
 export interface NativeRasterizerOptions {