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

package/dist/rasterizer/web/client.js

@@ -0,0 +1,359 @@
+/**
+ * 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 { isTightBuffer } from '../buffer.js';
+import { isWorkerResponse } from './protocol.js';
+import { monotonicNow } from '../../clock.js';
+import { PdfError } from '../../types.js';
+/**
+ * WHAT THIS BACKEND ACTUALLY DOES, and nothing more.
+ *
+ * `annotations: true` is the one that has to be right rather than optimistic:
+ * `usePdfDocument` silently DOWNGRADES a request for annotations when the
+ * capability is false, so a lie here does not throw, it draws a different
+ * picture. PDFium draws PDF-embedded annotations when `FPDF_ANNOT` is in the
+ * render flags and omits them when it is not, and `engine.ts` passes the flag
+ * from `RasterRequest.annotations` — so unlike Android, which can only ever draw
+ * them, this backend genuinely honours both settings.
+ *
+ * `text` / `search` / `links` are false because none of them is implemented.
+ * PDFium can do all three (`FPDFText_*`, `FPDFLink_*`) and the seam has no place
+ * to expose them yet; declaring them true would be claiming an API that does not
+ * exist.
+ *
+ * `interruptibleRender: false`, honestly. `FPDF_RenderPageBitmap` is synchronous
+ * and a worker reads one message at a time, so nothing can interrupt a render
+ * once it has started. What an abort does do is stop a QUEUED render from
+ * starting and free the caller immediately — see `render` below. PDFium's
+ * progressive API (`FPDF_RenderPageBitmap_Start` / `FPDF_RenderPage_Continue`
+ * with an `IFSDK_PAUSE`) is the mechanism that would make this true, and is not
+ * used; whoever wires it up should flip this flag in the same commit.
+ *
+ * `maxConcurrentRenders: 1` — one worker, one PDFium, one thread. There is
+ * nothing for a second lane to overlap with.
+ *
+ * `transport` is deliberately ABSENT. The union — `base64`, `jsi-arraybuffer`,
+ * `direct` — has no member for a structured-clone transfer out of a worker, and
+ * the field is purely observational; its own docs say a backend that omits it is
+ * making no claim. Inventing a member on a frozen public union to report
+ * something nothing branches on is not a trade worth making.
+ */
+const CAPABILITIES = {
+    annotations: true,
+    interruptibleRender: false,
+    text: false,
+    search: false,
+    links: false,
+    maxConcurrentRenders: 1,
+};
+/**
+ * Request/response over one worker, keyed by an id this side allocates.
+ *
+ * The worker never initiates: every message it sends answers exactly one id, so
+ * there is no subscription model and no ordering requirement. That is what makes
+ * an abandoned id (an aborted render) safe to simply forget — the reply arrives,
+ * finds no entry, and is dropped.
+ */
+function createConnection(worker) {
+    const pending = new Map();
+    let nextId = 1;
+    let dead = null;
+    const failAll = (error) => {
+        dead = error;
+        for (const entry of pending.values())
+            entry.reject(error);
+        pending.clear();
+    };
+    const onMessage = (event) => {
+        const data = event?.data;
+        if (!isWorkerResponse(data)) {
+            // Not ours. A worker's message channel is not private, and a message we
+            // cannot parse must not be turned into a rejected render belonging to
+            // somebody else's id.
+            return;
+        }
+        if (data.kind === 'error' && data.id === null) {
+            failAll(new PdfError(data.code, data.message));
+            return;
+        }
+        const id = data.id;
+        if (id === null)
+            return;
+        const entry = pending.get(id);
+        if (entry === undefined)
+            return;
+        pending.delete(id);
+        if (data.kind === 'error') {
+            entry.reject(new PdfError(data.code, data.message));
+        }
+        else {
+            entry.resolve(data);
+        }
+    };
+    /**
+     * A worker that fails to LOAD reports it here and nowhere else — no request
+     * of ours ever gets a reply. Without this the first render would hang for
+     * ever, which is the single most confusing way for a bundler misconfiguration
+     * to present.
+     */
+    const onError = (event) => {
+        const message = event?.message ?? 'unknown worker error';
+        failAll(new PdfError('backend-failure', `The PDF worker failed: ${String(message)}. If this is the first ` +
+            'render, check that `createWorker` builds a MODULE worker ' +
+            "(`{type: 'module'}`) and that `@embedpdf/pdfium` resolves inside it."));
+    };
+    worker.addEventListener('message', onMessage);
+    worker.addEventListener('error', onError);
+    worker.addEventListener('messageerror', onError);
+    return {
+        nextId: () => nextId++,
+        /** Post and await the reply for `id`. The id is the caller's so it can abandon it. */
+        request(id, message, transfer) {
+            if (dead !== null)
+                return Promise.reject(dead);
+            return new Promise((resolve, reject) => {
+                pending.set(id, { resolve, reject });
+                worker.postMessage(message, transfer);
+            });
+        },
+        post(message) {
+            if (dead === null)
+                worker.postMessage(message);
+        },
+        /** Forget an id without failing it. Used when a render is aborted. */
+        abandon(id) {
+            pending.delete(id);
+        },
+        close(reason) {
+            worker.removeEventListener('message', onMessage);
+            worker.removeEventListener('error', onError);
+            worker.removeEventListener('messageerror', onError);
+            failAll(reason);
+            worker.terminate();
+        },
+    };
+}
+/* ------------------------------------------------------------------ *
+ * The rasterizer
+ * ------------------------------------------------------------------ */
+/**
+ * The document bytes, as something safe to TRANSFER.
+ *
+ * Always a copy, and never the host's own buffer. `postMessage` with a transfer
+ * list NEUTERS the source — the caller's `Uint8Array` would silently become
+ * zero-length — and `PdfSource.data` belongs to the caller, who is entitled to
+ * still have it afterwards (a retry, a second rasterizer, their own cache).
+ * `slice()` also fixes the subtler half: a `Uint8Array` that is a VIEW into a
+ * larger buffer would otherwise send the whole underlying allocation and PDFium
+ * would parse from the wrong offset.
+ */
+const detachedCopy = (data) => data.slice().buffer;
+export function createWebRasterizer(options) {
+    const id = options.id ?? 'web-pdfium';
+    return {
+        id,
+        capabilities: CAPABILITIES,
+        async open(source) {
+            const worker = options.createWorker();
+            const connection = createConnection(worker);
+            const openId = connection.nextId();
+            let wire;
+            let transfer;
+            if ('uri' in source) {
+                wire = {
+                    kind: 'open',
+                    id: openId,
+                    wasm: options.wasm,
+                    // FETCHED IN THE WORKER, not here. Same CORS rules either way, one
+                    // fewer copy across the boundary, and the main thread never holds a
+                    // whole document. rock-desktop's Firebase `getDownloadURL` tokens
+                    // work unchanged.
+                    source: { url: source.uri },
+                    password: source.password,
+                };
+            }
+            else {
+                const bytes = detachedCopy(source.data);
+                wire = {
+                    kind: 'open',
+                    id: openId,
+                    wasm: options.wasm,
+                    source: { bytes },
+                    password: source.password,
+                };
+                // Ours to give away — `detachedCopy` made it for this.
+                transfer = [bytes];
+            }
+            let opened;
+            try {
+                opened = await connection.request(openId, wire, transfer);
+            }
+            catch (error) {
+                connection.close(error instanceof PdfError
+                    ? error
+                    : new PdfError('backend-failure', String(error)));
+                throw error;
+            }
+            if (opened.kind !== 'opened') {
+                const failure = new PdfError('backend-failure', `The worker answered an open with a ${opened.kind} message.`);
+                connection.close(failure);
+                throw failure;
+            }
+            return createHandle(connection, id, opened.pageCount, opened.pages);
+        },
+    };
+}
+function createHandle(connection, backendId, pageCount, pages) {
+    let closed = false;
+    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,
+        /**
+         * SYNCHRONOUS, and answered entirely from what `open()` already read. No
+         * message, no page load — see `readGeometry` in `./engine.ts`, which reads
+         * every page's post-rotation size out of the page dictionary at open.
+         */
+        pageGeometry: requirePage,
+        async render(request, signal) {
+            if (closed) {
+                throw new PdfError('backend-failure', `${backendId} handle is closed.`);
+            }
+            requirePage(request.page);
+            if (signal?.aborted === true) {
+                throw new PdfError('cancelled', 'Render was aborted before it started.');
+            }
+            const id = connection.nextId();
+            const startedAt = monotonicNow();
+            /**
+             * ABORT DOES TWO THINGS, AND ONLY THE FIRST IS GUARANTEED.
+             *
+             * It frees the CALLER immediately — the promise rejects `cancelled` and
+             * the controller stops waiting on a tile it no longer wants. And it posts
+             * a `cancel`, which the worker honours if the render has not started yet
+             * (see the yield in `./session.ts`) and cannot honour if it has. The id is
+             * abandoned either way, so a raster that does arrive is dropped rather
+             * than resolving a promise nobody holds.
+             *
+             * This is `interruptibleRender: false` stated as behaviour: cancellation
+             * happens between requests.
+             */
+            let abort;
+            const cancelled = new Promise((_, reject) => {
+                abort = () => {
+                    connection.abandon(id);
+                    connection.post({ kind: 'cancel', id });
+                    reject(new PdfError('cancelled', 'Render was aborted.'));
+                };
+                signal?.addEventListener('abort', abort, { once: true });
+            });
+            // Nothing awaits this branch when the render wins, and an unhandled
+            // rejection on a promise that lost a race is noise in every console.
+            cancelled.catch(() => { });
+            let response;
+            try {
+                response = await Promise.race([
+                    connection.request(id, { kind: 'render', id, request }),
+                    cancelled,
+                ]);
+            }
+            finally {
+                if (abort !== undefined)
+                    signal?.removeEventListener('abort', abort);
+            }
+            if (response.kind !== 'rendered') {
+                throw new PdfError('backend-failure', `The worker answered a render with a ${response.kind} message.`);
+            }
+            const bridgeEndedAt = monotonicNow();
+            const bytes = new Uint8Array(response.bytes);
+            return {
+                bytes,
+                width: response.width,
+                height: response.height,
+                // From the worker, which read `FPDFBitmap_GetStride`. Never recomputed
+                // as width * 4 — a wrong stride shears the image instead of failing.
+                rowBytes: response.rowBytes,
+                format: response.format,
+                alpha: response.alpha,
+                timings: {
+                    // The whole round trip, INCLUDING PDFium's work at the far end. There
+                    // is no second clock here: the worker's own render time is not
+                    // reported, because splitting it would need a clock the two threads
+                    // share and nothing reads the difference.
+                    bridgeMs: bridgeEndedAt - startedAt,
+                    // Structurally zero. The payload crossed as a transferred
+                    // ArrayBuffer, so there is no string, no decode and nothing to count
+                    // — which is the headline, not an omission.
+                    decodeMs: 0,
+                    payloadChars: 0,
+                    // Measured rather than asserted, though it is true by construction:
+                    // the worker `slice()`s the raster out of the WASM heap into its own
+                    // exactly-sized buffer, and a transfer preserves that.
+                    tight: isTightBuffer(bytes),
+                },
+            };
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            // The `close` message is posted first so an in-process worker can free
+            // the document properly; a real one is terminated before it reads it, and
+            // terminating is what actually reclaims the WASM heap. See the header.
+            connection.post({ kind: 'close' });
+            connection.close(new PdfError('cancelled', 'The document was closed mid-render.'));
+        },
+    };
+}

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

@@ -0,0 +1,69 @@
+/**
+ * The PDFium half of the web backend: open a document, measure its pages,
+ * render an arbitrary doc-space rect.
+ *
+ * PURE IN THE SAME SENSE `../android.ts` IS. It takes a `PdfiumBinding` and
+ * imports nothing else — no worker, no DOM, no `@embedpdf/pdfium`. Which means
+ * the interesting half of this backend (rect registration, stride, the
+ * background fill, `/Rotate`, the error codes) is exercised in vitest under
+ * plain node against the REAL WASM module, not against a mock of it. See
+ * `__tests__/web-rasterizer.test.ts`.
+ *
+ * ------------------------------------------------------------------------
+ * THE RECT MECHANISM — negative offsets, not a matrix
+ * ------------------------------------------------------------------------
+ *
+ * PDFium's public way to draw part of a page is to describe the WHOLE page at
+ * the target scale and then slide it: `FPDF_RenderPageBitmap(bitmap, page,
+ * -x*s, -y*s, pageW*s, pageH*s, 0, flags)` into a bitmap that is only the tile's
+ * size. Everything outside the bitmap is clipped away by the bitmap itself.
+ *
+ * The alternative, `FPDF_RenderPageBitmapWithMatrix` with
+ * `FS_MATRIX{a:s, b:0, c:0, d:s, e:-x*s, f:-y*s}` and an `FS_RECTF(0,0,w,h)`
+ * clip, was MEASURED to be byte-identical to this on every rect tested —
+ * including a rect whose device offset is fractional (x*s = 33.6999…), where the
+ * two might plausibly have rounded differently and do not. The matrix form also
+ * has a trap this one does not: passing a NULL clip renders NOTHING AT ALL
+ * (measured: an all-white bitmap, no error). The simpler mechanism with no null
+ * case is the one that ships.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THE OFFSET IS `-round(x*s)` AND NOT `round(-x*s)`
+ * ------------------------------------------------------------------------
+ *
+ * Because the tile's origin inside a hypothetical full-page render is
+ * `round(x*s)`, and the registration property is that the tile equals that
+ * region exactly. Negating the rounded origin makes those two the same integer
+ * by construction. `Math.round(-0.5)` is `-0` while `-Math.round(0.5)` is `-1`,
+ * so the two spellings genuinely differ on half-pixel boundaries — which is
+ * exactly where a misregistration would be least likely to be noticed and most
+ * likely to be real.
+ */
+import type { PdfiumBinding } from './pdfium.js';
+import type { AlphaEncoding, PageGeometry, PixelFormat, RasterRequest } from '../../types.js';
+export interface PdfiumRasterBytes {
+    /** Tight: its own exactly-sized ArrayBuffer, ready to transfer. */
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+    rowBytes: number;
+    format: PixelFormat;
+    alpha: AlphaEncoding;
+}
+export interface PdfiumDocument {
+    readonly pageCount: number;
+    /** Every page, measured once at open. */
+    readonly pages: readonly PageGeometry[];
+    render(request: RasterRequest): PdfiumRasterBytes;
+    close(): void;
+}
+/**
+ * Open a document from bytes.
+ *
+ * THE BYTES ARE COPIED INTO THE WASM HEAP AND STAY THERE. `FPDF_LoadMemDocument`
+ * does not take ownership and does not copy: PDFium reads the buffer lazily for
+ * the whole life of the document, so freeing it early is a use-after-free inside
+ * the WASM heap — which does not crash, it produces wrong pixels. `close()`
+ * frees it, after `FPDF_CloseDocument` and never before.
+ */
+export declare function openPdfiumDocument(api: PdfiumBinding, bytes: Uint8Array, password?: string): PdfiumDocument;