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

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

@@ -220,6 +220,26 @@ export interface RasterRequest {
      */
     annotations: boolean;
     background: 'white' | 'transparent';
+    /**
+     * DEVICE rotation applied on top of the page's own `/Rotate`, in degrees
+     * clockwise. Optional: absent means 0, and every backend reads it as
+     * `rotation ?? 0`, so a request built before the field existed renders
+     * exactly as it did.
+     *
+     * THE COORDINATE CONTRACT: `docRect` and `scale` are expressed in the
+     * ROTATED page's doc space. For 90 and 270 the page's extents are swapped —
+     * a 612x792 page rotated 90 is a 792x612 page whose origin is its displayed
+     * top-left — so a whole-page request for it is `{0, 0, 792, 612}`. That is
+     * what lets a backend keep the negative-offset rect mechanism unchanged: it
+     * describes the whole TURNED page at `scale` and slides it by
+     * `(-round(x·s), -round(y·s))`, exactly as it does an upright one. The only
+     * thing a backend swaps is the page box it hands the engine.
+     *
+     * This is NOT `PageGeometry.rotation`. That one is the document's `/Rotate`,
+     * already folded into every size and render by PDFium and informational
+     * here; this one is a host's choice, layered on top. See `./rotation.ts`.
+     */
+    rotation?: PageRotation;
 }
 export interface RasterizerCapabilities {
     /** Can render PDF-embedded annotations into the raster. */
@@ -227,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;
     /**
@@ -278,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.
@@ -317,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

@@ -324,6 +324,11 @@ RCT_EXPORT_METHOD(render
   req.width = [request[@"width"] doubleValue];
   req.height = [request[@"height"] doubleValue];
   req.scale = [request[@"scale"] doubleValue];
+  // OPTIONAL, DEFAULTING TO 0: a JS bundle older than this binary never sends it,
+  // and a page must not turn because a key is missing. The class check also covers
+  // a JS `null`, which the bridge delivers as `NSNull` rather than `nil`. The core
+  // validates the value; this only decides what "absent" means.
+  req.rotation = [request[@"rotation"] isKindOfClass:NSNumber.class] ? [request[@"rotation"] intValue] : 0;
   req.annotations = request[@"annotations"] == nil ? true : [request[@"annotations"] boolValue];
   req.background = [@"transparent" isEqual:request[@"background"]] ? pdfcanvas::Background::Transparent
                                                                     : pdfcanvas::Background::White;
@@ -392,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/CMakeLists.txt

@@ -80,6 +80,13 @@ if(WIN32)
 elseif(APPLE)
   set_target_properties(pdfcanvas_tests PROPERTIES
     BUILD_RPATH "${PDFCANVAS_PDFIUM_DIR}/lib")
+  # The rpath above cannot help on its own: the release dylib's install name is
+  # the CWD-relative `./libpdfium.dylib` (`otool -D`), not `@rpath/…`, so dyld
+  # looks beside the working directory and nowhere else. ctest runs the binary
+  # from the build directory, so — as on Windows — the library is copied there.
+  add_custom_command(TARGET pdfcanvas_tests POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+      "${PDFCANVAS_PDFIUM_DIR}/lib/libpdfium.dylib" "$<TARGET_FILE_DIR:pdfcanvas_tests>")
 else()
   set_target_properties(pdfcanvas_tests PROPERTIES
     BUILD_RPATH "${PDFCANVAS_PDFIUM_DIR}/lib")

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);
 

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

@@ -0,0 +1,52 @@
+// The two text-search rules that are not PDFium calls: how a match's context
+// reads, and how a page's matches cross the bridge.
+//
+// PURE — no PDFium, no lock, no document — so both are provable on their own,
+// and both have a TypeScript twin that must agree with them:
+// `src/rasterizer/text-search.ts` (the context rule, used by the web engine
+// and the fake) and `parseTextMatches` in `src/rasterizer/native-bridge.ts`
+// (the reader of the JSON written here).
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "pdfcanvas/types.h"
+
+namespace pdfcanvas {
+
+/// Characters of page text a match carries either side of itself. Mirrors
+/// `CONTEXT_CHARS` in `src/rasterizer/text-search.ts`.
+constexpr int kContextChars = 40;
+
+/// Whether a UTF-16 code unit is whitespace as ECMAScript's `\s` defines it —
+/// the exact set `collapseWhitespace` in `text-search.ts` collapses, so a
+/// context reads the same from every engine.
+bool isJsWhitespace(char16_t unit) noexcept;
+
+/// Runs of whitespace collapsed to one U+0020, both ends trimmed. PDFium's
+/// text page carries `\r\n` at every line break and a "find" list wants one
+/// line per hit.
+std::u16string collapseWhitespace(const std::u16string& text);
+
+/// `TextMatch[]` as ONE JSON string, the shape `parseTextMatches` reads:
+///
+///   [{"page":0,"charIndex":6,"charCount":8,
+///     "rects":[{"x":..,"y":..,"width":..,"height":..}],"context":".."}]
+///
+/// THE OUTPUT IS PURE ASCII: every string character outside printable ASCII —
+/// and `"` and `\` — is written as a `\uXXXX` escape of its UTF-16 unit, which
+/// `JSON.parse` reassembles, surrogate pairs included. That is what lets both
+/// bindings hand it over without a transcoding step: JNI's `NewStringUTF`
+/// takes "modified UTF-8", which is identical to ASCII and to nothing else,
+/// and `+[NSString stringWithUTF8String:]` reads ASCII as itself.
+///
+/// NUMBERS ARE LOCALE-PROOF. `%.17g` round-trips a double exactly, but printf
+/// honours `LC_NUMERIC`, and a host that has called `setlocale` for a
+/// comma-decimal locale would get `72,5` — which is not JSON. The one
+/// separator `%g` can emit is replaced back. A non-finite value (which the
+/// search never produces) is written as 0 rather than as the invalid token
+/// `nan`.
+std::string textMatchesToJson(const std::vector<TextMatch>& matches);
+
+}  // namespace pdfcanvas

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

@@ -48,6 +48,14 @@ struct RasterRequest {
   double scale = 1;
   /// Draw PDF-embedded annotations (and form fields) into the raster.
   bool annotations = true;
+  /// The HOST's rotation on top of the page's `/Rotate`, in degrees clockwise:
+  /// 0, 90, 180 or 270 — anything else is refused. `x`/`y`/`width`/`height`
+  /// are in the TURNED page's doc space (extents swapped for a quarter turn),
+  /// which is what keeps the negative-offset rect mechanism unchanged: the
+  /// only thing the render swaps is the page box it hands PDFium. Absent on
+  /// the wire means 0 on both bindings, so a JS/binary version skew cannot
+  /// turn a page by accident.
+  int rotation = 0;
   Background background = Background::White;
 
   /// Destination width in device pixels: ROUND, not ceil, and at least 1 —
@@ -59,6 +67,47 @@ struct RasterRequest {
   int pixelHeight() const;
 };
 
+/// A rect in page-local doc space: PDF points, y-down, origin at the DISPLAYED
+/// page's top-left. `DocRect` in `src/types.ts`.
+struct DocRect {
+  double x = 0;
+  double y = 0;
+  double width = 0;
+  double height = 0;
+};
+
+/// One page's search, mirroring `TextSearchRequest` in `src/types.ts`: every
+/// option already resolved by `PdfDocument.searchPage`, so no default here can
+/// drift from the TypeScript one.
+struct TextSearchRequest {
+  int page = 0;
+  /// UTF-16 code units, exactly as JavaScript holds them. Neither binding
+  /// transcodes — JNI's `GetStringChars` and `-[NSString getCharacters:]` both
+  /// hand over UTF-16 — and PDFium's `FPDF_WIDESTRING` is UTF-16LE, so the
+  /// query reaches `FPDFText_FindStart` with no UTF-8 step anywhere that could
+  /// mangle a supplementary character (JNI's "modified UTF-8" would).
+  std::u16string query;
+  bool matchCase = false;
+  bool wholeWord = false;
+  /// The HOST's rotation, exactly as `RasterRequest::rotation`: 0/90/180/270,
+  /// anything else refused. Rects come back in the TURNED page's doc space —
+  /// the space that page's rasters are drawn in.
+  int rotation = 0;
+};
+
+/// One hit, mirroring `TextMatch` in `src/types.ts`.
+struct TextMatch {
+  int page = 0;
+  /// PDFium's character index of the first matched character, and the count.
+  int charIndex = 0;
+  int charCount = 0;
+  /// One per text line the match spans, in the request's doc space.
+  std::vector<DocRect> rects;
+  /// `kContextChars` of page text either side, whitespace collapsed. UTF-16,
+  /// for the same reason the query is.
+  std::u16string context;
+};
+
 /// Where a document's bytes come from. Exactly one of `path` / `bytes` is used;
 /// a non-empty path wins.
 struct Source {

package/native/core/pdfcanvas-core.cmake

@@ -19,4 +19,5 @@ set(PDFCANVAS_CORE_SOURCES
   "${PDFCANVAS_CORE_DIR}/src/pixels.cpp"
   "${PDFCANVAS_CORE_DIR}/src/service.cpp"
   "${PDFCANVAS_CORE_DIR}/src/slots.cpp"
+  "${PDFCANVAS_CORE_DIR}/src/text_search.cpp"
 )