@reekon-tools/react-native-pdf-canvas 0.1.0

package/ios/Sources/PdfCanvasBridge/PdfCanvasModule.mm

@@ -0,0 +1,743 @@
+#import "PdfCanvasModule.h"
+
+// `<React/RCTBridgeModule.h>` only FORWARD-DECLARES `RCTBridge`, so the category
+// below and every `self.bridge` message need the real header. Compiling without it
+// fails as "cannot define category for undefined class", which reads like a missing
+// pod dependency rather than a missing import.
+#import <React/RCTBridge.h>
+#import <React/RCTLog.h>
+// `ObjCInteropTurboModule` — a PUBLIC pod header, exposed by React-NativeModulesApple
+// as `ReactCommon/RCTInteropTurboModule.h`. See the note above `getTurboModule:` for
+// why this module builds the interop wrapper itself instead of letting the manager do
+// it.
+#import <ReactCommon/RCTInteropTurboModule.h>
+#import <ReactCommon/RCTTurboModule.h>
+
+#import <atomic>
+
+#import <PdfCanvasCancellation.h>
+#import <PdfCanvasDocumentPool.h>
+#import <PdfCanvasErrorCode.h>
+#import <PdfCanvasPageGeometry.h>
+#import <PdfCanvasRasterPixels.h>
+#import <PdfCanvasRasterRequest.h>
+#import <PdfCanvasRasterizer.h>
+
+#import <PdfCanvasSlots.h>
+
+/**
+ * ------------------------------------------------------------------------
+ * HOW THIS MODULE GETS A `jsi::Runtime`, AND THE TWO ROUTES THAT DO NOT WORK
+ * ------------------------------------------------------------------------
+ *
+ * The JSI transport needs a runtime to install a host function into. There are four
+ * plausible ways to get one and only two of them work, so both the choice and the
+ * rejects are recorded here — each reject was tried on a real device.
+ *
+ * 1. `installJSIBindingsWithRuntime:callInvoker:` — WHAT THIS FILE USES. React
+ *    Native calls it with a live `jsi::Runtime &` on the JS thread, at module
+ *    construction, BEFORE JS can call any method on the module. That last part is
+ *    what makes it better than anything the JS side could trigger: the host function
+ *    exists before the first `installJsiTransport()` can look for it, so no render
+ *    can race the decision. It is the same hook `RCTBlobManager` uses.
+ *
+ *    THE CATCH, and it is why `getTurboModule:` is implemented below:
+ *    `RCTTurboModuleManager` only calls it for a module that responds to
+ *    `getTurboModule:` (`provideTurboModule:`, around line 408 of
+ *    RCTTurboModuleManager.mm). A plain `RCT_EXPORT_MODULE` class goes down
+ *    `provideLegacyModule:` instead and is never asked. So this module returns an
+ *    `ObjCInteropTurboModule` — exactly what the interop layer would have built for
+ *    it — which changes nothing about how its methods are marshalled and everything
+ *    about whether it is offered the runtime.
+ *
+ * 2. `self.bridge.runtime` — the FALLBACK, for the old architecture, where
+ *    `getTurboModule:` is never called and `RCTCxxBridge` really does answer.
+ *
+ *    IT DOES NOT WORK UNDER BRIDGELESS, MEASURED. `RCTInstance` does create an
+ *    `RCTBridgeProxy` with `runtime:_reactInstance->getJavaScriptContext()` and
+ *    `RCTTurboModuleManager` does assign it to a module's `bridge` property — but
+ *    `RCTBridgeProxy` is an `NSProxy` that overrides `methodSignatureForSelector:`
+ *    and `forwardInvocation:` and does NOT override `respondsToSelector:`, so a
+ *    `respondsToSelector:@selector(runtime)` guard answers NO for a method the proxy
+ *    genuinely implements. On device this produced exactly one line —
+ *    "[PdfCanvas] No bridge runtime is reachable" — and a session that rendered
+ *    every tile through base64. Dropping the guard and messaging it anyway would
+ *    work, and is not what this does: a bare message to an `NSProxy` whose
+ *    `forwardInvocation:` logs an error and returns garbage is not a thing to do on
+ *    the strength of a reading of one version's source.
+ *
+ *    (`@shopify/react-native-skia`'s `SkiaManager.mm` uses this route with an
+ *    `if (bridge.runtime)` guard. That is not evidence it works under bridgeless —
+ *    on the new architecture skia installs through its own codegen'd spec and the
+ *    bridge path is its legacy branch.)
+ *
+ * 3. `RCTCallInvokerModule` + `callInvoker->invokeSync` — REJECTED, and it would
+ *    DEADLOCK. `RuntimeSchedulerCallInvoker::invokeSync` calls
+ *    `RuntimeScheduler_Modern::executeNowOnTheSameThread`, whose re-entrancy guard is
+ *    a `thread_local` pointer set only INSIDE itself. A blocking synchronous native
+ *    method runs on the JS thread but not inside that function, so the guard is null
+ *    and it falls through to `executeSynchronouslyOnSameThread_CAN_DEADLOCK`, which
+ *    schedules onto the JS thread and waits — while being the JS thread.
+ *
+ * 4. `callInvoker->invokeAsync` at construction — REJECTED on ordering. It would be
+ *    safe, but the lambda runs after the current JS turn, and
+ *    `NativeModules.PdfCanvas` is touched and `installJsiTransport()` called within
+ *    one turn. The probe would find nothing and every session would fall back.
+ */
+@interface RCTBridge (PdfCanvasRuntime)
+- (void *)runtime;
+@end
+
+/**
+ * Mirrors `kPdfCanvasMaxPoolSize`, and is the width of the render queue.
+ *
+ * The queue is sized to the ceiling rather than to a document's pool because one
+ * module serves every open document. A render whose document has fewer lanes blocks
+ * on that document's own semaphore, which is where the real limit lives.
+ */
+static const NSInteger kPdfCanvasQueueWidth = 4;
+
+@implementation PdfCanvasModule {
+  /** JS handle -> rasterizer. Read on the queue, written on the bridge thread. */
+  NSMutableDictionary<NSNumber *, PdfCanvasRasterizer *> *_handles;
+  /** (handle, token) -> signal, so a token is only meaningful with its handle. */
+  NSMutableDictionary<NSNumber *, PdfCanvasCancellation *> *_signals;
+  /** Guards both dictionaries. */
+  NSLock *_lock;
+  NSOperationQueue *_renderQueue;
+  NSInteger _nextHandle;
+  /**
+   * Whether renders return a slot instead of a base64 string.
+   *
+   * FALSE UNTIL PROVEN. It is never set by this class deciding the fast path looks
+   * available; it is set by JS after a byte-for-byte round trip of
+   * `PdfCanvasSlotsProbeBytes`. Atomic because it is written on the JS thread (by
+   * `enableJsiTransport`, and by `invalidate`) and read on a render worker.
+   */
+  std::atomic<bool> _jsiEnabled;
+  std::atomic<bool> _invalidated;
+  /**
+   * Set once by `installJSIBindingsWithRuntime:callInvoker:`, which is the only
+   * thing that ever sees a live runtime on the new architecture.
+   *
+   * A flag rather than the pointer: the host function is installed there and then,
+   * so all `installJsiTransport` needs to know is whether that already happened.
+   * Keeping a `jsi::Runtime *` around would be a pointer with no owner and no way to
+   * learn it had been torn down.
+   */
+  BOOL _hostFunctionInstalled;
+}
+
+@synthesize bridge = _bridge;
+
+RCT_EXPORT_MODULE(PdfCanvas)
+
++ (BOOL)requiresMainQueueSetup {
+  // Nothing here touches UIKit at construction. Returning YES would move module
+  // setup to the main thread for no reason and log a warning about it.
+  return NO;
+}
+
+- (instancetype)init {
+  self = [super init];
+  if (self != nil) {
+    _handles = [NSMutableDictionary dictionary];
+    _signals = [NSMutableDictionary dictionary];
+    _lock = [[NSLock alloc] init];
+    _nextHandle = 1;
+    _jsiEnabled = false;
+    _invalidated = false;
+    _renderQueue = [[NSOperationQueue alloc] init];
+    // WIDTH-LIMITED, mirroring Android's `Executors.newFixedThreadPool`. An
+    // unbounded concurrent `dispatch_queue` would spawn a thread per queued render
+    // — and every render beyond a document's pool size does nothing but block on
+    // that pool's semaphore, so those threads would be pure cost.
+    _renderQueue.maxConcurrentOperationCount = kPdfCanvasQueueWidth;
+    _renderQueue.name = @"tools.reekon.pdfcanvas.render";
+    _renderQueue.qualityOfService = NSQualityOfServiceUserInitiated;
+  }
+  return self;
+}
+
+/**
+ * A reload drops the JS side without ever calling `close`, so every open document
+ * would otherwise keep its parsed pages until the process dies. Fast Refresh makes
+ * that happen dozens of times a day.
+ */
+- (void)invalidate {
+  // FIRST, before anything else, so no render that has not yet STARTED can ask for
+  // a slot.
+  //
+  // IT DOES NOT DIVERT A RENDER ALREADY IN FLIGHT, and that is the same bounded
+  // leak Android documents: a worker already inside `CGContextDrawPDFPage` holds a
+  // sink, and it will publish its raster after the `PdfCanvasSlotsReleaseAll`
+  // below has run past. Nothing takes it, and it is freed by the NEXT invalidate.
+  // At most one raster per busy lane, dev-only, reclaimed on the following reload.
+  _jsiEnabled = false;
+  _invalidated = true;
+
+  [_lock lock];
+  NSArray<PdfCanvasRasterizer *> *open = _handles.allValues;
+  [_handles removeAllObjects];
+  [_signals removeAllObjects];
+  [_lock unlock];
+
+  for (PdfCanvasRasterizer *rasterizer in open) {
+    // Non-blocking even with a render in flight — a lease owns a CoreFoundation
+    // reference to its document, so this cannot free one out from under a worker.
+    // See `PdfCanvasDocumentPool`.
+    [rasterizer close];
+  }
+
+  // THE QUEUE IS DELIBERATELY NOT CANCELLED. `cancelAllOperations` looks like the
+  // tidy thing to do and it strands promises: an `NSOperation` cancelled before it
+  // starts never runs its block, so the `resolve`/`reject` pair inside it is never
+  // called, and on the JS side that is an `await` that hangs for the life of the app
+  // rather than an error anyone can see.
+  //
+  // Letting the queued operations run costs nothing and settles every one of them.
+  // Each holds a strong reference to its rasterizer, which the loop above has just
+  // closed, so it fails fast with `backend-failure` — and a render that has already
+  // STARTED was never cancellable anyway, because `CGContextDrawPDFPage` is
+  // uninterruptible once entered. (Android reaches the same conclusion from the other
+  // side: its binding catches `RejectedExecutionException` for tasks submitted after
+  // `shutdownNow`, precisely so those promises settle.)
+
+  // A reload also strands any slot whose promise resolved but whose JS
+  // continuation never ran. Each one is a whole raster — megabytes — held in C++
+  // with nothing left that could ever take it.
+  PdfCanvasSlotsReleaseAll();
+}
+
+/* ---------------------------------------------------------------- *
+ * transport
+ * ---------------------------------------------------------------- */
+
+/**
+ * Installs the JSI host function and parks one probe raster for JS to take.
+ *
+ * SYNCHRONOUS on purpose, and that is load-bearing twice over. MEASURED by reading
+ * RN 0.86.2's own source: `ObjCTurboModule::performMethodInvocation` runs a sync
+ * method through `nativeMethodCallInvoker_->invokeSync`, and
+ * `ModuleNativeMethodCallInvoker::invokeSync` is `work()` — called inline, on the
+ * calling thread, which for a JS-initiated call is the JS thread. That is the only
+ * thread where `bridge.runtime` is a live pointer rather than a value that may
+ * already have been torn down. It also means the whole probe — install, take,
+ * enable — completes before the JS module that called it finishes evaluating, so no
+ * render can race the decision.
+ *
+ * IT RETURNS AN OBJECT, AND MUST. Same measurement: for a non-void, non-promise
+ * return the interop layer does `void *rawResult; [inv getReturnValue:&rawResult];
+ * result = (__bridge id)rawResult;`. A method declared to return `double` or `BOOL`
+ * would have its bits reinterpreted as an object pointer. `RCT_EXPORT_BLOCKING_
+ * SYNCHRONOUS_METHOD` defaults the return type to `id` for exactly this reason;
+ * the `NSNumber` below is that default honoured rather than fought.
+ *
+ * @return the probe slot id, or -1 if the fast path is unavailable. Never throws:
+ *     every failure here is a fallback, not an error.
+ */
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(installJsiTransport) {
+  @try {
+    if (_invalidated) {
+      return @(-1);
+    }
+    // NORMALLY ALREADY DONE. On the new architecture
+    // `installJSIBindingsWithRuntime:callInvoker:` ran at construction, so all this
+    // method has to do is park a probe raster. The branch below is the old
+    // architecture, where that hook is never called and `RCTCxxBridge` genuinely
+    // does answer `-runtime`.
+    if (!_hostFunctionInstalled) {
+      RCTBridge *bridge = self.bridge;
+      void *runtime =
+          [bridge respondsToSelector:@selector(runtime)] ? bridge.runtime : NULL;
+      if (runtime == NULL) {
+        RCTLogWarn(
+            @"[PdfCanvas] No JS runtime was reachable — neither "
+            @"installJSIBindingsWithRuntime: nor bridge.runtime — so every tile "
+            @"will cross the bridge as base64. That is correct but roughly 85x "
+            @"slower per tile. bridge=%@",
+            bridge == nil ? @"nil" : NSStringFromClass([bridge class]));
+        return @(-1);
+      }
+      _hostFunctionInstalled = PdfCanvasSlotsInstall(runtime);
+      if (!_hostFunctionInstalled) {
+        return @(-1);
+      }
+    }
+    return @(PdfCanvasSlotsStoreProbe());
+  } @catch (NSException *exception) {
+    // Includes a `respondsToSelector:` on an `NSProxy` that declines to answer it.
+    // Every failure here is a fallback, not an error.
+    return @(-1);
+  }
+}
+
+/**
+ * Turns the fast transport on, once JS has verified the probe bytes.
+ *
+ * Synchronous for the same reason as `installJsiTransport`: an async call would be
+ * ordered before any render, but "ordered before" is a property of the bridge queue
+ * and this decision is too cheap to make it depend on one.
+ *
+ * @return the flag as it now stands, so the caller reports what is really live
+ *     rather than what it asked for.
+ */
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(enableJsiTransport:(BOOL)enabled) {
+  const bool live = enabled && !_invalidated;
+  _jsiEnabled = live;
+  return @(live);
+}
+
+/* ---------------------------------------------------------------- *
+ * open
+ * ---------------------------------------------------------------- */
+
+RCT_EXPORT_METHOD(open
+                  : (NSDictionary *)source poolSize
+                  : (double)poolSize resolve
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  // DRAINED HERE, on the calling thread, before the queue is handed anything. On
+  // iOS a `NSDictionary` from the bridge is a real Foundation object rather than a
+  // shell over C++ memory — unlike Android's `ReadableNativeMap`, which is only
+  // contractually valid for the duration of the method — so this is defensive
+  // rather than required. It is still the right shape: it keeps the two bindings
+  // reading the same way, and it means a malformed request fails before a worker
+  // has allocated anything.
+  NSString *uri = [source[@"uri"] isKindOfClass:NSString.class] ? source[@"uri"] : nil;
+  NSString *base64 =
+      [source[@"base64"] isKindOfClass:NSString.class] ? source[@"base64"] : nil;
+  NSString *password =
+      [source[@"password"] isKindOfClass:NSString.class] ? source[@"password"] : nil;
+  const NSInteger lanes = [self clampPoolSize:poolSize];
+
+  if (_invalidated) {
+    [self reject:reject code:PdfCanvasErrorCodeBackendFailure
+         message:@"The PdfCanvas module has been invalidated."
+      underlying:nil];
+    return;
+  }
+
+  __weak PdfCanvasModule *weakSelf = self;
+  [_renderQueue addOperationWithBlock:^{
+    PdfCanvasModule *strongSelf = weakSelf;
+    if (strongSelf == nil) {
+      return;
+    }
+    NSError *error = nil;
+    PdfCanvasRasterizer *rasterizer = nil;
+    if (base64 != nil) {
+      NSData *data = [[NSData alloc] initWithBase64EncodedString:base64
+                                                        options:0];
+      if (data == nil) {
+        [strongSelf reject:reject
+                      code:PdfCanvasErrorCodeCorrupt
+                   message:@"The document's base64 payload could not be decoded."
+                underlying:nil];
+        return;
+      }
+      rasterizer = [PdfCanvasRasterizer openData:data
+                                        password:password
+                                        poolSize:lanes
+                                           error:&error];
+    } else {
+      NSURL *url = [strongSelf resolveURI:uri error:&error];
+      if (url != nil) {
+        rasterizer = [PdfCanvasRasterizer openFileURL:url
+                                            password:password
+                                            poolSize:lanes
+                                               error:&error];
+      }
+    }
+    if (rasterizer == nil) {
+      [strongSelf rejectWithError:reject error:error];
+      return;
+    }
+
+    // EVERYTHING THAT CAN STILL FAIL HAPPENS BEFORE THE RASTERIZER IS PUBLISHED.
+    // Registering it first and then throwing while building the result would leave
+    // an open document — parsed pages, a mapped file — that JS has no handle for
+    // and could never close. Android's binding carries the same ordering and the
+    // same `published` flag for the same reason.
+    NSMutableArray<NSDictionary *> *pages =
+        [NSMutableArray arrayWithCapacity:(NSUInteger)rasterizer.pageCount];
+    for (NSInteger i = 0; i < rasterizer.pageCount; i++) {
+      PdfCanvasPageGeometry *geometry = [rasterizer pageGeometryAtIndex:i
+                                                                 error:&error];
+      if (geometry == nil) {
+        [rasterizer close];
+        [strongSelf rejectWithError:reject error:error];
+        return;
+      }
+      [pages addObject:@{
+        @"index" : @(geometry.index),
+        // DOUBLES, not ints. A PDF point is not an integer — A4 is 595.276 wide —
+        // and Android reports ints only because `PdfRenderer` gives it ints.
+        // `PageGeometry.width` in `src/types.ts` is a `number`, so nothing has to
+        // change on the JS side to carry the extra precision.
+        @"width" : @(geometry.widthPoints),
+        @"height" : @(geometry.heightPoints),
+        @"rotation" : @(geometry.rotationDegrees),
+      }];
+    }
+
+    NSNumber *handle = nil;
+    [strongSelf->_lock lock];
+    if (strongSelf->_invalidated) {
+      [strongSelf->_lock unlock];
+      [rasterizer close];
+      [strongSelf reject:reject
+                    code:PdfCanvasErrorCodeBackendFailure
+                 message:@"The PdfCanvas module was invalidated while opening."
+              underlying:nil];
+      return;
+    }
+    handle = @(strongSelf->_nextHandle++);
+    strongSelf->_handles[handle] = rasterizer;
+    [strongSelf->_lock unlock];
+
+    resolve(@{
+      @"handle" : handle,
+      @"pageCount" : @(rasterizer.pageCount),
+      @"pages" : pages,
+      // A CONSTANT on this platform, and part of the shared wire format rather
+      // than an Android extension: a host should not have to know which platform
+      // it is on to ask whether a `/Rotate` page will draw upright.
+      @"rotationSupport" : PdfCanvasRasterizer.rotationSupport,
+    });
+  }];
+}
+
+/**
+ * Accepts a plain path or a `file://` URL.
+ *
+ * NO `content://` EQUIVALENT TO HANDLE, which is the one place this is simpler than
+ * Android: there, a document-provider URI has no path the process can open and has
+ * to be copied into the cache first, because `PdfRenderer` needs a seekable
+ * descriptor and a provider may hand back a pipe. On iOS a picked document arrives
+ * as a `file://` URL that is either already in the app's container (the usual case,
+ * when the host asked for a copy) or security-scoped — and a security-scoped URL is
+ * the HOST's to keep open, which `PdfCanvasPreflight` says in its unreadable-file
+ * message rather than guessing at here.
+ */
+- (nullable NSURL *)resolveURI:(nullable NSString *)uri
+                         error:(NSError *_Nullable *_Nullable)error {
+  if (uri.length == 0) {
+    PdfCanvasFail(error, PdfCanvasErrorCodeNotFound, @"No document uri was given.",
+                  nil);
+    return nil;
+  }
+  if ([uri hasPrefix:@"file://"]) {
+    NSURL *url = [NSURL URLWithString:uri];
+    if (url == nil || url.path.length == 0) {
+      // A path with characters that need percent-encoding — a space, a `#` — makes
+      // `URLWithString:` return nil. Falling back to treating the whole string as a
+      // path is wrong (it would keep the scheme), so the encoded form is tried.
+      NSString *encoded = [uri
+          stringByAddingPercentEncodingWithAllowedCharacters:
+              NSCharacterSet.URLPathAllowedCharacterSet];
+      url = encoded == nil ? nil : [NSURL URLWithString:encoded];
+    }
+    if (url == nil || url.path.length == 0) {
+      PdfCanvasFail(
+          error, PdfCanvasErrorCodeNotFound,
+          [NSString stringWithFormat:@"Could not parse %@ as a file URL.", uri],
+          nil);
+      return nil;
+    }
+    return [NSURL fileURLWithPath:url.path];
+  }
+  if ([uri containsString:@"://"]) {
+    // Handed on as-is so preflight can produce the "this backend does no
+    // networking" message, which is more useful than a parse failure here.
+    NSURL *url = [NSURL URLWithString:uri];
+    if (url != nil) {
+      return url;
+    }
+  }
+  return [NSURL fileURLWithPath:uri];
+}
+
+/* ---------------------------------------------------------------- *
+ * render
+ * ---------------------------------------------------------------- */
+
+RCT_EXPORT_METHOD(render
+                  : (double)handle request
+                  : (NSDictionary *)request token
+                  : (double)token resolve
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  NSNumber *handleKey = @((NSInteger)handle);
+  [_lock lock];
+  PdfCanvasRasterizer *rasterizer = _handles[handleKey];
+  [_lock unlock];
+  if (rasterizer == nil) {
+    [self reject:reject
+            code:PdfCanvasErrorCodeBackendFailure
+         message:[NSString stringWithFormat:@"No open document for handle %ld.",
+                                            (long)handle]
+      underlying:nil];
+    return;
+  }
+
+  PdfCanvasRasterRequest *req = [[PdfCanvasRasterRequest alloc]
+      initWithPage:[request[@"page"] integerValue]
+              docX:[request[@"x"] doubleValue]
+              docY:[request[@"y"] doubleValue]
+          docWidth:[request[@"width"] doubleValue]
+         docHeight:[request[@"height"] doubleValue]
+             scale:[request[@"scale"] doubleValue]
+       annotations:request[@"annotations"] == nil
+                       ? YES
+                       : [request[@"annotations"] boolValue]
+        background:[@"transparent" isEqual:request[@"background"]]
+                       ? PdfCanvasBackgroundTransparent
+                       : PdfCanvasBackgroundWhite];
+
+  NSNumber *signalKey = [self signalKeyForHandle:(NSInteger)handle
+                                           token:(NSInteger)token];
+  // Registered BEFORE the operation runs, and synchronously on the calling thread.
+  // That ordering is what lets `cancel` be a pure lookup: calls from one JS module
+  // are executed in the order JS made them, and JS cannot cancel a token before
+  // the render that issued it, so by the time any cancel for this key arrives this
+  // entry already exists.
+  PdfCanvasCancellation *signal = [[PdfCanvasCancellation alloc] init];
+  [_lock lock];
+  _signals[signalKey] = signal;
+  [_lock unlock];
+
+  __weak PdfCanvasModule *weakSelf = self;
+  [_renderQueue addOperationWithBlock:^{
+    PdfCanvasModule *strongSelf = weakSelf;
+    if (strongSelf == nil) {
+      return;
+    }
+    PdfCanvasRasterPixels *pixels = nil;
+    BOOL handedOff = NO;
+    @try {
+      // Read ONCE. The flag is atomic and `invalidate` clears it, so reading it
+      // twice could ask for a slot and then decide not to look for one — which is
+      // exactly how a filled slot is stranded.
+      const bool fast = strongSelf->_jsiEnabled;
+      id<PdfCanvasPixelSink> sink =
+          fast ? [[PdfCanvasSlotSink alloc] init] : nil;
+
+      NSError *error = nil;
+      pixels = [rasterizer render:req cancellation:signal sink:sink error:&error];
+      if (pixels == nil) {
+        [strongSelf rejectWithError:reject error:error];
+        return;
+      }
+
+      NSMutableDictionary *result = [NSMutableDictionary dictionaryWithCapacity:5];
+      // ONE of the two, never both — `native-bridge.ts` branches on which key is
+      // present, and sending both would mean paying for the encode this whole path
+      // exists to delete.
+      //
+      // The branch is on WHERE THE PIXELS ARE, not on what was asked for: a sink
+      // may refuse its reservation, and that tile still has to go out.
+      if (pixels.isInNativeSlot) {
+        // A double, because that is what a bridge number is on the way to JS.
+        // Slots are consumed within one render, so the 2^53 exact-integer ceiling
+        // is not reachable in any session that could also survive the file
+        // descriptors.
+        result[@"pixelsSlot"] = @((double)pixels.slot);
+      } else {
+        result[@"base64"] = [pixels.bytes base64EncodedStringWithOptions:0];
+      }
+      result[@"width"] = @(pixels.width);
+      result[@"height"] = @(pixels.height);
+      // Passed through, never recomputed as width*4 on either side of the bridge.
+      // A wrong stride shears the image rather than failing.
+      result[@"rowBytes"] = @(pixels.rowBytes);
+      result[@"format"] = pixels.format;
+      resolve(result);
+      // ONLY NOW. Everything that could fail is behind us and the slot id has
+      // reached JS, so from here the ArrayBuffer's take is what frees it and this
+      // thread must not.
+      handedOff = YES;
+    } @catch (NSException *exception) {
+      [strongSelf reject:reject
+                    code:PdfCanvasErrorCodeBackendFailure
+                 message:[NSString stringWithFormat:@"%@: %@", exception.name,
+                                                    exception.reason]
+              underlying:nil];
+    } @finally {
+      // THE ABANDON PATHS, and each one strands a whole raster of C++ memory
+      // without this:
+      //
+      //   1. Building the result dictionary throws (memory pressure), or
+      //      `resolve` throws, or the promise was already settled.
+      //   2. NOT the render failing after it filled the slot: `pixels` is nil on
+      //      that path, so this cannot release it. The rasterizer owns that one —
+      //      its post-draw cancellation check abandons its own sink before
+      //      returning.
+      //
+      // Also not covered, and the two differ by WHEN the reload lands: a slot id
+      // that reaches JS whose continuation never runs is reclaimed by
+      // `PdfCanvasSlotsReleaseAll` in `invalidate`; a slot published AFTER that —
+      // this worker was already mid-draw when the reload started — waits for the
+      // NEXT one. See the note at `invalidate`.
+      if (pixels != nil && !handedOff) {
+        [pixels releaseSlot];
+      }
+      [strongSelf->_lock lock];
+      [strongSelf->_signals removeObjectForKey:signalKey];
+      [strongSelf->_lock unlock];
+    }
+  }];
+}
+
+/**
+ * Best-effort, and the JS side is told so via `capabilities.interruptibleRender:
+ * false`. This can stop a queued render starting and can discard a finished one; it
+ * cannot interrupt `CGContextDrawPDFPage`.
+ *
+ * A PURE LOOKUP, and deliberately not a speculative insert. "No signal registered"
+ * is far more commonly what a cancel that arrives AFTER its render finished and
+ * cleaned up looks like than a cancel that beat its render across the bridge — and
+ * a superseded raster epoch produces a stream of the former. Planting an entry for
+ * each would grow the dictionary for the life of the module. Android's binding
+ * carries the same fix and the same note.
+ */
+RCT_EXPORT_METHOD(cancel : (double)handle token : (double)token) {
+  NSNumber *key = [self signalKeyForHandle:(NSInteger)handle
+                                     token:(NSInteger)token];
+  [_lock lock];
+  PdfCanvasCancellation *signal = _signals[key];
+  [_lock unlock];
+  [signal cancel];
+}
+
+RCT_EXPORT_METHOD(close : (double)handle) {
+  NSNumber *key = @((NSInteger)handle);
+  [_lock lock];
+  PdfCanvasRasterizer *rasterizer = _handles[key];
+  [_handles removeObjectForKey:key];
+  [_lock unlock];
+  // Non-blocking even with a render in flight. See `PdfCanvasDocumentPool`.
+  [rasterizer close];
+}
+
+/** Exposed for wire parity with Android, where the answer is a device probe. */
+RCT_EXPORT_METHOD(rotationSupport
+                  : (RCTPromiseResolveBlock)resolve reject
+                  : (RCTPromiseRejectBlock)reject) {
+  resolve(PdfCanvasRasterizer.rotationSupport);
+}
+
+/**
+ * Slots currently parked, for a host that wants to see the transport is not
+ * leaking. Diagnostic only — nothing in the package reads it.
+ */
+RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD(pendingRasterSlots) {
+  return @(PdfCanvasSlotsCount());
+}
+
+/*
+ * WHY THERE IS NO `isBackendPoisoned`.
+ *
+ * Android exposes one because a `PdfRenderer` constructor that throws permanently
+ * poisons PDFium for the whole process on API 24, and a host may want to know it
+ * has happened. CoreGraphics has no equivalent behaviour — MEASURED: a `%PDF-`
+ * header over garbage returns NULL and a subsequent open of a good document
+ * succeeds, repeatedly, in the same process (`FailureTests.swift`,
+ * `testHeaderOnlyGarbageIsCorruptAndPoisonsNothing`). A method that always answered
+ * "no" would be a method a host might one day trust to mean something.
+ */
+
+/* ---------------------------------------------------------------- *
+ * helpers
+ * ---------------------------------------------------------------- */
+
+- (NSInteger)clampPoolSize:(double)requested {
+  if (!(requested >= 1)) {
+    return 1;
+  }
+  const NSInteger size = (NSInteger)requested;
+  return size > kPdfCanvasQueueWidth ? kPdfCanvasQueueWidth : size;
+}
+
+- (NSNumber *)signalKeyForHandle:(NSInteger)handle token:(NSInteger)token {
+  return @(((int64_t)handle << 32) | (token & 0xffffffffLL));
+}
+
+/**
+ * The error CODE is the promise's rejection code, verbatim from
+ * `PdfCanvasErrorCodeWire` — which is the TypeScript `PdfErrorCode` union member.
+ * React Native surfaces it as `error.code`, and
+ * `src/rasterizer/native-bridge.ts` reconstructs a `PdfError` from it with no
+ * translation table in between.
+ */
+- (void)reject:(RCTPromiseRejectBlock)reject
+          code:(PdfCanvasErrorCode)code
+       message:(NSString *)message
+    underlying:(nullable NSError *)underlying {
+  reject(PdfCanvasErrorCodeWire(code), message,
+         underlying ?: PdfCanvasMakeError(code, message, nil));
+}
+
+- (void)rejectWithError:(RCTPromiseRejectBlock)reject
+                  error:(nullable NSError *)error {
+  if (error == nil) {
+    [self reject:reject
+            code:PdfCanvasErrorCodeBackendFailure
+         message:@"The rasterizer failed without reporting an error."
+      underlying:nil];
+    return;
+  }
+  reject(PdfCanvasErrorCodeWire(PdfCanvasErrorCodeOf(error)),
+         error.localizedDescription, error);
+}
+
+/* ---------------------------------------------------------------- *
+ * The runtime
+ * ---------------------------------------------------------------- */
+
+/**
+ * Returns the SAME wrapper the interop layer would have built for this module.
+ *
+ * `ObjCInteropTurboModule` is what `RCTTurboModuleManager provideLegacyModule:`
+ * constructs for any `RCT_EXPORT_MODULE` class, and it reads this class's exported
+ * methods off the `__rct_export__` metadata at runtime — so returning it changes
+ * NOTHING about how `open`, `render`, `cancel`, `close` or the two synchronous
+ * methods are marshalled. What it changes is which branch of the manager this module
+ * takes: responding to `getTurboModule:` moves it from `provideLegacyModule:` to
+ * `provideTurboModule:`, and only the latter offers
+ * `installJSIBindingsWithRuntime:callInvoker:`.
+ *
+ * NO CODEGEN, deliberately. A generated spec would mean a `codegenConfig` in
+ * `package.json`, a spec file, and a JS side that reaches the module through
+ * `TurboModuleRegistry` instead of `NativeModules` — and `NativeModules` is what
+ * works on BOTH architectures and what `src/rasterizer/index.native.ts` does for
+ * Android too. Paying for codegen to obtain a hook the interop wrapper can be handed
+ * directly is the wrong trade.
+ */
+- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
+    (const facebook::react::ObjCTurboModule::InitParams &)params {
+  return std::make_shared<facebook::react::ObjCInteropTurboModule>(params);
+}
+
+/**
+ * The one place a live `jsi::Runtime` is handed to this module.
+ *
+ * Called on the JS thread at module construction, before JS can call any method
+ * here — so the host function exists before the first `installJsiTransport()` looks
+ * for it, and no render can race the decision. See the file header for the three
+ * routes that do not work.
+ */
+- (void)installJSIBindingsWithRuntime:(facebook::jsi::Runtime &)runtime
+                          callInvoker:
+                              (const std::shared_ptr<facebook::react::CallInvoker> &)
+                                  callInvoker {
+  _hostFunctionInstalled = PdfCanvasSlotsInstall(&runtime);
+  if (!_hostFunctionInstalled) {
+    RCTLogWarn(
+        @"[PdfCanvas] The JS runtime refused __pdfCanvasTakePixels, so every "
+        @"tile will cross the bridge as base64. That is correct but roughly 85x "
+        @"slower per tile.");
+  }
+}
+
+@end