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

package/dist/rasterizer/native-bridge.js

@@ -0,0 +1,413 @@
+/**
+ * The part of a platform backend that is not platform-specific.
+ *
+ * TWO NATIVE BACKENDS, ONE WIRE FORMAT. `android.ts` and `ios.ts` are both thin
+ * over this file: they choose an `id`, a `RasterizerCapabilities`, an
+ * `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.
+ *
+ * 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
+ * carries on.
+ */
+import { monotonicNow } from '../clock.js';
+import { isTightBuffer } from './buffer.js';
+import { PdfError } from '../types.js';
+/* ------------------------------------------------------------------ *
+ * Errors
+ * ------------------------------------------------------------------ */
+const ERROR_CODES = [
+    'not-found',
+    'password-required',
+    'password-incorrect',
+    'corrupt',
+    'unsupported',
+    'cancelled',
+    'out-of-memory',
+    'backend-failure',
+];
+/**
+ * React Native's `promise.reject(code, message)` surfaces `code` as a string
+ * property on the rejection, which is why `PdfErrorCode`'s members are the wire
+ * format on the native side too (`PdfErrorCode.wire()` in Java,
+ * `PdfCanvasErrorCodeWire()` in Objective-C). No translation table exists in
+ * between, deliberately: a table is a place for the lists to silently drift
+ * apart.
+ */
+export function toPdfError(error, fallback) {
+    if (error instanceof PdfError)
+        return error;
+    const code = error?.code;
+    const message = error?.message ?? String(error);
+    if (typeof code === 'string' && ERROR_CODES.includes(code)) {
+        return new PdfError(code, String(message), { cause: error });
+    }
+    return new PdfError('backend-failure', `${fallback}: ${message}`, {
+        cause: error,
+    });
+}
+/* ------------------------------------------------------------------ *
+ * base64
+ * ------------------------------------------------------------------ */
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+const BASE64_LOOKUP = /*#__PURE__*/ (() => {
+    const table = new Uint8Array(128).fill(255);
+    for (let i = 0; i < BASE64_ALPHABET.length; i++) {
+        table[BASE64_ALPHABET.charCodeAt(i)] = i;
+    }
+    return table;
+})();
+/**
+ * Hand-rolled rather than `atob` or `Buffer`.
+ *
+ * `Buffer` is a node global that RN does not ship, and `atob` — added to Hermes
+ * relatively recently — decodes to a STRING, so recovering bytes means a second
+ * pass building a Uint8Array from char codes, doubling the peak footprint of a
+ * buffer that is already megabytes. This writes straight into the output array,
+ * and being pure means the padded-stride and odd-length cases are covered in
+ * vitest instead of on a device.
+ */
+export function decodeBase64(input) {
+    let end = input.length;
+    while (end > 0 && input.charCodeAt(end - 1) === 61 /* '=' */)
+        end--;
+    const out = new Uint8Array(Math.floor((end * 3) / 4));
+    let outIndex = 0;
+    let accumulator = 0;
+    let bits = 0;
+    for (let i = 0; i < end; i++) {
+        const code = input.charCodeAt(i);
+        const value = code < 128 ? BASE64_LOOKUP[code] : undefined;
+        if (value === undefined || value === 255) {
+            // Whitespace is legal in a base64 payload and is the one thing worth
+            // tolerating; anything else means the transport corrupted the raster, and
+            // a sheared image is a far worse outcome than a named failure.
+            if (code === 10 || code === 13 || code === 32 || code === 9)
+                continue;
+            throw new PdfError('backend-failure', `Raster payload is not valid base64 at index ${i}.`);
+        }
+        accumulator = (accumulator << 6) | value;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[outIndex++] = (accumulator >> bits) & 0xff;
+        }
+    }
+    return outIndex === out.length ? out : out.subarray(0, outIndex).slice();
+}
+/* ------------------------------------------------------------------ *
+ * Transport negotiation
+ * ------------------------------------------------------------------ */
+/**
+ * Mirrors `PdfCanvasPixelBridge.PROBE_BYTES` on the Java side and
+ * `kPdfCanvasProbeBytes` in `ios/Sources/PdfCanvasBridge/PdfCanvasSlots.mm`.
+ *
+ * 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
+ * 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.)
+ */
+export const TRANSPORT_PROBE_BYTES = [
+    0x00, 0x01, 0x02, 0xfd, 0xfe, 0xff, 0x2a, 0x07,
+];
+/**
+ * Reads the installed host function off the global.
+ *
+ * Through `globalThis`, which is universal — unlike `react-native`, whose import
+ * is what this whole file is written to avoid. So the pure core still loads
+ * under vitest and in a browser: the lookup simply finds nothing.
+ */
+export const lookupTakePixels = () => {
+    const found = globalThis
+        .__pdfCanvasTakePixels;
+    return typeof found === 'function' ? found : null;
+};
+const BASE64_TRANSPORT = { kind: 'base64', take: null };
+/**
+ * Decides ONCE, at construction, which transport this rasterizer uses — and
+ * proves the fast one before choosing it.
+ *
+ * THE PROBE IS THE POINT. Every step below can fail on a real device for a
+ * reason no type system sees: the app binary may predate the native transport
+ * (no `installJsiTransport`), the build may lack the native library for this ABI
+ * or slice (install returns -1), the runtime may refuse a host function, or the
+ * JS engine may not support an ArrayBuffer backed by external memory at all —
+ * Hermes does, but "does" is a claim about a version. So instead of inferring
+ * availability from any of those, the negotiation moves eight known bytes across
+ * the real transport and compares them. Only a byte-for-byte match arms it.
+ *
+ * Every failure returns `base64`, and none of them throws. A build that cannot
+ * do this fast renders exactly as it did before.
+ */
+export function negotiateTransport(native, lookup = lookupTakePixels) {
+    const install = native.installJsiTransport;
+    const enable = native.enableJsiTransport;
+    if (typeof install !== 'function' || typeof enable !== 'function') {
+        return BASE64_TRANSPORT;
+    }
+    try {
+        const slot = install.call(native);
+        if (typeof slot !== 'number' || !Number.isFinite(slot) || slot < 0) {
+            return BASE64_TRANSPORT;
+        }
+        const take = lookup();
+        if (take === null) {
+            // Installed on the native side but not visible on the global: the runtime
+            // this module is evaluating in is not the one that was installed into. The
+            // probe slot is reclaimed on the next reload.
+            //
+            // DISARMED, not merely declined. The enable flag lives on the native
+            // MODULE, shared by every rasterizer in the process, so another runtime
+            // that negotiated successfully may already have turned it on — and then
+            // every render this rasterizer makes comes back as a slot it has no way to
+            // redeem, which is a rasterizer that cannot draw at all rather than a slow
+            // one. Turning the flag off costs the other runtime its speed and costs
+            // this one nothing but a base64 decode.
+            enable.call(native, false);
+            return BASE64_TRANSPORT;
+        }
+        const probe = new Uint8Array(take(slot));
+        if (probe.length !== TRANSPORT_PROBE_BYTES.length ||
+            TRANSPORT_PROBE_BYTES.some((byte, index) => probe[index] !== byte)) {
+            enable.call(native, false);
+            return BASE64_TRANSPORT;
+        }
+        return enable.call(native, true)
+            ? { kind: 'jsi-arraybuffer', take }
+            : BASE64_TRANSPORT;
+    }
+    catch {
+        // Includes the interesting case: a runtime that installs the host function
+        // happily and then throws inside `createArrayBuffer`. That failure is only
+        // observable by trying, which is what the probe is.
+        try {
+            enable.call(native, false);
+        }
+        catch {
+            // Disarming a transport that never armed. Nothing to report.
+        }
+        return BASE64_TRANSPORT;
+    }
+}
+/* ------------------------------------------------------------------ *
+ * Geometry
+ * ------------------------------------------------------------------ */
+const ROTATIONS = [0, 90, 180, 270];
+export function toPageGeometry(page) {
+    const rotation = ROTATIONS.includes(page.rotation)
+        ? page.rotation
+        : 0;
+    return {
+        index: page.index,
+        width: page.width,
+        height: page.height,
+        rotation,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Bytes
+ * ------------------------------------------------------------------ */
+/**
+ * Turns one native render result into bytes, on whichever transport produced it.
+ *
+ * Branches on the RESULT rather than on the negotiated transport, because the
+ * two can disagree for exactly one render: a native side clears its own flag
+ * when a slot store fails and falls that tile back to base64 mid-flight. What
+ * arrived is the only thing that can be believed.
+ */
+export function bytesFromResult(result, transport) {
+    if (result.pixelsSlot !== undefined) {
+        if (transport.take === null) {
+            throw new PdfError('backend-failure', 'The native module returned a JSI pixel slot, but no ' +
+                '__pdfCanvasTakePixels is installed in this runtime.');
+        }
+        // No copy. The ArrayBuffer wraps the native buffer the render worker
+        // filled, and it is exactly the raster and nothing more — so `isTightBuffer`
+        // holds by construction and `tighten()` in ingest.ts has nothing to do.
+        //
+        // WRAPPED, because the take can fail for a reason that is not a bug here: a
+        // slot is drained on teardown (a reload, or a second React instance tearing
+        // down), and the host function reports that by THROWING — which is right,
+        // since an empty ArrayBuffer would reach Skia and draw a black tile. What
+        // arrives is a bare `Error` from C++, and every other failure at this seam is
+        // a `PdfError` with a code the controller can act on (`decodeBase64`
+        // included). Mapping it keeps that one contract true of both transports.
+        let buffer;
+        try {
+            buffer = transport.take(result.pixelsSlot);
+        }
+        catch (error) {
+            throw new PdfError('backend-failure', `Could not redeem raster slot ${result.pixelsSlot}: ` +
+                `${error?.message ?? String(error)}`, { cause: error });
+        }
+        return {
+            bytes: new Uint8Array(buffer),
+            payloadChars: 0,
+            used: 'jsi-arraybuffer',
+        };
+    }
+    if (result.base64 !== undefined) {
+        return {
+            bytes: decodeBase64(result.base64),
+            payloadChars: result.base64.length,
+            used: 'base64',
+        };
+    }
+    throw new PdfError('backend-failure', 'The native module returned neither `base64` nor `pixelsSlot`.');
+}
+export function createNativeHandle(native, opened, transport, alpha, label) {
+    const pages = opened.pages.map(toPageGeometry);
+    let closed = false;
+    // Monotonic per handle. The native side keys its cancellation signals on
+    // (handle, token), so a token is only ever meaningful alongside its handle.
+    let nextToken = 1;
+    const requirePage = (index) => {
+        const geometry = pages[index];
+        if (geometry === undefined) {
+            throw new PdfError('not-found', `Document has ${pages.length} pages; asked for ${index}.`);
+        }
+        return geometry;
+    };
+    return {
+        pageCount: opened.pageCount,
+        rotationSupport: opened.rotationSupport,
+        pageGeometry: requirePage,
+        async render(request, signal) {
+            if (closed) {
+                throw new PdfError('backend-failure', `${label} rasterizer handle is closed.`);
+            }
+            requirePage(request.page);
+            if (signal?.aborted) {
+                throw new PdfError('cancelled', 'Render was aborted before it started.');
+            }
+            const token = nextToken++;
+            // Registered before the call so an abort that lands during the bridge hop
+            // still reaches the native signal. Removed in the finally, so a document
+            // that renders for hours does not accumulate listeners.
+            const onAbort = () => native.cancel(opened.handle, token);
+            signal?.addEventListener('abort', onAbort, { once: true });
+            // INSTRUMENTATION. Two clock reads and one subtraction per tile, on a path
+            // whose cheapest term is already milliseconds — the measurement cost is
+            // noise. It is unconditional on purpose: a timing seam that has to be
+            // switched on is a timing seam nobody has running when the interesting
+            // frame happens.
+            const startedAt = monotonicNow();
+            let result;
+            try {
+                result = await native.render(opened.handle, {
+                    page: request.page,
+                    x: request.docRect.x,
+                    y: request.docRect.y,
+                    width: request.docRect.width,
+                    height: request.docRect.height,
+                    scale: request.scale,
+                    annotations: request.annotations,
+                    background: request.background,
+                }, token);
+            }
+            catch (error) {
+                throw toPdfError(error, `Could not render page ${request.page}`);
+            }
+            finally {
+                signal?.removeEventListener('abort', onAbort);
+            }
+            const bridgeEndedAt = monotonicNow();
+            // On the fast transport this is a slot redemption and an ArrayBuffer view
+            // — the same seam that used to hold a 5.6 M-iteration base64 loop, kept in
+            // place so the two are measured by the identical clock reads.
+            const decoded = bytesFromResult(result, transport);
+            const decodeEndedAt = monotonicNow();
+            return {
+                bytes: decoded.bytes,
+                width: result.width,
+                height: result.height,
+                // Taken from the native result, never recomputed as width * 4. Every
+                // device measured so far shows a tight stride at every width tested,
+                // including odd and prime ones — but "measured tight today" is not
+                // "guaranteed tight", and a wrong stride shears the image instead of
+                // failing.
+                rowBytes: result.rowBytes,
+                format: result.format,
+                alpha,
+                timings: {
+                    bridgeMs: bridgeEndedAt - startedAt,
+                    decodeMs: decodeEndedAt - bridgeEndedAt,
+                    // Zero on the fast transport, and that zero is the headline: there is
+                    // no payload to count because nothing was stringified.
+                    payloadChars: decoded.payloadChars,
+                    // Measured, not asserted, on BOTH transports. `decodeBase64` allocates
+                    // its own exact buffer and a redeemed ArrayBuffer is exactly the
+                    // raster, so this is expected to be TRUE either way — which is the
+                    // useful thing to have on record: `tighten()`'s copy was never part of
+                    // the cost being attacked, and the new transport neither gains nor
+                    // loses there.
+                    tight: isTightBuffer(decoded.bytes),
+                    transport: decoded.used,
+                },
+            };
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            native.close(opened.handle);
+        },
+    };
+}
+/**
+ * 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 createNativeRasterizer(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
+    // the moment the object exists, rather than becoming true later behind a host
+    // that has already read it.
+    const transport = negotiateTransport(native, spec.lookupTakePixels ?? lookupTakePixels);
+    const capabilities = {
+        ...spec.capabilities,
+        maxConcurrentRenders: spec.poolSize,
+        transport: transport.kind,
+    };
+    return {
+        id: spec.id,
+        capabilities,
+        async open(source) {
+            let opened;
+            try {
+                opened = await native.open(spec.toNativeSource(source), spec.poolSize);
+            }
+            catch (error) {
+                throw toPdfError(error, 'Could not open the document');
+            }
+            return createNativeHandle(native, opened, transport, spec.alpha, spec.label);
+        },
+    };
+}

package/dist/rasterizer/web/client.d.ts

@@ -0,0 +1,84 @@
+/**
+ * The main-thread half of the web backend: a `PageRasterizer` over a worker.
+ *
+ * ------------------------------------------------------------------------
+ * THE CONTRACT WITH THE HOST — a worker FACTORY, not a URL
+ * ------------------------------------------------------------------------
+ *
+ * This package never constructs a `Worker` from a path of its own. Not from a
+ * hardcoded URL, and not from `new URL('./worker.js', import.meta.url)` — that
+ * form works in Vite and in a native ESM browser load, and does not survive
+ * every bundler, every `base`, or an SSR pass where `import.meta.url` is a file
+ * path on the server. A library that guesses wrong there fails at RUNTIME in the
+ * host's production build, which is the worst place to find out.
+ *
+ * So the host says how, once:
+ *
+ *     // Vite / Rollup — the form the spike proved on Vite 5.1.0
+ *     import PdfCanvasWorker from
+ *       '@reekon-tools/react-native-pdf-canvas/worker?worker';
+ *     import wasmUrl from '@embedpdf/pdfium/pdfium.wasm?url';
+ *
+ *     configureWebPdfium({
+ *       createWorker: () => new PdfCanvasWorker(),
+ *       wasm: {url: wasmUrl},
+ *     });
+ *
+ *     // Anything else — webpack 5, esbuild, a plain module script
+ *     createWorker: () =>
+ *       new Worker(new URL('.../worker.js', import.meta.url), {type: 'module'}),
+ *
+ * `type: 'module'` is required: the worker entry is ESM and statically imports
+ * `@embedpdf/pdfium`. The wasm locator is the host's for the same reason
+ * `./web-init.ts`'s CanvasKit locator is — see `PdfiumWasmSource`.
+ *
+ * ------------------------------------------------------------------------
+ * ONE WORKER PER DOCUMENT, TERMINATED ON `close()`
+ * ------------------------------------------------------------------------
+ *
+ * Not one worker per rasterizer, and this is a memory decision rather than a
+ * concurrency one. The Emscripten heap GROWS ONE WAY — it never returns pages to
+ * the OS — so on web the peak footprint of a session is permanent for the rest
+ * of the tab's life. MEASURED: 24 consecutive 512² tiles and 24 consecutive
+ * 1024² tiles leave the heap flat at 17.75 MiB, while ONE whole-page 2448x3168
+ * render takes it to 32.625 MiB and keeps it there.
+ *
+ * Terminating the worker is the only way to give that back. So a document's
+ * entire PDFium footprint — the parsed document, the page cache, the bitmap high
+ * water mark — dies with `close()`, and the cost is one wasm instantiation per
+ * document, MEASURED at 19 ms cold and 10 ms warm under node.
+ */
+import type { PdfiumWasmSource } from './protocol.js';
+import type { PageRasterizer } from '../../types.js';
+/**
+ * The worker surface this file uses, declared rather than imported.
+ *
+ * This package compiles with `lib: ["ES2022"]` and no DOM — the pure core has to
+ * keep loading with neither `react-native` nor a browser present, and pulling
+ * `lib.dom` in to name one type would let every DOM global into the whole
+ * package unnoticed.
+ *
+ * A real `Worker` satisfies this structurally. The listener parameter is
+ * `unknown` on purpose: method parameters are compared bivariantly, so a
+ * `(ev: MessageEvent) => void` listener is accepted, whereas the same shape
+ * written as a PROPERTY (`onmessage: …`) would be rejected under
+ * `strictFunctionTypes` and force every host to cast.
+ */
+export interface WorkerLike {
+    postMessage(message: unknown, transfer?: readonly unknown[]): void;
+    addEventListener(type: string, listener: (event: unknown) => void): void;
+    removeEventListener(type: string, listener: (event: unknown) => void): void;
+    terminate(): void;
+}
+export interface WebRasterizerOptions {
+    /**
+     * Makes one worker. Called once per `open()`, never memoised by this package
+     * — see the header for why a document owns its worker outright.
+     */
+    createWorker: () => WorkerLike;
+    /** Where the worker finds `pdfium.wasm`. Always the host's to say. */
+    wasm: PdfiumWasmSource;
+    /** Surfaced as `PageRasterizer.id` and in every diagnostic. */
+    id?: string;
+}
+export declare function createWebRasterizer(options: WebRasterizerOptions): PageRasterizer;