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

package/dist/rasterizer/native-bridge.d.ts

@@ -1,64 +1,43 @@
 /**
- * The part of a platform backend that is not platform-specific.
+ * The wire format between JS and the `PdfCanvas` native module, and everything
+ * built on it that is not a per-backend fact.
  *
- * TWO NATIVE BACKENDS, ONE WIRE FORMAT. `android.ts` and `ios.ts` are both thin
- * over this file: they choose an `id`, a `RasterizerCapabilities`, an
+ * TWO NATIVE MODULES, ONE WIRE FORMAT, ONE ADAPTER. `native.ts` is thin over
+ * this file: it states the `id`, the `RasterizerCapabilities`, the
  * `AlphaEncoding` and how a `PdfSource` becomes a native source, and everything
  * else — error mapping, page-geometry marshalling, the transport negotiation, the
- * base64 decode, the cancellation wiring, the phase timings — is here and is
- * identical. That is not tidiness: the spec's whole claim for the iOS step is
- * "the seam is a seam and not an Android-shaped hole", and the cheapest way to
- * be held to it is for the second backend to be unable to drift.
- *
- * PURE ON PURPOSE, exactly as `android.ts` was before it was split. 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 a real one.
+ * base64 codec, the cancellation wiring, the phase timings — is here.
  *
  * WHY THE WIRE FORMAT IS SHARED RATHER THAN MERELY SIMILAR. The two native
- * modules are written independently — `android/src/.../rn/PdfCanvasModule.java`
- * and `ios/Sources/PdfCanvasBridge/PdfCanvasModule.mm` — so the one thing that
- * can silently diverge is the shape of the maps they resolve with. Sharing this
- * file makes a divergence a compile error on one side or a failing marshalling
- * test on the other, instead of a wrong image on one platform.
- *
- * `globalThis` is the only ambient thing this file reads, and it is universal —
- * the `__pdfCanvasTakePixels` lookup finds nothing under vitest and the adapter
+ * modules are written in different languages — `PdfCanvasModule.java` and
+ * `PdfCanvasModule.mm` — over the same C++ core, so the one thing that can still
+ * diverge is the shape of the maps they resolve with. One set of TypeScript
+ * types for both makes a divergence a failing marshalling test rather than a
+ * wrong image on one platform.
+ *
+ * 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 a real one. `globalThis` is
+ * the only ambient thing this file reads, and it is universal — the
+ * `__pdfCanvasTakePixels` lookup finds nothing under vitest and the adapter
  * carries on.
  */
 import { PdfError } from '../types.js';
 import type { AlphaEncoding, PageGeometry, PageRasterizer, PdfSource, PixelFormat, RasterizerCapabilities, RasterizerHandle, RasterTransport } from '../types.js';
-/**
- * Whether this DEVICE draws a page carrying `/Rotate` upright.
- *
- * A THREE-STATE ANSWER BECAUSE ANDROID GENUINELY HAS THREE. API 24 reports the
- * rotated DIMENSIONS but draws the content unrotated and clipped, while 31 and
- * 33 are correct, and the verdict is measured on device rather than derived from
- * `Build.VERSION` — see `PdfPlatformQuirks`. iOS answers `'supported'`
- * unconditionally: CoreGraphics applies the transform this backend hands it, and
- * `ios/Sources/PdfCanvasCore/PdfCanvasPageTransform.mm` is where `/Rotate`
- * becomes part of that transform, so there is no device variable to probe.
- *
- * It stays on the shared wire format rather than being an Android extension
- * precisely so a host does not have to know which platform it is on to ask.
- */
-export type NativeRotationSupport = 'supported' | 'unsupported' | 'unknown';
 export interface NativePdfPage {
     index: number;
+    /** Post-rotation, in PDF points. A double: A4 is 595.276 wide. */
     width: number;
     height: number;
     /**
-     * The page's `/Rotate`, in degrees, or 0.
+     * Always 0 from the native core, and informational everywhere.
      *
-     * THE TWO BACKENDS REPORT THIS DIFFERENTLY AND BOTH ARE RIGHT, which is worth
-     * knowing before treating a difference as a bug. `PageGeometry.rotation` is
-     * informational — `width` and `height` are already post-rotation on every
-     * backend, and no consumer applies a further rotation — so:
-     *
-     *  - iOS reports the real `/Rotate` (`CGPDFPageGetRotationAngle`), matching
-     *    the web PDFium backend.
-     *  - Android reports 0, because `PdfRenderer` exposes no way to read `/Rotate`
-     *    below API 35. That is an inability, not a policy.
+     * PDFium pre-applies `/Rotate` to both the size above and the render, so
+     * there is no residual rotation for a caller to apply, and reading the raw
+     * `/Rotate` would need `FPDF_LoadPage` — which parses the content stream, the
+     * one thing `pageGeometry` is forbidden to do. The web backend reports the
+     * real value through an `@embedpdf` extension that has no stock-PDFium
+     * counterpart. No consumer rotates anything on the strength of this field.
      */
     rotation: number;
 }
@@ -66,7 +45,6 @@ export interface NativeOpenResult {
     handle: number;
     pageCount: number;
     pages: NativePdfPage[];
-    rotationSupport: NativeRotationSupport;
 }
 export interface NativeRenderResult {
     /**
@@ -110,9 +88,14 @@ export interface NativeSource {
     password?: string;
 }
 export interface PdfCanvasNativeModule {
-    open(source: NativeSource, poolSize: number): Promise<NativeOpenResult>;
+    open(source: NativeSource): Promise<NativeOpenResult>;
     render(handle: number, request: NativeRenderRequest, token: number): Promise<NativeRenderResult>;
-    /** Best-effort. Cannot interrupt a render already inside the platform engine. */
+    /**
+     * Sets the signal the render polls — including MID-RENDER, through PDFium's
+     * progressive API — so a superseded tile stops within one batch of page
+     * objects. A cancel for a token whose render already finished finds nothing
+     * and does nothing.
+     */
     cancel(handle: number, token: number): void;
     close(handle: number): void;
     /**
@@ -160,21 +143,26 @@ export declare function toPdfError(error: unknown, fallback: string): PdfError;
  */
 export declare function decodeBase64(input: string): Uint8Array;
 /**
- * Mirrors `PdfCanvasPixelBridge.PROBE_BYTES` on the Java side and
- * `kPdfCanvasProbeBytes` in `ios/Sources/PdfCanvasBridge/PdfCanvasSlots.mm`.
+ * The encoder, for the one thing that travels JS -> native as bytes: a document
+ * opened from memory. Hand-rolled for the same reasons as the decoder — no
+ * `Buffer` on RN, and `btoa` wants a string. Standard alphabet, `=` padding, no
+ * line breaks, which is what both native modules' decoders accept.
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/**
+ * Mirrors `slots::probeBytes()` in `native/core/src/slots.cpp` (the one store
+ * both platforms now share) and `PdfCanvasNative.PROBE_BYTES` in Java.
  *
- * The three lists are restated rather than derived, which is the point: they are
- * the only places the transport's byte fidelity is asserted, and if one is edited
+ * The lists are restated rather than derived, which is the point: they are the
+ * only places the transport's byte fidelity is asserted, and if one is edited
  * without the others the probe fails and that platform degrades to base64 rather
  * than shipping a shear.
  *
  * The contents are chosen, not arbitrary. 0x00 and 0xFF pin both ends of the
  * range; 0xFD/0xFE/0xFF are above 0x7F, where Java's SIGNED byte and a
- * JS `Uint8Array` disagree unless every step of the copy is right. (On iOS the
- * sign-extension hazard does not exist — the whole path is `uint8_t` — but the
- * probe's other job does: it proves the runtime will build an ArrayBuffer over
- * external memory at all, which is a claim about a JS engine version and not
- * about a language.)
+ * JS `Uint8Array` disagree unless every step of the copy is right. The probe's
+ * other job is platform-blind: it proves the runtime will build an ArrayBuffer
+ * over external memory at all, which is a claim about a JS engine version.
  */
 export declare const TRANSPORT_PROBE_BYTES: readonly number[];
 /**
@@ -226,36 +214,24 @@ export declare function bytesFromResult(result: NativeRenderResult, transport: N
     payloadChars: number;
     used: RasterTransport;
 };
-/**
- * Surfaced so a host can decide what to do about a device that does not draw
- * rotated pages upright — warn, fall back, or accept it.
- */
-export interface NativeRasterizerHandle extends RasterizerHandle {
-    readonly rotationSupport: NativeRotationSupport;
-}
-export declare function createNativeHandle(native: PdfCanvasNativeModule, opened: NativeOpenResult, transport: NativeTransport, alpha: AlphaEncoding, label: string): NativeRasterizerHandle;
+export declare function createNativeHandle(native: PdfCanvasNativeModule, opened: NativeOpenResult, transport: NativeTransport, alpha: AlphaEncoding, label: string): RasterizerHandle;
 export interface NativeRasterizerSpec {
     /** Surfaced as `PageRasterizer.id`, so a bug report names a backend. */
     id: string;
-    /**
-     * Everything except `maxConcurrentRenders` and `transport`, both of which are
-     * resolved here — the first from the pool size actually asked for, the second
-     * from the negotiation.
-     */
+    /** Everything except `transport`, which is resolved here from the negotiation. */
     capabilities: RasterizerCapabilities;
-    /** What this platform's bitmaps encode. Never defaulted — see `AlphaEncoding`. */
+    /** What the engine's bitmaps encode. Never defaulted — see `AlphaEncoding`. */
     alpha: AlphaEncoding;
-    /** Clamped concurrent renders, already resolved by the caller. */
-    poolSize: number;
     /** Named in the "handle is closed" message. */
     label: string;
     toNativeSource: (source: PdfSource) => NativeSource;
     lookupTakePixels?: () => TakePixels | null;
 }
 /**
- * Wraps a native module in a `PageRasterizer`.
+ * Wraps a native module in a `PageRasterizer`, given the facts only the backend
+ * knows. `native.ts` is the one caller.
  *
  * 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 createNativeRasterizer(native: PdfCanvasNativeModule, spec: NativeRasterizerSpec): PageRasterizer;
+export declare function createRasterizerOverBridge(native: PdfCanvasNativeModule, spec: NativeRasterizerSpec): PageRasterizer;

package/dist/rasterizer/native-bridge.js

@@ -1,29 +1,25 @@
 /**
- * The part of a platform backend that is not platform-specific.
+ * The wire format between JS and the `PdfCanvas` native module, and everything
+ * built on it that is not a per-backend fact.
  *
- * TWO NATIVE BACKENDS, ONE WIRE FORMAT. `android.ts` and `ios.ts` are both thin
- * over this file: they choose an `id`, a `RasterizerCapabilities`, an
+ * TWO NATIVE MODULES, ONE WIRE FORMAT, ONE ADAPTER. `native.ts` is thin over
+ * this file: it states the `id`, the `RasterizerCapabilities`, the
  * `AlphaEncoding` and how a `PdfSource` becomes a native source, and everything
  * else — error mapping, page-geometry marshalling, the transport negotiation, the
- * base64 decode, the cancellation wiring, the phase timings — is here and is
- * identical. That is not tidiness: the spec's whole claim for the iOS step is
- * "the seam is a seam and not an Android-shaped hole", and the cheapest way to
- * be held to it is for the second backend to be unable to drift.
- *
- * PURE ON PURPOSE, exactly as `android.ts` was before it was split. 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 a real one.
+ * base64 codec, the cancellation wiring, the phase timings — is here.
  *
  * WHY THE WIRE FORMAT IS SHARED RATHER THAN MERELY SIMILAR. The two native
- * modules are written independently — `android/src/.../rn/PdfCanvasModule.java`
- * and `ios/Sources/PdfCanvasBridge/PdfCanvasModule.mm` — so the one thing that
- * can silently diverge is the shape of the maps they resolve with. Sharing this
- * file makes a divergence a compile error on one side or a failing marshalling
- * test on the other, instead of a wrong image on one platform.
+ * modules are written in different languages — `PdfCanvasModule.java` and
+ * `PdfCanvasModule.mm` — over the same C++ core, so the one thing that can still
+ * diverge is the shape of the maps they resolve with. One set of TypeScript
+ * types for both makes a divergence a failing marshalling test rather than a
+ * wrong image on one platform.
  *
- * `globalThis` is the only ambient thing this file reads, and it is universal —
- * the `__pdfCanvasTakePixels` lookup finds nothing under vitest and the adapter
+ * 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 a real one. `globalThis` is
+ * the only ambient thing this file reads, and it is universal — the
+ * `__pdfCanvasTakePixels` lookup finds nothing under vitest and the adapter
  * carries on.
  */
 import { monotonicNow } from '../clock.js';
@@ -111,25 +107,43 @@ export function decodeBase64(input) {
     }
     return outIndex === out.length ? out : out.subarray(0, outIndex).slice();
 }
+/**
+ * The encoder, for the one thing that travels JS -> native as bytes: a document
+ * opened from memory. Hand-rolled for the same reasons as the decoder — no
+ * `Buffer` on RN, and `btoa` wants a string. Standard alphabet, `=` padding, no
+ * line breaks, which is what both native modules' decoders accept.
+ */
+export function encodeBase64(bytes) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i] ?? 0;
+        const b1 = bytes[i + 1] ?? 0;
+        const b2 = bytes[i + 2] ?? 0;
+        const remaining = bytes.length - i;
+        out += BASE64_ALPHABET[b0 >> 2];
+        out += BASE64_ALPHABET[((b0 & 3) << 4) | (b1 >> 4)];
+        out += remaining > 1 ? BASE64_ALPHABET[((b1 & 15) << 2) | (b2 >> 6)] : '=';
+        out += remaining > 2 ? BASE64_ALPHABET[b2 & 63] : '=';
+    }
+    return out;
+}
 /* ------------------------------------------------------------------ *
  * Transport negotiation
  * ------------------------------------------------------------------ */
 /**
- * Mirrors `PdfCanvasPixelBridge.PROBE_BYTES` on the Java side and
- * `kPdfCanvasProbeBytes` in `ios/Sources/PdfCanvasBridge/PdfCanvasSlots.mm`.
+ * Mirrors `slots::probeBytes()` in `native/core/src/slots.cpp` (the one store
+ * both platforms now share) and `PdfCanvasNative.PROBE_BYTES` in Java.
  *
- * The three lists are restated rather than derived, which is the point: they are
- * the only places the transport's byte fidelity is asserted, and if one is edited
+ * The lists are restated rather than derived, which is the point: they are the
+ * only places the transport's byte fidelity is asserted, and if one is edited
  * without the others the probe fails and that platform degrades to base64 rather
  * than shipping a shear.
  *
  * The contents are chosen, not arbitrary. 0x00 and 0xFF pin both ends of the
  * range; 0xFD/0xFE/0xFF are above 0x7F, where Java's SIGNED byte and a
- * JS `Uint8Array` disagree unless every step of the copy is right. (On iOS the
- * sign-extension hazard does not exist — the whole path is `uint8_t` — but the
- * probe's other job does: it proves the runtime will build an ArrayBuffer over
- * external memory at all, which is a claim about a JS engine version and not
- * about a language.)
+ * JS `Uint8Array` disagree unless every step of the copy is right. The probe's
+ * other job is platform-blind: it proves the runtime will build an ArrayBuffer
+ * over external memory at all, which is a claim about a JS engine version.
  */
 export const TRANSPORT_PROBE_BYTES = [
     0x00, 0x01, 0x02, 0xfd, 0xfe, 0xff, 0x2a, 0x07,
@@ -279,6 +293,9 @@ export function bytesFromResult(result, transport) {
     }
     throw new PdfError('backend-failure', 'The native module returned neither `base64` nor `pixelsSlot`.');
 }
+/* ------------------------------------------------------------------ *
+ * The handle
+ * ------------------------------------------------------------------ */
 export function createNativeHandle(native, opened, transport, alpha, label) {
     const pages = opened.pages.map(toPageGeometry);
     let closed = false;
@@ -294,7 +311,6 @@ export function createNativeHandle(native, opened, transport, alpha, label) {
     };
     return {
         pageCount: opened.pageCount,
-        rotationSupport: opened.rotationSupport,
         pageGeometry: requirePage,
         async render(request, signal) {
             if (closed) {
@@ -379,12 +395,13 @@ export function createNativeHandle(native, opened, transport, alpha, label) {
     };
 }
 /**
- * Wraps a native module in a `PageRasterizer`.
+ * Wraps a native module in a `PageRasterizer`, given the facts only the backend
+ * knows. `native.ts` is the one caller.
  *
  * The native module is INJECTED rather than imported so this file stays pure.
  * `getDefaultRasterizer()` in `./index.native.ts` supplies the real one.
  */
-export function createNativeRasterizer(native, spec) {
+export function createRasterizerOverBridge(native, spec) {
     // ONCE, here, and not lazily on first render. The probe is two synchronous
     // bridge calls and an eight-byte round trip, so it costs nothing worth
     // deferring — and doing it now is what lets `capabilities.transport` be true
@@ -393,7 +410,6 @@ export function createNativeRasterizer(native, spec) {
     const transport = negotiateTransport(native, spec.lookupTakePixels ?? lookupTakePixels);
     const capabilities = {
         ...spec.capabilities,
-        maxConcurrentRenders: spec.poolSize,
         transport: transport.kind,
     };
     return {
@@ -402,7 +418,7 @@ export function createNativeRasterizer(native, spec) {
         async open(source) {
             let opened;
             try {
-                opened = await native.open(spec.toNativeSource(source), spec.poolSize);
+                opened = await native.open(spec.toNativeSource(source));
             }
             catch (error) {
                 throw toPdfError(error, 'Could not open the document');

package/dist/rasterizer/native.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The TypeScript half of the native backend — ONE adapter for iOS and Android.
+ *
+ * There used to be two (`android.ts`, `ios.ts`), and the split was load-bearing:
+ * the platforms differed in engine (PdfRenderer vs CoreGraphics/PDFKit), in
+ * alpha encoding, in whether `annotations: false` was honoured, in whether a
+ * password was accepted, in what `PageGeometry.rotation` meant, and in how many
+ * render lanes made sense. Every one of those differences is gone. Both native
+ * modules now marshal to the same C++ core (`native/core`) linked against the
+ * same pinned PDFium release the web backend runs, so what this file states —
+ * capabilities, alpha, source handling — is one truth with no platform branch,
+ * and a tile rendered on an iPhone is byte-identical to the same tile on a
+ * Pixel and in a browser.
+ *
+ * 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.
+ *
+ * The native side is proven on a laptop by `native/tests` (the core, against
+ * real PDFium) and by `android/tools/compile-gate.sh` (the JNI seam); the iOS
+ * binding's only proof is a device session, as it always was.
+ */
+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 type NativePlatform = 'ios' | 'android';
+export declare const NATIVE_CAPABILITIES: RasterizerCapabilities;
+export interface NativeRasterizerOptions {
+    /** Named in the `id` and in error messages. Diagnostics only. */
+    platform?: NativePlatform;
+    id?: string;
+    /**
+     * How to find the installed JSI host function. Injected only by tests; the
+     * default reads `globalThis`.
+     */
+    lookupTakePixels?: () => TakePixels | null;
+}
+/**
+ * Wraps the `PdfCanvas` 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 createNativeRasterizer(native: import('./native-bridge.js').PdfCanvasNativeModule, options?: NativeRasterizerOptions): PageRasterizer;

package/dist/rasterizer/native.js

@@ -0,0 +1,123 @@
+/**
+ * The TypeScript half of the native backend — ONE adapter for iOS and Android.
+ *
+ * There used to be two (`android.ts`, `ios.ts`), and the split was load-bearing:
+ * the platforms differed in engine (PdfRenderer vs CoreGraphics/PDFKit), in
+ * alpha encoding, in whether `annotations: false` was honoured, in whether a
+ * password was accepted, in what `PageGeometry.rotation` meant, and in how many
+ * render lanes made sense. Every one of those differences is gone. Both native
+ * modules now marshal to the same C++ core (`native/core`) linked against the
+ * same pinned PDFium release the web backend runs, so what this file states —
+ * capabilities, alpha, source handling — is one truth with no platform branch,
+ * and a tile rendered on an iPhone is byte-identical to the same tile on a
+ * Pixel and in a browser.
+ *
+ * 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.
+ *
+ * The native side is proven on a laptop by `native/tests` (the core, against
+ * real PDFium) and by `android/tools/compile-gate.sh` (the JNI seam); the iOS
+ * binding's only proof is a device session, as it always was.
+ */
+import { createRasterizerOverBridge, encodeBase64 } from './native-bridge.js';
+import { PdfError } from '../types.js';
+export { TRANSPORT_PROBE_BYTES, bytesFromResult, decodeBase64, encodeBase64, lookupTakePixels, negotiateTransport, toPageGeometry, } from './native-bridge.js';
+/**
+ * STRAIGHT (un-premultiplied), and — unlike the two constants this replaces —
+ * a measurement of the engine rather than of a platform bitmap type.
+ *
+ * MEASURED in `native/tests` (`alphaIsStraight`): every partially covered pixel
+ * of an antialiased opaque-white edge over a transparent page reads
+ * `[255, 255, 255, a]`, where premultiplied would be `[a, a, a, a]`. It matches
+ * the web backend for the only good reason two backends can match: they are the
+ * same engine. The retired cores were both `'premultiplied'` — Android because
+ * `Bitmap` is, iOS because `CGBitmapContext` offers nothing else — which is why
+ * `RasterPixels.alpha` is a required field and `ingest.ts` has no default.
+ *
+ * Invisible under `background: 'white'`, where every pixel is opaque; wrong
+ * under `'transparent'`, which is in the contract.
+ */
+const NATIVE_ALPHA = 'straight';
+export const NATIVE_CAPABILITIES = Object.freeze({
+    /**
+     * True in BOTH directions, on both platforms. `annotations: true` passes
+     * `FPDF_ANNOT` and draws form fields through `FPDF_FFLDraw`; `false` draws
+     * the content stream alone. Android could not do the second and iOS did it
+     * through a different engine than its tiles; neither caveat survives.
+     */
+    annotations: true,
+    /**
+     * TRUE, for the first time on a native backend. The core renders through
+     * PDFium's progressive API and polls the cancellation signal between batches
+     * of page objects, so an abort stops a superseded tile mid-draw rather than
+     * merely preventing the next one from starting. `RasterPolicy.
+     * minEpochIntervalMs` was written for engines that could not do this.
+     */
+    interruptibleRender: true,
+    /**
+     * FALSE, AND A DECLARATION ABOUT THE PACKAGE, NOT THE ENGINE. PDFium has
+     * text extraction, search and link enumeration, so all three could be true
+     * the day a surface for them exists. It does not — see the non-goals — and a
+     * capability that says "yes" about an API no consumer can reach is worse
+     * than one that says "no".
+     */
+    text: false,
+    search: false,
+    links: false,
+    /**
+     * ONE. PDFium is not thread-safe — not across documents, not across threads
+     * — so the core serialises every call behind a process-wide lock, and a
+     * second lane would only queue behind the first while holding a promise
+     * open. Neither retired core did better in practice: Android measured every
+     * lane count above one as SLOWER (AOSP's lock convoyed), and iOS defaulted
+     * to one because a second was never measured to help. What replaces
+     * parallelism is cancellation: a stale render gives the lock up within one
+     * progressive batch.
+     */
+    maxConcurrentRenders: 1,
+});
+/**
+ * A `uri` passes straight through. Bytes are ACCEPTED — both native modules
+ * open a memory document — but cross the bridge as base64, which for a
+ * document is a one-off cost proportional to its size (a 20 MB drawing is a
+ * ~27 MB string, marshalled once). Prefer a `uri` where one exists: the
+ * previous adapters refused bytes outright for this reason, and refusing was
+ * the wrong trade once the engine could take them, but the cost is real.
+ */
+function toNativeSource(source) {
+    const password = source.password;
+    const withPassword = (bare) => password === undefined ? bare : { ...bare, password };
+    if ('uri' in source) {
+        return withPassword({ uri: source.uri });
+    }
+    if (source.data.byteLength === 0) {
+        throw new PdfError('corrupt', 'The document is empty (0 bytes).');
+    }
+    return withPassword({ base64: encodeBase64(source.data) });
+}
+/**
+ * Wraps the `PdfCanvas` 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 createNativeRasterizer(native, options = {}) {
+    const platform = options.platform;
+    return createRasterizerOverBridge(native, {
+        // `ios-pdfium` / `android-pdfium`: the engine is what a bug report needs
+        // to name, and it is the same word on both platforms now.
+        id: options.id ?? `${platform ?? 'native'}-pdfium`,
+        capabilities: NATIVE_CAPABILITIES,
+        alpha: NATIVE_ALPHA,
+        label: platform === 'ios'
+            ? 'iOS'
+            : platform === 'android'
+                ? 'Android'
+                : 'Native',
+        toNativeSource,
+        ...(options.lookupTakePixels === undefined
+            ? {}
+            : { lookupTakePixels: options.lookupTakePixels }),
+    });
+}

package/dist/react/usePdfDocument.d.ts

@@ -45,12 +45,12 @@ export interface PdfRenderOptions {
     /** Target width in device pixels; derives `scale` from `docRect.width`. */
     widthPx?: number;
     /**
-     * Draw PDF-embedded annotations into the raster.
+     * Draw PDF-embedded annotations (and form fields) into the raster.
      *
-     * Defaults to TRUE here — a file raster (thumbnail, print, hero) is expected to
-     * look like the document does in any other viewer. The layer path passes false,
-     * because the Skia scene draws the app's own annotations and they would
-     * double-draw. Silently downgraded to false if the backend cannot do it.
+     * Defaults to TRUE — a file raster (thumbnail, print, hero) is expected to
+     * look like the document does in any other viewer, and so are the layer's
+     * tiles (`UsePdfLayerOptions.annotations`, same default). Silently downgraded
+     * to false if the backend cannot do it; every shipped backend can.
      */
     annotations?: boolean;
     /**

package/dist/react/usePdfLayer.d.ts

@@ -79,6 +79,15 @@ export interface UsePdfLayerOptions {
     layout?: PdfPageLayout;
     /** Overrides merged over the default `RasterPolicy`. */
     policy?: Partial<RasterPolicy>;
+    /**
+     * Draw the PDF's own annotations and form fields into the tiles.
+     *
+     * @default true — the page looks as it does in any other viewer. Pass false
+     * only if the host imports the PDF's annotations into its own Skia layer and
+     * would otherwise show each one twice. Changing it REBUILDS the controller
+     * and its raster cache: every cached tile was rendered one way or the other.
+     */
+    annotations?: boolean;
     onDiagnostic?: (diagnostic: PdfDiagnostic) => void;
 }
 export interface PdfLayer {
@@ -91,4 +100,4 @@ export interface PdfLayer {
      */
     controller: PdfController;
 }
-export declare function usePdfLayer({ document, pages: pageSelection, layout, policy, onDiagnostic, }: UsePdfLayerOptions): PdfLayer;
+export declare function usePdfLayer({ document, pages: pageSelection, layout, policy, annotations, onDiagnostic, }: UsePdfLayerOptions): PdfLayer;

package/dist/react/usePdfLayer.js

@@ -181,7 +181,7 @@ export function usePdfLayer({ document,
 // The PUBLIC name stays `pages`; locally it is the SELECTION, and the
 // controller's own `pages` is the per-page geometry. Two very different things
 // one rename apart.
-pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, onDiagnostic, }) {
+pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, annotations = true, onDiagnostic, }) {
     // The diagnostic callback is almost always an inline arrow. Route it through a
     // ref so a fresh identity on every render never counts as a reason to rebuild
     // the controller.
@@ -254,6 +254,7 @@ pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, onDiagnostic, })
             // before the field existed) means 1, which is the sequential behaviour
             // every backend was proven against.
             maxConcurrentRenders: document.capabilities.maxConcurrentRenders,
+            annotations,
             onDiagnostic: emitDiagnostic,
             backendId: document.rasterizerId,
         });
@@ -277,7 +278,14 @@ pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, onDiagnostic, })
     // cost of the teardown is one page's rasters, which is the page you are turning
     // to and would have paid for anyway. See `__tests__/single-page.test.ts`.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-    [document, pageRects, pagesKey, policySignature, emitDiagnostic]);
+    [
+        document,
+        pageRects,
+        pagesKey,
+        policySignature,
+        annotations,
+        emitDiagnostic,
+    ]);
     const instance = layer?.controller ?? null;
     useEffect(() => {
         if (layer === null) {

package/dist/skia/index.native.d.ts

@@ -7,8 +7,12 @@
  *
  * The one thing it adds over the shared barrel is installing the native
  * resolver, so a consumer who imports ONLY this subpath still gets a working
- * `skiaApi()`. The call is a statement using an imported binding, not a bare
- * `import './x.js'` — this package declares `sideEffects: false`, and a bare
- * side-effect import is exactly what that flag licenses a bundler to delete.
+ * `skiaApi()`. The call only survives a bundler because this file is NAMED in
+ * `package.json#sideEffects`: a module that declares no used binding of its
+ * own (this one only re-exports) is otherwise never marked executed by
+ * Rollup, and its top-level statements go with it — a call on an imported
+ * binding is no safer than a bare `import './x.js'`. That is exactly how the
+ * web twin's install was dropped from the production web build once; see
+ * `__tests__/tree-shaking.test.ts`.
  */
 export * from './index.js';

package/dist/skia/index.native.js

@@ -7,9 +7,13 @@
  *
  * The one thing it adds over the shared barrel is installing the native
  * resolver, so a consumer who imports ONLY this subpath still gets a working
- * `skiaApi()`. The call is a statement using an imported binding, not a bare
- * `import './x.js'` — this package declares `sideEffects: false`, and a bare
- * side-effect import is exactly what that flag licenses a bundler to delete.
+ * `skiaApi()`. The call only survives a bundler because this file is NAMED in
+ * `package.json#sideEffects`: a module that declares no used binding of its
+ * own (this one only re-exports) is otherwise never marked executed by
+ * Rollup, and its top-level statements go with it — a call on an imported
+ * binding is no safer than a bare `import './x.js'`. That is exactly how the
+ * web twin's install was dropped from the production web build once; see
+ * `__tests__/tree-shaking.test.ts`.
  */
 import { installNativeSkiaResolver } from './resolve.native.js';
 export * from './index.js';

package/dist/skia/index.web.d.ts

@@ -6,7 +6,9 @@
  * install itself decides nothing: it stores a closure, and
  * `globalThis.CanvasKit` is not read until the first raster.
  *
- * See `index.native.ts` for why this is a statement and not a bare
- * `import './resolve.web.js'`.
+ * This file is named in `package.json#sideEffects`, and must stay there: it
+ * declares no binding of its own, so without the listing Rollup never marks it
+ * executed and the install below is dropped. See `index.native.ts` and
+ * `__tests__/tree-shaking.test.ts`.
  */
 export * from './index.js';