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

package/dist/rasterizer/android.js

@@ -1,126 +0,0 @@
-/**
- * The TypeScript half of the Android backend.
- *
- * THIN, AND IT USED TO BE THE WHOLE THING. Everything that is not
- * Android-specific — error mapping, page-geometry marshalling, the transport
- * negotiation, the base64 decode, the cancellation wiring, the phase timings —
- * moved to `./native-bridge.ts` when the iOS backend landed, because the two
- * platforms speak the identical wire format and the spec's claim for the iOS step
- * is that the seam is a seam. What is left here is the four things that are
- * genuinely Android's: the id, the capabilities, the alpha encoding, and what
- * `PdfSource` it can accept.
- *
- * The names exported from `./native-bridge.ts` are re-exported below under their
- * original `Android*` spellings, so nothing that imported them from here breaks.
- *
- * PURE ON PURPOSE. Nothing here imports `react-native`, which is what lets the
- * whole adapter be tested in vitest against a fake native module.
- * `./index.native.ts` is the only file that resolves the real one, and it does
- * nothing except hand it to `createAndroidRasterizer`.
- *
- * The native side is `android/src/main/java/tools/reekon/pdfcanvas/`, a
- * React-free Android library that is proven on device by
- * `./gradlew connectedDebugAndroidTest`. That split is the reason a bug here is
- * a bug in marshalling and never a bug in rasterizing.
- */
-import { createNativeRasterizer } from './native-bridge.js';
-import { PdfError } from '../types.js';
-export { TRANSPORT_PROBE_BYTES, bytesFromResult, decodeBase64, lookupTakePixels, negotiateTransport, toPageGeometry, } from './native-bridge.js';
-/* ------------------------------------------------------------------ *
- * What is actually Android's
- * ------------------------------------------------------------------ */
-/**
- * A CONSTANT AND NOT PART OF THE WIRE RESULT, unlike `format`.
- *
- * `format` is per-render because the Java side could in principle hand back
- * either byte order; the alpha encoding cannot vary, because it is a property of
- * `Bitmap` itself. `PdfCanvasRasterizer.extract` reads an ARGB_8888 Bitmap, and
- * Android bitmaps are PREMULTIPLIED unless somebody calls
- * `setPremultiplied(false)` — which that code deliberately never does, since
- * un-premultiplying would make a `background: 'transparent'` raster composite
- * wrongly rather than fail visibly. So there is nothing for the native side to
- * report and no reason to widen the wire format to carry it.
- *
- * IT MATCHES iOS AND THAT IS A COINCIDENCE OF MECHANISM, not a shared choice.
- * `CGBitmapContext` has no non-premultiplied 8-bit RGBA configuration at all —
- * Apple's supported-formats table offers premultiplied or alpha-none and nothing
- * between — so `ios.ts` declares the same value for a completely different
- * reason. PDFium and pdf.js, meanwhile, both emit STRAIGHT alpha (measured — see
- * `AlphaEncoding`), which is the whole reason `RasterPixels.alpha` exists rather
- * than a single `AlphaType.Premul` in `ingest.ts`. Do not "align" any of these
- * four values with each other.
- */
-const ANDROID_ALPHA = 'premultiplied';
-const CAPABILITIES = {
-    /**
-     * True in the sense the field means — annotations ARE drawn into the raster.
-     *
-     * What is NOT true, and has no field to say so: they cannot be turned OFF.
-     * `PdfRenderer.Page.render` takes a render mode and no annotation switch, and
-     * PDFium's `FPDF_ANNOT` flag is unreachable through the platform class at
-     * every API level. So `RasterRequest.annotations: false` — which is what the
-     * controller passes for every tile — is recorded and ignored, and an app that
-     * draws its own copy of a PDF-embedded annotation will see it twice on
-     * Android. The fix is a PDFium backend, not a different mode here.
-     *
-     * iOS DOES HONOUR THE FALSE CASE, which is worth knowing when a bug report
-     * says annotations appear twice on one platform only: `ios.ts` picks
-     * `CGContextDrawPDFPage` for `false` and PDFKit for `true`, and the two really
-     * do differ in what they composite.
-     */
-    annotations: true,
-    /**
-     * False, and honestly so. `PdfRenderer.Page.render` is synchronous and
-     * uninterruptible once entered; an abort can only stop the NEXT piece
-     * starting, or discard a finished raster that is no longer wanted.
-     */
-    interruptibleRender: false,
-    text: false,
-    search: false,
-    links: false,
-    // Overwritten per rasterizer with the pool size it was actually opened with —
-    // see `createNativeRasterizer`. The constant carries the conservative value so
-    // a partially-constructed object is never the fast one.
-    maxConcurrentRenders: 1,
-};
-/**
- * Mirrors `PdfRendererPool.MAX_POOL_SIZE` on the Java side, which is where the
- * clamp is actually enforced (`PdfRendererPool.open`). Restating it here is not
- * a second source of truth: it is what makes the DECLARED capability match the
- * pool the native side will really hand out, rather than promising four lanes to
- * a pool that silently opened with four... or with one.
- */
-const MAX_POOL_SIZE = 4;
-const clampPoolSize = (size) => Math.max(1, Math.min(MAX_POOL_SIZE, Math.floor(size) || 1));
-function toNativeSource(source) {
-    const password = source.password;
-    if ('uri' in source) {
-        return password === undefined
-            ? { uri: source.uri }
-            : { uri: source.uri, password };
-    }
-    throw new PdfError('unsupported', 'Passing a document as bytes is not wired through the Android binding yet. ' +
-        'The native side supports it (PdfCanvasRasterizer.openBytes spools to a ' +
-        'file, because PdfRenderer needs a seekable descriptor), but sending the ' +
-        'bytes over the bridge costs a base64 round trip of the whole document. ' +
-        'Pass a `uri` instead.');
-}
-/**
- * Wraps a native module in a `PageRasterizer`.
- *
- * The native module is INJECTED rather than imported so this file stays pure.
- * `getDefaultRasterizer()` in `./index.native.ts` supplies the real one.
- */
-export function createAndroidRasterizer(native, options = {}) {
-    return createNativeRasterizer(native, {
-        id: options.id ?? 'android-pdfrenderer',
-        capabilities: CAPABILITIES,
-        alpha: ANDROID_ALPHA,
-        poolSize: clampPoolSize(options.poolSize ?? 1),
-        label: 'Android',
-        toNativeSource,
-        ...(options.lookupTakePixels === undefined
-            ? {}
-            : { lookupTakePixels: options.lookupTakePixels }),
-    });
-}

package/dist/rasterizer/ios.d.ts

@@ -1,84 +0,0 @@
-/**
- * The TypeScript half of the iOS backend.
- *
- * FOUR THINGS, and nothing else. The wire format, the error mapping, the
- * transport negotiation, the base64 fallback, the cancellation wiring and the
- * phase timings are all in `./native-bridge.ts`, shared byte-for-byte with
- * Android. What is iOS's own is the id, the capabilities, the alpha encoding and
- * which `PdfSource` shapes it accepts — which is the whole point of the seam
- * existing.
- *
- * PURE ON PURPOSE, like `./android.ts`. Nothing here imports `react-native`, so
- * the adapter is testable in vitest against a fake native module.
- * `./index.native.ts` is the only file that resolves the real one.
- *
- * The native side is `ios/Sources/PdfCanvasCore/`, a React-free Objective-C++
- * library that also builds under SwiftPM (`ios/Package.swift`) so its geometry,
- * rotation, stride, alpha and error mapping are provable with `swift test` on a
- * Mac — no device, no app, no simulator. `ios/Sources/PdfCanvasBridge/` is the
- * React binding and the JSI slot store, and joins the build only through the
- * podspec.
- *
- * ------------------------------------------------------------------------
- * TWO ENGINES BEHIND ONE BACKEND, chosen per render by `annotations`.
- * ------------------------------------------------------------------------
- *
- * `annotations: false` — every tile the controller asks for — draws through
- * `CGContextDrawPDFPage`, which composites the page's content stream and NOT its
- * annotation appearance streams. `annotations: true` — `renderPage`'s default,
- * which is the thumbnail and print path — draws through PDFKit's
- * `-[PDFPage drawWithBox:toContext:]`, which composites both.
- *
- * THAT MAKES iOS THE ONLY BACKEND THAT HONOURS `annotations: false`. Android
- * cannot (`PdfRenderer.Page.render` has no annotation switch at any API level)
- * and the PDFium web backend does not pass `FPDF_ANNOT` either. So an app that
- * draws its own copy of a PDF-embedded annotation on the Skia layer sees it once
- * on iOS and twice on Android — a real cross-platform difference, and the right
- * way round.
- */
-import type { TakePixels } from './native-bridge.js';
-import type { PageRasterizer } from '../types.js';
-export interface IosRasterizerOptions {
-    /**
-     * Concurrent renders. Clamped to [1, 4] natively — each slot is one more
-     * `CGPDFDocumentRef` over its own `CGDataProvider`, plus, once an
-     * `annotations: true` render asks for one, its own lazily-opened `PDFDocument`.
-     *
-     * ONE, AND FOR A WEAKER REASON THAN ANDROID'S. Android declares 1 because
-     * lanes above 1 were measured to make things WORSE — AOSP serialises
-     * `PdfRenderer` behind a process-wide PDFium lock that convoys, so four threads
-     * inflate the per-tile PDFium phases by up to 30x. None of that evidence is
-     * about CoreGraphics, and it must not be cited as though it were: the lock
-     * being measured there lives in `android_graphics_pdf_PdfRenderer.cpp`.
-     *
-     * WHAT IS ACTUALLY KNOWN ABOUT iOS. The pool exists so that concurrency is
-     * expressible at all: `CGPDFDocumentRef` is not documented thread-safe, and a
-     * single one shared across lanes would have to be serialised by a lock we own,
-     * which buys nothing. Opening the file once per lane gives each lane an
-     * independent parse — the same argument `PdfRendererPool` makes for not using
-     * `dup(2)`. Whether that then converts into wall-clock is unmeasured, which is
-     * why the default is the conservative 1 rather than the optimistic 2: an
-     * unmeasured speedup that is really a slowdown is exactly the mistake Android's
-     * `poolSize: 2` was, and it survived for months.
-     *
-     * Raising it does two things at once, as on Android: it opens more documents
-     * AND it widens the controller's lane bound, because it is also what the
-     * rasterizer reports as `RasterizerCapabilities.maxConcurrentRenders`. Measure
-     * before raising it, on a real drawing rather than a synthetic fixture — the
-     * Android note explains why that distinction inverted the answer there.
-     */
-    poolSize?: number;
-    id?: string;
-    /**
-     * How to find the installed JSI host function. Injected only by tests; the
-     * default reads `globalThis`.
-     */
-    lookupTakePixels?: () => TakePixels | null;
-}
-/**
- * Wraps a native module in a `PageRasterizer`.
- *
- * The native module is INJECTED rather than imported so this file stays pure.
- * `getDefaultRasterizer()` in `./index.native.ts` supplies the real one.
- */
-export declare function createIosRasterizer(native: import('./native-bridge.js').PdfCanvasNativeModule, options?: IosRasterizerOptions): PageRasterizer;

package/dist/rasterizer/ios.js

@@ -1,155 +0,0 @@
-/**
- * The TypeScript half of the iOS backend.
- *
- * FOUR THINGS, and nothing else. The wire format, the error mapping, the
- * transport negotiation, the base64 fallback, the cancellation wiring and the
- * phase timings are all in `./native-bridge.ts`, shared byte-for-byte with
- * Android. What is iOS's own is the id, the capabilities, the alpha encoding and
- * which `PdfSource` shapes it accepts — which is the whole point of the seam
- * existing.
- *
- * PURE ON PURPOSE, like `./android.ts`. Nothing here imports `react-native`, so
- * the adapter is testable in vitest against a fake native module.
- * `./index.native.ts` is the only file that resolves the real one.
- *
- * The native side is `ios/Sources/PdfCanvasCore/`, a React-free Objective-C++
- * library that also builds under SwiftPM (`ios/Package.swift`) so its geometry,
- * rotation, stride, alpha and error mapping are provable with `swift test` on a
- * Mac — no device, no app, no simulator. `ios/Sources/PdfCanvasBridge/` is the
- * React binding and the JSI slot store, and joins the build only through the
- * podspec.
- *
- * ------------------------------------------------------------------------
- * TWO ENGINES BEHIND ONE BACKEND, chosen per render by `annotations`.
- * ------------------------------------------------------------------------
- *
- * `annotations: false` — every tile the controller asks for — draws through
- * `CGContextDrawPDFPage`, which composites the page's content stream and NOT its
- * annotation appearance streams. `annotations: true` — `renderPage`'s default,
- * which is the thumbnail and print path — draws through PDFKit's
- * `-[PDFPage drawWithBox:toContext:]`, which composites both.
- *
- * THAT MAKES iOS THE ONLY BACKEND THAT HONOURS `annotations: false`. Android
- * cannot (`PdfRenderer.Page.render` has no annotation switch at any API level)
- * and the PDFium web backend does not pass `FPDF_ANNOT` either. So an app that
- * draws its own copy of a PDF-embedded annotation on the Skia layer sees it once
- * on iOS and twice on Android — a real cross-platform difference, and the right
- * way round.
- */
-import { createNativeRasterizer } from './native-bridge.js';
-import { PdfError } from '../types.js';
-/**
- * A CONSTANT AND NOT PART OF THE WIRE RESULT, unlike `format`, and — unusually
- * for this package — a fact about an API rather than a measurement.
- *
- * There is no non-premultiplied 8-bit RGBA `CGBitmapContext`. Apple's supported
- * pixel formats for a 32-bit-per-pixel, 8-bits-per-component RGB bitmap context
- * are `kCGImageAlphaPremultipliedFirst`, `kCGImageAlphaPremultipliedLast`,
- * `kCGImageAlphaNoneSkipFirst` and `kCGImageAlphaNoneSkipLast` — premultiplied,
- * or no alpha at all. `kCGImageAlphaLast` (straight) is not in the table and
- * `CGBitmapContextCreate` returns NULL for it. So the only two choices a backend
- * has here are "premultiplied" and "throw away the alpha channel", and throwing
- * it away would break `background: 'transparent'`.
- *
- * `ios/Sources/PdfCanvasCore/PdfCanvasRasterizer.mm` creates exactly one context
- * configuration and this constant states it. The `alphaIsPremultiplied` case in
- * the Swift suite reads the bytes back and checks the encoding on an antialiased
- * edge over a transparent page — the one cell the spec's alpha table had marked
- * NOT MEASURED — so this is asserted rather than believed.
- *
- * IT AGREES WITH ANDROID BY COINCIDENCE OF MECHANISM. Android's value comes from
- * `Bitmap` being premultiplied by default; this one comes from CoreGraphics
- * having no other option. PDFium and pdf.js both emit STRAIGHT alpha. Four
- * backends, three independent reasons, no default that would be right — which is
- * why `RasterPixels.alpha` is a required field.
- */
-const IOS_ALPHA = 'premultiplied';
-const CAPABILITIES = {
-    /**
-     * True, and — alone among the four backends — true in BOTH directions.
-     *
-     * `annotations: true` draws them (PDFKit) and `annotations: false` does not
-     * (`CGContextDrawPDFPage`). Android records the flag and ignores it; the web
-     * PDFium backend does not pass `FPDF_ANNOT`. The field only claims "can render
-     * PDF-embedded annotations into the raster", so all three answer true — the
-     * asymmetry is documented at the top of this file rather than inventable from
-     * the capability.
-     */
-    annotations: true,
-    /**
-     * False, and honestly so. `CGContextDrawPDFPage` and
-     * `-[PDFPage drawWithBox:toContext:]` are both synchronous and uninterruptible
-     * once entered; an abort can only stop the NEXT piece starting, or discard a
-     * finished raster that is no longer wanted. This is the platform
-     * `RasterPolicy.minEpochIntervalMs` was written for — PDFKit is named in its
-     * doc comment.
-     */
-    interruptibleRender: false,
-    /**
-     * FALSE, AND THIS ONE IS A DECLARATION ABOUT THE PACKAGE, NOT THE PLATFORM.
-     * PDFKit really does have `-[PDFPage string]`, `-[PDFDocument findString:]` and
-     * link annotations, so iOS could answer true for all three the day a text
-     * surface exists. It does not exist — see the Non-goals — and a capability that
-     * says "yes" about an API no consumer can reach is worse than one that says
-     * "no". Every backend declares false today for the same reason.
-     */
-    text: false,
-    search: false,
-    links: false,
-    // Overwritten per rasterizer with the pool size it was actually opened with —
-    // see `createNativeRasterizer`.
-    maxConcurrentRenders: 1,
-};
-/**
- * Mirrors `kPdfCanvasMaxPoolSize` in
- * `ios/Sources/PdfCanvasCore/PdfCanvasDocumentPool.mm`, which is where the clamp
- * is actually enforced. Restating it here is what makes the DECLARED capability
- * match the pool the native side will really hand out.
- */
-const MAX_POOL_SIZE = 4;
-const clampPoolSize = (size) => Math.max(1, Math.min(MAX_POOL_SIZE, Math.floor(size) || 1));
-function toNativeSource(source) {
-    const password = source.password;
-    if ('uri' in source) {
-        return password === undefined
-            ? { uri: source.uri }
-            : { uri: source.uri, password };
-    }
-    // REFUSED FOR THE SAME REASON AS ANDROID, and it is the bridge's reason rather
-    // than the platform's. iOS could take bytes with no spool at all —
-    // `CGPDFDocumentCreateWithProvider` over a `CFData` needs no file, and the
-    // native `open` does implement the `base64` field of the shared wire format for
-    // exactly that — but getting the bytes THERE means base64-encoding the whole
-    // document across the bridge, which is the one thing the spec's "two rules that
-    // are now measured" says never to do.
-    throw new PdfError('unsupported', 'Passing a document as bytes is not wired through the iOS binding. The ' +
-        'native side supports it (no spool file is needed — CoreGraphics reads a ' +
-        'CGDataProvider over the bytes directly), but sending them over the ' +
-        'bridge costs a base64 round trip of the whole document. Pass a `uri` ' +
-        'instead: a plain path, a `file://` URL, or a security-scoped URL the app ' +
-        'can still read.');
-}
-/**
- * Wraps a native module in a `PageRasterizer`.
- *
- * The native module is INJECTED rather than imported so this file stays pure.
- * `getDefaultRasterizer()` in `./index.native.ts` supplies the real one.
- */
-export function createIosRasterizer(native, options = {}) {
-    return createNativeRasterizer(native, {
-        // NOT `ios-pdfkit`, though the README's plan said PDFKit and an earlier draft
-        // of this file used that id. Half the renders never touch PDFKit — every tile
-        // goes through `CGContextDrawPDFPage` — and an id is what a bug report
-        // quotes, so naming the framework that handles the minority of renders would
-        // misdirect every investigation of a tile.
-        id: options.id ?? 'ios-coregraphics',
-        capabilities: CAPABILITIES,
-        alpha: IOS_ALPHA,
-        poolSize: clampPoolSize(options.poolSize ?? 1),
-        label: 'iOS',
-        toNativeSource,
-        ...(options.lookupTakePixels === undefined
-            ? {}
-            : { lookupTakePixels: options.lookupTakePixels }),
-    });
-}

package/ios/Package.swift

@@ -1,58 +0,0 @@
-// swift-tools-version:5.9
-//
-// A SECOND BUILD SYSTEM FOR THE SAME SOURCES, and it earns its keep.
-//
-// `PdfCanvasCore` is the React-free iOS rasterizer. The podspec at the repository
-// root compiles it into a host app; this manifest compiles the identical files
-// for macOS so that `swift test` proves them on a laptop — no device, no
-// simulator, no app, no CocoaPods. That is the same arrangement Android has, where
-// `android/src/main` is a React-free library provable by
-// `./gradlew connectedDebugAndroidTest`, and it exists for the same reason: a bug
-// in the React binding must never be able to hide as a bug in rasterizing.
-//
-// It also enforces a rule that would otherwise be a comment. CoreGraphics and
-// PDFKit exist on macOS; UIKit does not. So a UIKit import anywhere in
-// `PdfCanvasCore` breaks this build immediately, which is exactly when it should
-// break — rather than at the point somebody tries to reuse the core somewhere it
-// cannot go.
-//
-// WHAT IS DELIBERATELY NOT HERE: `PdfCanvasBridge`. It imports `<jsi/jsi.h>` and
-// `<React/RCTBridgeModule.h>`, which come from a pod and cannot be resolved by
-// SwiftPM. Its only build is the podspec's, and its only proof is a device
-// session — which is precisely the split the Android README describes and the
-// reason both platforms name what is unproven.
-//
-// The test target is SWIFT, not Objective-C, which forces the core's public
-// headers to stay importable from Swift: no C++ in a header, no `void *` where a
-// typed pointer belongs, nothing that only an Objective-C++ translation unit can
-// parse. That constraint is worth having on a library whose one C++ file lives on
-// the other side of a protocol.
-
-import PackageDescription
-
-let package = Package(
-  name: "PdfCanvasCore",
-  platforms: [.macOS(.v11), .iOS(.v13)],
-  products: [
-    .library(name: "PdfCanvasCore", targets: ["PdfCanvasCore", "PdfCanvasSlots"])
-  ],
-  targets: [
-    .target(
-      name: "PdfCanvasCore",
-      path: "Sources/PdfCanvasCore",
-      publicHeadersPath: "include"
-    ),
-    .target(
-      name: "PdfCanvasSlots",
-      dependencies: ["PdfCanvasCore"],
-      path: "Sources/PdfCanvasSlots",
-      publicHeadersPath: "include"
-    ),
-    .testTarget(
-      name: "PdfCanvasCoreTests",
-      dependencies: ["PdfCanvasCore", "PdfCanvasSlots"],
-      path: "Tests/PdfCanvasCoreTests"
-    ),
-  ],
-  cxxLanguageStandard: .cxx17
-)

package/ios/Sources/PdfCanvasCore/PdfCanvasCancellation.m

@@ -1,38 +0,0 @@
-#import "PdfCanvasCancellation.h"
-
-#import <stdatomic.h>
-
-@implementation PdfCanvasCancellation {
-  _Atomic(bool) _cancelled;
-}
-
-- (instancetype)init {
-  self = [super init];
-  if (self != nil) {
-    atomic_init(&_cancelled, false);
-  }
-  return self;
-}
-
-- (void)cancel {
-  atomic_store_explicit(&_cancelled, true, memory_order_relaxed);
-}
-
-- (BOOL)isCancelled {
-  return atomic_load_explicit(&_cancelled, memory_order_relaxed) ? YES : NO;
-}
-
-@end
-
-BOOL PdfCanvasCheckCancelled(
-    PdfCanvasCancellation *_Nullable signal,
-    NSString *stage,
-    NSError *_Nullable *_Nullable error) {
-  if (signal == nil || !signal.isCancelled) {
-    return YES;
-  }
-  PdfCanvasFail(
-      error, PdfCanvasErrorCodeCancelled,
-      [NSString stringWithFormat:@"Render cancelled (%@).", stage], nil);
-  return NO;
-}