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

package/dist/rasterizer/web/pdfium.js

@@ -0,0 +1,170 @@
+/**
+ * The PDFium surface this package uses, and the adapter that produces it.
+ *
+ * ------------------------------------------------------------------------
+ * WHY A STRUCTURAL INTERFACE INSTEAD OF `@embedpdf/pdfium`'s OWN TYPE
+ * ------------------------------------------------------------------------
+ *
+ * Same discipline as `AndroidPdfNativeModule` in `../android.ts`, and for the
+ * same two reasons.
+ *
+ *   1. THE ENGINE STAYS PURE AND TESTABLE. `./engine.ts` takes a
+ *      `PdfiumBinding` and never names the package, so the whole open/geometry/
+ *      render/error path runs in vitest against the real WASM module — or
+ *      against a stub — with no worker, no DOM and no bundler in the loop.
+ *   2. THE PUBLISHED TYPES CARRY NO PEER. `@embedpdf/pdfium` is an OPTIONAL peer
+ *      dependency: a consumer who only ships native must not have their build
+ *      break on a missing module referenced from our `.d.ts`. Nothing in this
+ *      file imports it, not even as a type. `./worker.ts` is the one module that
+ *      names it at all, and it exports nothing typed by it.
+ *
+ * The obvious risk of a hand-written structural type is that it drifts from the
+ * real module and nobody notices until runtime. It cannot here: `./worker.ts`
+ * calls `bindPdfium(await init(...))` with the genuine `WrappedPdfiumModule`,
+ * and that file IS type-checked by `tsc --noEmit`. A wrong arity or a renamed
+ * export fails the build.
+ *
+ * ------------------------------------------------------------------------
+ * EVERY CONSTANT AND SEMANTIC BELOW WAS MEASURED AGAINST 2.15.0, NOT READ
+ * ------------------------------------------------------------------------
+ *
+ * The notes that say "measured" mean a script that called the real WASM module
+ * under node and printed the answer. See each one.
+ */
+import { PdfError } from '../../types.js';
+/* ------------------------------------------------------------------ *
+ * Constants
+ * ------------------------------------------------------------------ */
+/**
+ * `FPDFBitmap_BGRA`. The only four-channel format PDFium's public bitmap API
+ * offers, and the one every render path below creates.
+ *
+ * It describes the BUFFER, not the render: adding `FPDF_REVERSE_BYTE_ORDER` to
+ * the render flags leaves the bitmap tagged BGRA while the bytes come out RGBA.
+ * That is not a contradiction to fix — the flag is documented as acting on the
+ * composite, and it is why `renderPage` derives `PixelFormat` from the FLAGS it
+ * passed rather than from the bitmap format it asked for.
+ */
+export const FPDF_BITMAP_BGRA = 4;
+/** Draw PDF-embedded annotations. Answers `RasterRequest.annotations`. */
+export const FPDF_ANNOT = 0x01;
+/**
+ * Write RGBA instead of BGRA.
+ *
+ * MEASURED: with the flag, a `0.2 0.4 0.9 rg` fill reads `[51, 102, 230, 255]`;
+ * without it, `[230, 102, 51, 255]`. Same bitmap format, swapped R and B.
+ *
+ * THE WEB BACKEND ALWAYS PASSES IT, and that is a deliberate choice about the
+ * INGEST side rather than about PDFium. `imageFromPixels` maps `'bgra8888'` to
+ * `ColorType.BGRA_8888`, which CanvasKit exposes but which a GPU-backed build
+ * may still refuse from `MakeImage` — and the recovery for that is a full extra
+ * pass over the buffer swizzling R and B in JS. RGBA is the configuration every
+ * Skia backend accepts, PDFium produces it for free inside the composite it was
+ * already doing, and the JS-side fallback pass never runs.
+ */
+export const FPDF_REVERSE_BYTE_ORDER = 0x10;
+/**
+ * `FPDF_GetLastError()`'s codes.
+ *
+ * ONLY MEANINGFUL IMMEDIATELY AFTER A FAILED DOCUMENT LOAD. MEASURED: after
+ * loading an encrypted document without a password (which sets 4), a subsequent
+ * `FPDF_GetPageSizeByIndexF` for an out-of-range index returns false and leaves
+ * the error at 4 — the stale value from the earlier call. So this table is
+ * consulted in exactly one place, `mapLoadError`, and every other failure in
+ * this backend is decided by its own bounds check or return value.
+ */
+export const PDFIUM_ERR = {
+    SUCCESS: 0,
+    UNKNOWN: 1,
+    FILE: 2,
+    FORMAT: 3,
+    PASSWORD: 4,
+    SECURITY: 5,
+    PAGE: 6,
+};
+/**
+ * Turn an initialised `@embedpdf/pdfium` module into a `PdfiumBinding`.
+ *
+ * Deliberately mechanical. The only judgement in here is `heapU8`, which reads
+ * `HEAPU8` off the module on EVERY call rather than closing over it — see
+ * `PdfiumHeap`.
+ */
+export function bindPdfium(module) {
+    const { pdfium } = module;
+    return {
+        heapU8: () => pdfium.HEAPU8,
+        malloc: byteLength => pdfium.wasmExports.malloc(byteLength),
+        free: pointer => pdfium.wasmExports.free(pointer),
+        getFloat: pointer => Number(pdfium.getValue(pointer, 'float')),
+        FPDF_LoadMemDocument: (pointer, byteLength, password) => module.FPDF_LoadMemDocument(pointer, byteLength, password),
+        FPDF_CloseDocument: document => {
+            module.FPDF_CloseDocument(document);
+        },
+        FPDF_GetLastError: () => module.FPDF_GetLastError(),
+        FPDF_GetPageCount: document => module.FPDF_GetPageCount(document),
+        FPDF_GetPageSizeByIndexF: (document, index, sizeOut) => module.FPDF_GetPageSizeByIndexF(document, index, sizeOut),
+        EPDF_GetPageRotationByIndex: (document, index) => module.EPDF_GetPageRotationByIndex(document, index),
+        FPDF_LoadPage: (document, index) => module.FPDF_LoadPage(document, index),
+        FPDF_ClosePage: page => {
+            module.FPDF_ClosePage(page);
+        },
+        FPDFBitmap_CreateEx: (width, height, format, firstScan, stride) => module.FPDFBitmap_CreateEx(width, height, format, firstScan, stride),
+        FPDFBitmap_Destroy: bitmap => {
+            module.FPDFBitmap_Destroy(bitmap);
+        },
+        FPDFBitmap_FillRect: (bitmap, left, top, width, height, color) => module.FPDFBitmap_FillRect(bitmap, left, top, width, height, color),
+        FPDFBitmap_GetBuffer: bitmap => module.FPDFBitmap_GetBuffer(bitmap),
+        FPDFBitmap_GetStride: bitmap => module.FPDFBitmap_GetStride(bitmap),
+        FPDF_RenderPageBitmap: (bitmap, page, startX, startY, sizeX, sizeY, rotate, flags) => {
+            module.FPDF_RenderPageBitmap(bitmap, page, startX, startY, sizeX, sizeY, rotate, flags);
+        },
+    };
+}
+/* ------------------------------------------------------------------ *
+ * Errors
+ * ------------------------------------------------------------------ */
+/**
+ * `FPDF_GetLastError()` after a failed load -> the frozen `PdfErrorCode` union.
+ *
+ * `passwordSupplied` is what tells the two password outcomes apart, and it has
+ * to: MEASURED, PDFium returns 4 both for an encrypted document opened with no
+ * password and for one opened with the WRONG password. There is no code that
+ * distinguishes them, so the caller's own knowledge does — and the distinction
+ * matters, because one of them means "prompt the user" and the other means
+ * "tell them they got it wrong".
+ */
+export function mapLoadError(error, passwordSupplied) {
+    switch (error) {
+        case PDFIUM_ERR.FILE:
+            return 'not-found';
+        case PDFIUM_ERR.FORMAT:
+            // MEASURED: both a truncated document and an eight-byte non-PDF report
+            // this.
+            return 'corrupt';
+        case PDFIUM_ERR.PASSWORD:
+            return passwordSupplied ? 'password-incorrect' : 'password-required';
+        case PDFIUM_ERR.SECURITY:
+            // An encryption scheme this PDFium build cannot handle. Not corruption
+            // and not a wrong password — nothing the user can do about it.
+            return 'unsupported';
+        case PDFIUM_ERR.PAGE:
+            return 'corrupt';
+        default:
+            return 'backend-failure';
+    }
+}
+const ERROR_NAMES = {
+    [PDFIUM_ERR.SUCCESS]: 'SUCCESS',
+    [PDFIUM_ERR.UNKNOWN]: 'UNKNOWN',
+    [PDFIUM_ERR.FILE]: 'FILE',
+    [PDFIUM_ERR.FORMAT]: 'FORMAT',
+    [PDFIUM_ERR.PASSWORD]: 'PASSWORD',
+    [PDFIUM_ERR.SECURITY]: 'SECURITY',
+    [PDFIUM_ERR.PAGE]: 'PAGE',
+};
+/** The load failure, as the error a host can branch on. */
+export function loadError(error, passwordSupplied) {
+    const name = ERROR_NAMES[error] ?? String(error);
+    return new PdfError(mapLoadError(error, passwordSupplied), `PDFium could not open the document (FPDF_GetLastError = ${error} ` +
+        `${name}${passwordSupplied ? ', a password was supplied' : ''}).`);
+}

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

@@ -0,0 +1,138 @@
+/**
+ * The wire between the main thread and the PDFium worker.
+ *
+ * PURE TYPES AND ONE PREDICATE. Both sides import this file, which is what stops
+ * the two halves of a message from being written twice and drifting — the exact
+ * failure mode the Android backend avoids by making `PdfErrorCode`'s members the
+ * wire format on the Java side too.
+ *
+ * EVERYTHING HERE IS STRUCTURED-CLONEABLE. `DocRect`, `PageGeometry` and
+ * `RasterRequest` are plain data by construction, and the one binary payload is
+ * an `ArrayBuffer` that is TRANSFERRED rather than copied — see
+ * `RenderedResponse.bytes`.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THE WASM SOURCE TRAVELS IN THE `open` MESSAGE
+ * ------------------------------------------------------------------------
+ *
+ * Because a worker is created per document (see `./client.ts`), so the first
+ * message it ever receives is `open` and there is nothing for a separate
+ * `init` message to be ordered against. Folding it in removes a state — "worker
+ * exists but has not been told where its wasm is" — that could otherwise be
+ * observed by a `render` arriving first.
+ */
+import type { AlphaEncoding, PageGeometry, PdfErrorCode, PixelFormat, RasterRequest } from '../../types.js';
+/**
+ * Where the worker gets `pdfium.wasm`.
+ *
+ * TWO FORMS, AND BOTH ARE THE HOST'S TO SUPPLY — this package hardcodes no URL,
+ * for the same reason `./web-init.ts` hardcodes no CanvasKit URL: the version
+ * that has to match is the one the host's tree installed, and a baked-in CDN
+ * path either fights that pin or silently serves a different wasm than the JS
+ * bindings were built against.
+ *
+ * - `{url}` — handed to Emscripten's `locateFile`, so it can stream-compile.
+ *   The normal case: `import wasmUrl from '@embedpdf/pdfium/pdfium.wasm?url'`,
+ *   and the one to prefer: the browser's HTTP cache serves the second document's
+ *   worker from memory, so a session pays for the download once.
+ * - `{binary}` — already-fetched bytes. What the node tests use (read off disk),
+ *   and what a host with its own asset pipeline or an offline bundle wants. It
+ *   is COPIED into each worker rather than transferred — transferring would
+ *   neuter the host's buffer and the second document would find it empty — so a
+ *   4.6 MB structured clone is paid per `open()`.
+ */
+export type PdfiumWasmSource = {
+    url: string;
+} | {
+    binary: ArrayBuffer;
+};
+/** The document, as it crosses to the worker. `{uri}` is fetched THERE. */
+export type PdfiumDocumentSource = {
+    url: string;
+} | {
+    bytes: ArrayBuffer;
+};
+export interface OpenRequest {
+    kind: 'open';
+    id: number;
+    wasm: PdfiumWasmSource;
+    source: PdfiumDocumentSource;
+    password?: string;
+}
+export interface RenderRequest {
+    kind: 'render';
+    id: number;
+    request: RasterRequest;
+}
+/**
+ * Drop a render that has not started yet.
+ *
+ * BEST EFFORT AND HONEST ABOUT IT. The worker renders synchronously, so a
+ * `cancel` can only ever be delivered BETWEEN renders — never into one. What it
+ * genuinely does is stop a QUEUED render from starting, which is why the worker
+ * yields to its event loop between jobs (see `./session.ts`): without that
+ * yield, messages queued behind a burst of renders would not be read until the
+ * burst had finished and this message would be worthless.
+ */
+export interface CancelRequest {
+    kind: 'cancel';
+    id: number;
+}
+/**
+ * Close the document and stop.
+ *
+ * REDUNDANT IN A REAL WORKER, and kept anyway. `RasterizerHandle.close()`
+ * terminates the worker, which reclaims the entire WASM heap in one step — the
+ * whole reason a worker is created per document. This message will usually not
+ * even be read before that happens.
+ *
+ * It earns its place on the other side: the in-process worker the tests drive
+ * has no `terminate()` that can free an Emscripten heap, so this is what
+ * exercises `PdfiumDocument.close()` — the `FPDF_CloseDocument`-then-`free`
+ * ordering that a use-after-free in the WASM heap depends on — under vitest.
+ */
+export interface CloseRequest {
+    kind: 'close';
+}
+export type WorkerRequest = OpenRequest | RenderRequest | CancelRequest | CloseRequest;
+export interface OpenedResponse {
+    kind: 'opened';
+    id: number;
+    pageCount: number;
+    pages: PageGeometry[];
+}
+export interface RenderedResponse {
+    kind: 'rendered';
+    id: number;
+    /** TRANSFERRED. Neutered on the worker side the moment it is posted. */
+    bytes: ArrayBuffer;
+    width: number;
+    height: number;
+    rowBytes: number;
+    format: PixelFormat;
+    /**
+     * Carried on the wire rather than restated on the main thread, for the same
+     * reason `RasterPixels` carries it: the declaration belongs next to the bytes
+     * it describes. It is constant for this backend today; a second render path
+     * (a flattened export, a different bitmap format) would make it not be, and
+     * the wire would already say so.
+     */
+    alpha: AlphaEncoding;
+}
+export interface ErrorResponse {
+    kind: 'error';
+    /** Null for a failure that belongs to no single request. */
+    id: number | null;
+    code: PdfErrorCode;
+    message: string;
+}
+export type WorkerResponse = OpenedResponse | RenderedResponse | ErrorResponse;
+/**
+ * Is this a message from our worker?
+ *
+ * A worker's `message` event is not a private channel — anything with a handle
+ * to it can post — and the payload arrives as `unknown`. Narrowing here rather
+ * than casting at the call site means a malformed message becomes a rejected
+ * promise with a name on it, not a `TypeError` deep in the connection.
+ */
+export declare function isWorkerResponse(value: unknown): value is WorkerResponse;

package/dist/rasterizer/web/protocol.js

@@ -0,0 +1,37 @@
+/**
+ * The wire between the main thread and the PDFium worker.
+ *
+ * PURE TYPES AND ONE PREDICATE. Both sides import this file, which is what stops
+ * the two halves of a message from being written twice and drifting — the exact
+ * failure mode the Android backend avoids by making `PdfErrorCode`'s members the
+ * wire format on the Java side too.
+ *
+ * EVERYTHING HERE IS STRUCTURED-CLONEABLE. `DocRect`, `PageGeometry` and
+ * `RasterRequest` are plain data by construction, and the one binary payload is
+ * an `ArrayBuffer` that is TRANSFERRED rather than copied — see
+ * `RenderedResponse.bytes`.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THE WASM SOURCE TRAVELS IN THE `open` MESSAGE
+ * ------------------------------------------------------------------------
+ *
+ * Because a worker is created per document (see `./client.ts`), so the first
+ * message it ever receives is `open` and there is nothing for a separate
+ * `init` message to be ordered against. Folding it in removes a state — "worker
+ * exists but has not been told where its wasm is" — that could otherwise be
+ * observed by a `render` arriving first.
+ */
+/**
+ * Is this a message from our worker?
+ *
+ * A worker's `message` event is not a private channel — anything with a handle
+ * to it can post — and the payload arrives as `unknown`. Narrowing here rather
+ * than casting at the call site means a malformed message becomes a rejected
+ * promise with a name on it, not a `TypeError` deep in the connection.
+ */
+export function isWorkerResponse(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const kind = value.kind;
+    return kind === 'opened' || kind === 'rendered' || kind === 'error';
+}

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

@@ -0,0 +1,106 @@
+/**
+ * The worker's own logic, with `self` factored out.
+ *
+ * `./worker.ts` is nothing but the four lines that bind this to a real
+ * `DedicatedWorkerGlobalScope`; everything a bug could live in — the queue, the
+ * cancellation window, the fetch, the error mapping, the open-before-render
+ * ordering — is here, takes its dependencies as arguments, and runs in vitest
+ * under plain node against the REAL PDFium module.
+ *
+ * ------------------------------------------------------------------------
+ * THE YIELD IS THE CANCELLATION MECHANISM
+ * ------------------------------------------------------------------------
+ *
+ * A worker processes messages one at a time and `FPDF_RenderPageBitmap` is
+ * synchronous, so nothing can interrupt a render that has started. What CAN be
+ * stopped is a render that has not started — and only if the `cancel` message
+ * gets read first. Handling each `render` message by rendering inside the
+ * handler would make that impossible: messages are FIFO, so three queued renders
+ * would all complete before a `cancel` posted after them was ever looked at.
+ *
+ * So renders are QUEUED here and drained one per macrotask, with a yield between
+ * them. That yield is the only window in which a `cancel` can land, and it is
+ * exactly what `RasterizerCapabilities.interruptibleRender: false` means in
+ * practice: cancellation happens between requests, never inside one.
+ *
+ * See `macrotaskYield` below for what that yield is actually made of, and why it
+ * is not the `setTimeout(0)` it used to be.
+ */
+import type { PdfiumBinding } from './pdfium.js';
+import type { PdfiumWasmSource, WorkerRequest, WorkerResponse } from './protocol.js';
+/**
+ * The slice of `fetch` this file uses.
+ *
+ * Declared rather than imported: this package compiles with `lib: ["ES2022"]`
+ * and no DOM, deliberately — the pure core must keep loading with neither
+ * `react-native` nor a browser present, and a `lib: ["DOM"]` would let a DOM
+ * global be referenced anywhere in the package without anyone noticing.
+ */
+export interface FetchResponseLike {
+    ok: boolean;
+    status: number;
+    statusText: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export type FetchLike = (url: string) => Promise<FetchResponseLike>;
+export interface WorkerSessionDeps {
+    /** Post one response, transferring any binary payload rather than copying. */
+    post(response: WorkerResponse, transfer?: readonly ArrayBuffer[]): void;
+    /**
+     * Initialise PDFium and hand back the binding. Called at most ONCE, on the
+     * `open` message, so a worker that is created and then discarded never
+     * compiles the wasm at all.
+     */
+    loadPdfium(wasm: PdfiumWasmSource): Promise<PdfiumBinding>;
+    /** Defaults to `globalThis.fetch`. Injected by the tests. */
+    fetch?: FetchLike;
+    /**
+     * Defaults to `macrotaskYield`. See the header — this is the cancel window.
+     *
+     * Kept injectable for the tests that need to COUNT yields or drive the drain
+     * loop deterministically. Nothing on the shipped path passes it, so the
+     * default is what every browser actually runs and what the abort tests in
+     * `web-rasterizer.test.ts` exercise.
+     */
+    yieldToEventLoop?: () => Promise<void>;
+}
+export interface WorkerSession {
+    handle(request: WorkerRequest): void;
+    /** Close the document and refuse everything after. Idempotent. */
+    dispose(): void;
+}
+/**
+ * THE CANCEL WINDOW: a port hop, and then a timer turn.
+ *
+ * WHY A PORT HOP. It is a macrotask that no clamp applies to. Same Chrome
+ * worker, same 24 consecutive yields as `timerYield`'s 90.0 ms: 0.2 ms total,
+ * mean 0.008 ms.
+ *
+ * WHY A TIMER TURN AS WELL. Because a port hop ALONE does not drain the timer
+ * queue, and the timer queue is where the `cancel` is. Measured on node v24.14.0
+ * with K `setTimeout(0)` callbacks already pending when the yield starts, 20
+ * trials at each K in {1, 2, 4, 8, 16, 32}: a timer yield runs ALL K of them
+ * before it resolves, in every trial; a bare port hop runs ZERO of them, in
+ * every trial. A port-only yield would have narrowed the very window this file
+ * exists to keep open, and would have done it quietly — the abort test in
+ * `web-rasterizer.test.ts` delivers its cancels over a `setTimeout`-backed
+ * channel, so a bare hop turns that test flaky rather than loudly wrong.
+ *
+ * AND THE TIMER TURN IS FREE, which is the whole reason this shape works: the
+ * hop RESETS the nesting level Chrome clamps on, because the timer is always
+ * scheduled from a port-message task and never from another timer task.
+ * Measured in the same worker over the same 24 yields: 0.1-0.3 ms total, mean
+ * 0.004-0.013 ms — indistinguishable from the bare hop, and ~280x cheaper than
+ * the bare timer it replaces.
+ *
+ * So this is STRICTLY STRONGER than what it replaces — a hop AND a full timer
+ * turn, where there was only a timer turn — at 1/280th the cost, and its worst
+ * case (a runtime that clamps the following timer anyway) is exactly the
+ * behaviour that shipped before it.
+ *
+ * Exported for `web-rasterizer.test.ts`, which asserts the drained-timer
+ * property above directly. Still not public: nothing in the package's `exports`
+ * map reaches `session.ts` except `./worker`, which re-exports nothing.
+ */
+export declare const macrotaskYield: () => Promise<void>;
+export declare function createWorkerSession(deps: WorkerSessionDeps): WorkerSession;