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

package/dist/rasterizer/web/engine.js

@@ -0,0 +1,308 @@
+/**
+ * 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 { FPDF_ANNOT, FPDF_BITMAP_BGRA, FPDF_REVERSE_BYTE_ORDER, loadError, } from './pdfium.js';
+import { PdfError } from '../../types.js';
+/**
+ * MEASURED, not inherited from the other backends. An antialiased opaque-white
+ * edge over a transparent page reads `[255, 255, 255, 50]` and
+ * `[255, 255, 255, 178]` out of PDFium; premultiplied would have been
+ * `[50, 50, 50, 50]` and `[178, 178, 178, 178]`. So the web backend declares
+ * `'straight'` and Android declares `'premultiplied'`, which is the entire
+ * reason `RasterPixels.alpha` is a required field rather than a constant in
+ * `ingest.ts`.
+ *
+ * INVISIBLE UNDER `background: 'white'` — every pixel is opaque there and the
+ * two encodings are byte-identical — so this can only ever be caught by a test
+ * that renders `background: 'transparent'`. There is one.
+ */
+const PDFIUM_ALPHA = 'straight';
+/** See `FPDF_REVERSE_BYTE_ORDER`: the flag is always passed, so this follows. */
+const PDFIUM_FORMAT = 'rgba8888';
+/** ARGB. Both of the two values used are symmetric under an R/B swap, which is
+ * what makes filling BEFORE a reverse-byte-order render correct rather than
+ * lucky: `FPDFBitmap_FillRect` writes in the bitmap's own BGRA order. */
+const OPAQUE_WHITE = 0xffffffff;
+const TRANSPARENT = 0x00000000;
+/** PDFium's ints are 32-bit; a request past this cannot be expressed at all. */
+const MAX_INT32 = 0x7fffffff;
+const ROTATIONS = [0, 90, 180, 270];
+/* ------------------------------------------------------------------ *
+ * Open
+ * ------------------------------------------------------------------ */
+/**
+ * Read every page's size and rotation without loading a single page.
+ *
+ * This is what makes `RasterizerHandle.pageGeometry` synchronous. Both calls
+ * work off the page DICTIONARY — no content stream is parsed — so the cost is
+ * proportional to the page tree and not to what is drawn on it.
+ *
+ * A page that cannot be measured fails the OPEN rather than being papered over
+ * with a zero size. A `PageGeometry` is what the layout function turns into the
+ * document's whole coordinate space; a wrong one there is not a missing page,
+ * it is every page after it in the wrong place.
+ */
+function readGeometry(api, document, pageCount) {
+    const sizeOut = api.malloc(8);
+    try {
+        const pages = [];
+        for (let index = 0; index < pageCount; index++) {
+            if (!api.FPDF_GetPageSizeByIndexF(document, index, sizeOut)) {
+                throw new PdfError('corrupt', `PDFium could not read the size of page ${index} of ${pageCount}.`);
+            }
+            const rotationIndex = api.EPDF_GetPageRotationByIndex(document, index);
+            pages.push({
+                index,
+                // ALREADY POST-ROTATION, and measured to be so — see
+                // `FPDF_GetPageSizeByIndexF`. Swapping width and height here for a
+                // 90/270 page would rotate it twice.
+                width: api.getFloat(sizeOut),
+                height: api.getFloat(sizeOut + 4),
+                // -1 is PDFium's "no such page", which the size read above has already
+                // ruled out; anything else outside 0..3 would be a new return
+                // convention. Both fall back to 0 rather than failing the open: an
+                // unrotated page whose dimensions are right still draws correctly, and
+                // `PageGeometry.rotation` is informational to this package.
+                rotation: ROTATIONS[rotationIndex] ?? 0,
+            });
+        }
+        return pages;
+    }
+    finally {
+        api.free(sizeOut);
+    }
+}
+/**
+ * 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 function openPdfiumDocument(api, bytes, password) {
+    if (bytes.byteLength === 0) {
+        throw new PdfError('corrupt', 'The document is empty (0 bytes).');
+    }
+    const dataPointer = api.malloc(bytes.byteLength);
+    if (dataPointer === 0) {
+        throw new PdfError('out-of-memory', `Could not allocate ${bytes.byteLength} bytes in the PDFium heap for ` +
+            'the document.');
+    }
+    api.heapU8().set(bytes, dataPointer);
+    const document = api.FPDF_LoadMemDocument(dataPointer, bytes.byteLength, password ?? '');
+    if (document === 0) {
+        const error = api.FPDF_GetLastError();
+        api.free(dataPointer);
+        throw loadError(error, password !== undefined && password !== '');
+    }
+    let pages;
+    const pageCount = api.FPDF_GetPageCount(document);
+    try {
+        pages = readGeometry(api, document, pageCount);
+    }
+    catch (error) {
+        api.FPDF_CloseDocument(document);
+        api.free(dataPointer);
+        throw error;
+    }
+    return createDocument(api, document, dataPointer, pages);
+}
+/* ------------------------------------------------------------------ *
+ * Render
+ * ------------------------------------------------------------------ */
+function createDocument(api, document, dataPointer, pages) {
+    let closed = false;
+    /**
+     * ONE loaded page, cached.
+     *
+     * `FPDF_LoadPage` is the call that parses the content stream, and an epoch is
+     * several tiles of the same page — so caching turns N parses into one. It is
+     * capped at ONE rather than being an LRU on purpose: a parsed page lives in
+     * the Emscripten heap, and that heap only ever grows (it never returns pages
+     * to the OS), so "how many parsed pages may be resident" is a permanent floor
+     * on the tab's memory and not a cache-tuning question. Alternating between two
+     * pages costs a reparse; holding both costs the session.
+     */
+    let loadedIndex = -1;
+    let loadedPage = 0;
+    const releasePage = () => {
+        if (loadedPage !== 0) {
+            api.FPDF_ClosePage(loadedPage);
+            loadedPage = 0;
+            loadedIndex = -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;
+    };
+    const loadPage = (index) => {
+        if (loadedIndex === index && loadedPage !== 0)
+            return loadedPage;
+        releasePage();
+        const page = api.FPDF_LoadPage(document, index);
+        if (page === 0) {
+            // Not `FPDF_GetLastError` — see `PDFIUM_ERR`, it is stale here. The index
+            // was already bounds-checked against the geometry read at open, so a
+            // failure at this point is a page whose content PDFium refuses.
+            throw new PdfError('corrupt', `PDFium could not load page ${index}. The page exists (its size was ` +
+                'read at open) but its content could not be parsed.');
+        }
+        loadedIndex = index;
+        loadedPage = page;
+        return page;
+    };
+    return {
+        pageCount: pages.length,
+        pages,
+        render(request) {
+            if (closed) {
+                throw new PdfError('backend-failure', 'The document is closed.');
+            }
+            const geometry = requirePage(request.page);
+            const { docRect, scale } = request;
+            if (!Number.isFinite(scale) || scale <= 0) {
+                throw new PdfError('backend-failure', `Scale must be a positive finite number, got ${scale}.`);
+            }
+            if (!Number.isFinite(docRect.x) ||
+                !Number.isFinite(docRect.y) ||
+                !(docRect.width > 0) ||
+                !(docRect.height > 0)) {
+                throw new PdfError('backend-failure', `Doc rect must be finite and have positive extent, got ` +
+                    `${docRect.width}x${docRect.height} at ` +
+                    `(${docRect.x}, ${docRect.y}).`);
+            }
+            // At least one pixel: a sub-pixel rect is a legitimate ask at low zoom,
+            // and a zero-sized bitmap is not a thing PDFium (or Skia) accepts.
+            const width = Math.max(1, Math.round(docRect.width * scale));
+            const height = Math.max(1, Math.round(docRect.height * scale));
+            // See the header: the negation of the ROUNDED origin, not the rounding of
+            // the negated one.
+            const startX = -Math.round(docRect.x * scale);
+            const startY = -Math.round(docRect.y * scale);
+            const pageWidth = Math.round(geometry.width * scale);
+            const pageHeight = Math.round(geometry.height * scale);
+            if (width * height > MAX_INT32 / 4 ||
+                pageWidth > MAX_INT32 ||
+                pageHeight > MAX_INT32) {
+                throw new PdfError('out-of-memory', `A ${width}x${height} raster of a ${pageWidth}x${pageHeight} page ` +
+                    'cannot be expressed in PDFium’s 32-bit ints. Lower ' +
+                    '`RasterPolicy.maxPieceDimension` or `maxRasterPixels`.');
+            }
+            const bitmap = api.FPDFBitmap_CreateEx(width, height, FPDF_BITMAP_BGRA, 0, 0);
+            if (bitmap === 0) {
+                throw new PdfError('out-of-memory', `PDFium could not allocate a ${width}x${height} bitmap ` +
+                    `(${width * height * 4} bytes).`);
+            }
+            try {
+                // BEFORE THE RENDER, ALWAYS, AND NOT OPTIONAL. PDFium composites onto
+                // the destination and never clears it; a freshly allocated buffer is
+                // transparent black, which under the app's annotation layers reads as a
+                // BLACK page rather than a blank one. Ingest cannot repair this — it
+                // has no way to tell "the PDF painted black here" from "nothing painted
+                // here".
+                // The return is CHECKED, not discarded: the comment above says the fill
+                // is not optional, and a silently-failed fill is exactly the failure it
+                // describes — a black page that ingest cannot tell from painted black.
+                const filled = api.FPDFBitmap_FillRect(bitmap, 0, 0, width, height, request.background === 'white' ? OPAQUE_WHITE : TRANSPARENT);
+                if (!filled) {
+                    throw new PdfError('backend-failure', `PDFium refused to clear the ${width}x${height} destination ` +
+                        `bitmap before rendering page ${request.page}. Rendering into it ` +
+                        'would composite onto uninitialised memory.');
+                }
+                const page = loadPage(request.page);
+                api.FPDF_RenderPageBitmap(bitmap, page, startX, startY, pageWidth, pageHeight, 
+                // Device rotation, NOT the page's `/Rotate`. PDFium applies the
+                // page's own rotation itself, and `geometry` is already post-rotation
+                // — passing anything but 0 here would rotate a second time.
+                0, FPDF_REVERSE_BYTE_ORDER | (request.annotations ? FPDF_ANNOT : 0));
+                // READ, NEVER ASSUMED. Measured tight (`width * 4`) at 1, 3, 7, 13, 1023
+                // and 1025 px — but "tight today" is not "tight always", and a wrong
+                // stride shears the image instead of failing.
+                const rowBytes = api.FPDFBitmap_GetStride(bitmap);
+                const buffer = api.FPDFBitmap_GetBuffer(bitmap);
+                if (buffer === 0 || rowBytes < width * 4) {
+                    throw new PdfError('backend-failure', `PDFium reported an unusable bitmap: buffer ${buffer}, stride ` +
+                        `${rowBytes} for a ${width}px row.`);
+                }
+                // `slice` and not `subarray`: this must LEAVE the WASM heap. A view
+                // would be invalidated by the next allocation (Emscripten replaces
+                // HEAPU8 wholesale when memory grows) and would be neither tight nor
+                // transferable. The copy is the price of getting the pixels out, and
+                // it is the only one — the result owns an exactly-sized ArrayBuffer,
+                // so `isTightBuffer` holds and ingest's `tighten()` has nothing to do.
+                //
+                // The WHOLE stride of the last row, not Skia's `computeByteSize`
+                // minimum. The two are the same for a tight stride (which is every
+                // width measured) and differ only by the final row's padding; carrying
+                // it costs nothing and keeps `bytes[y * rowBytes + …]` in range for
+                // every row, which is how every reader here and in the tests indexes.
+                const bytes = api.heapU8().slice(buffer, buffer + rowBytes * height);
+                return {
+                    bytes,
+                    width,
+                    height,
+                    rowBytes,
+                    format: PDFIUM_FORMAT,
+                    alpha: PDFIUM_ALPHA,
+                };
+            }
+            finally {
+                api.FPDFBitmap_Destroy(bitmap);
+            }
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            releasePage();
+            api.FPDF_CloseDocument(document);
+            // AFTER the close, never before: PDFium reads this buffer for the whole
+            // life of the document.
+            api.free(dataPointer);
+        },
+    };
+}

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

@@ -0,0 +1,26 @@
+/**
+ * The web backend's MAIN-THREAD surface.
+ *
+ * `./worker.ts` is deliberately NOT re-exported. It is an ENTRY POINT, not a
+ * module a host imports for its values — it binds itself to `self` at
+ * evaluation, and it is the only file that names `@embedpdf/pdfium`, so pulling
+ * it in here would drag an optional peer into every web bundle that merely
+ * touches the rasterizer registry. It is reached through the package's
+ * `./worker` subpath, by a bundler, as a worker.
+ *
+ * `./engine.ts` and `./session.ts` are re-exported because they are the seam a
+ * different host might want: a caller who already owns a PDFium module (a
+ * Node-side thumbnail service, an Electron main process) can drive
+ * `openPdfiumDocument` directly with no worker at all, which is exactly what the
+ * tests do.
+ */
+export { createWebRasterizer } from './client.js';
+export type { WebRasterizerOptions, WorkerLike } from './client.js';
+export { openPdfiumDocument } from './engine.js';
+export type { PdfiumDocument, PdfiumRasterBytes } from './engine.js';
+export { bindPdfium, loadError, mapLoadError, FPDF_ANNOT, FPDF_BITMAP_BGRA, FPDF_REVERSE_BYTE_ORDER, PDFIUM_ERR, } from './pdfium.js';
+export type { PdfiumBinding, PdfiumHeap, PdfiumWasmModule } from './pdfium.js';
+export { createWorkerSession } from './session.js';
+export type { FetchLike, FetchResponseLike, WorkerSession, WorkerSessionDeps, } from './session.js';
+export { isWorkerResponse } from './protocol.js';
+export type { CancelRequest, CloseRequest, ErrorResponse, OpenRequest, OpenedResponse, PdfiumDocumentSource, PdfiumWasmSource, RenderRequest, RenderedResponse, WorkerRequest, WorkerResponse, } from './protocol.js';

package/dist/rasterizer/web/index.js

@@ -0,0 +1,21 @@
+/**
+ * The web backend's MAIN-THREAD surface.
+ *
+ * `./worker.ts` is deliberately NOT re-exported. It is an ENTRY POINT, not a
+ * module a host imports for its values — it binds itself to `self` at
+ * evaluation, and it is the only file that names `@embedpdf/pdfium`, so pulling
+ * it in here would drag an optional peer into every web bundle that merely
+ * touches the rasterizer registry. It is reached through the package's
+ * `./worker` subpath, by a bundler, as a worker.
+ *
+ * `./engine.ts` and `./session.ts` are re-exported because they are the seam a
+ * different host might want: a caller who already owns a PDFium module (a
+ * Node-side thumbnail service, an Electron main process) can drive
+ * `openPdfiumDocument` directly with no worker at all, which is exactly what the
+ * tests do.
+ */
+export { createWebRasterizer } from './client.js';
+export { openPdfiumDocument } from './engine.js';
+export { bindPdfium, loadError, mapLoadError, FPDF_ANNOT, FPDF_BITMAP_BGRA, FPDF_REVERSE_BYTE_ORDER, PDFIUM_ERR, } from './pdfium.js';
+export { createWorkerSession } from './session.js';
+export { isWorkerResponse } from './protocol.js';

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

@@ -0,0 +1,213 @@
+/**
+ * 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';
+import type { PdfErrorCode } from '../../types.js';
+/**
+ * `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 declare const FPDF_BITMAP_BGRA = 4;
+/** Draw PDF-embedded annotations. Answers `RasterRequest.annotations`. */
+export declare const FPDF_ANNOT = 1;
+/**
+ * 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 declare const FPDF_REVERSE_BYTE_ORDER = 16;
+/**
+ * `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 declare const PDFIUM_ERR: {
+    readonly SUCCESS: 0;
+    readonly UNKNOWN: 1;
+    readonly FILE: 2;
+    readonly FORMAT: 3;
+    readonly PASSWORD: 4;
+    readonly SECURITY: 5;
+    readonly PAGE: 6;
+};
+/**
+ * The WASM heap, reached through FUNCTIONS rather than a captured view.
+ *
+ * `heapU8()` is a call and must stay one. Emscripten REPLACES `Module.HEAPU8`
+ * whenever the heap grows, so a reference captured at bind time detaches the
+ * moment a large bitmap is allocated and every read after that is out of a dead
+ * buffer. This is the single easiest way to write a web PDF backend that works
+ * on small documents and silently produces garbage on big ones.
+ */
+export interface PdfiumHeap {
+    heapU8(): Uint8Array;
+    malloc(byteLength: number): number;
+    free(pointer: number): void;
+    /** Reads an `FS_SIZEF` component — PDFium's float32. */
+    getFloat(pointer: number): number;
+}
+/**
+ * Exactly the PDFium entry points this backend calls. Nothing speculative:
+ * text, search, links and form filling are all absent because none of them is
+ * implemented, and `RasterizerCapabilities` says so.
+ */
+export interface PdfiumBinding extends PdfiumHeap {
+    /**
+     * Does NOT copy — the buffer must stay allocated and untouched for the whole
+     * life of the document. `./engine.ts` owns that lifetime and frees the
+     * pointer in `close()`.
+     */
+    FPDF_LoadMemDocument(dataPointer: number, byteLength: number, password: string): number;
+    FPDF_CloseDocument(document: number): void;
+    FPDF_GetLastError(): number;
+    FPDF_GetPageCount(document: number): number;
+    /**
+     * Writes an `FS_SIZEF` (two float32s) and does NOT parse the page's content
+     * stream — PDFium builds a bare `CPDF_Page` from the page dictionary and reads
+     * its dimensions. That is what makes `RasterizerHandle.pageGeometry`
+     * synchronous and cheap: every page is measured once at open.
+     *
+     * MEASURED, and it is the whole reason `/Rotate` needs no arithmetic here: for
+     * a 200x100 MediaBox with `/Rotate 90` it reports 100x200, and for a 280x360
+     * CropBox with `/Rotate 270` it reports 360x280. CropBox, intersected with
+     * MediaBox, AFTER rotation — which is precisely what `PageGeometry.width` and
+     * `.height` are defined as.
+     *
+     * Contrast `EPDF_GetPageSizeByIndexNormalized`, which sounds like the one you
+     * want and is the opposite: it normalises the rotation AWAY and reports
+     * 200x100 for the same rotated page.
+     */
+    FPDF_GetPageSizeByIndexF(document: number, index: number, sizeOut: number): boolean;
+    /**
+     * `@embedpdf/pdfium`'s extension. Returns PDFium's rotation INDEX — 0, 1, 2 or
+     * 3 for 0/90/180/270 — or -1 for an index the document does not have
+     * (measured). The plain `FPDFPage_GetRotation` would need a loaded page, which
+     * is exactly what `pageGeometry` is forbidden to do.
+     */
+    EPDF_GetPageRotationByIndex(document: number, index: number): number;
+    FPDF_LoadPage(document: number, index: number): number;
+    FPDF_ClosePage(page: number): void;
+    /**
+     * `firstScan: 0` lets PDFium allocate; `stride: 0` lets it choose. Returns 0
+     * when the allocation fails, which is the only out-of-memory signal there is
+     * (measured: a 100000x100000 request returns 0 rather than throwing).
+     */
+    FPDFBitmap_CreateEx(width: number, height: number, format: number, firstScan: number, stride: number): number;
+    FPDFBitmap_Destroy(bitmap: number): void;
+    /** `color` is ARGB, so 0xFFFFFFFF is opaque white and 0 is transparent. */
+    FPDFBitmap_FillRect(bitmap: number, left: number, top: number, width: number, height: number, color: number): boolean;
+    FPDFBitmap_GetBuffer(bitmap: number): number;
+    FPDFBitmap_GetStride(bitmap: number): number;
+    FPDF_RenderPageBitmap(bitmap: number, page: number, startX: number, startY: number, sizeX: number, sizeY: number, rotate: number, flags: number): void;
+}
+/**
+ * The shape of `@embedpdf/pdfium`'s `WrappedPdfiumModule`, restated as the
+ * subset this package touches.
+ *
+ * `PdfiumRuntimeMethods.wasmExports` is where `malloc` / `free` live; the FPDF_*
+ * entries are `cwrap`ped onto the wrapper object itself.
+ */
+export interface PdfiumWasmModule {
+    pdfium: {
+        HEAPU8: Uint8Array;
+        /**
+         * `number | bigint` because Emscripten's `getValue` reads `i64` too. This
+         * backend only ever asks for `'float'`, so the bigint arm is unreachable —
+         * but the declaration is the real one, and `bindPdfium` narrows rather than
+         * asserting. (This is the drift check working: the first hand-written
+         * signature said `number`, and `tsc` refused the real module.)
+         */
+        getValue(pointer: number, type: string): number | bigint;
+        wasmExports: {
+            malloc(byteLength: number): number;
+            free(pointer: number): void;
+        };
+    };
+    /** Initialises the library. Must be called once before anything else. */
+    PDFiumExt_Init(): null;
+    FPDF_LoadMemDocument(dataPointer: number, byteLength: number, password: string): number;
+    FPDF_CloseDocument(document: number): null;
+    FPDF_GetLastError(): number;
+    FPDF_GetPageCount(document: number): number;
+    FPDF_GetPageSizeByIndexF(document: number, index: number, sizeOut: number): boolean;
+    EPDF_GetPageRotationByIndex(document: number, index: number): number;
+    FPDF_LoadPage(document: number, index: number): number;
+    FPDF_ClosePage(page: number): null;
+    FPDFBitmap_CreateEx(width: number, height: number, format: number, firstScan: number, stride: number): number;
+    FPDFBitmap_Destroy(bitmap: number): null;
+    FPDFBitmap_FillRect(bitmap: number, left: number, top: number, width: number, height: number, color: number): boolean;
+    FPDFBitmap_GetBuffer(bitmap: number): number;
+    FPDFBitmap_GetStride(bitmap: number): number;
+    FPDF_RenderPageBitmap(bitmap: number, page: number, startX: number, startY: number, sizeX: number, sizeY: number, rotate: number, flags: number): null;
+}
+/**
+ * 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 declare function bindPdfium(module: PdfiumWasmModule): PdfiumBinding;
+/**
+ * `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 declare function mapLoadError(error: number, passwordSupplied: boolean): PdfErrorCode;
+/** The load failure, as the error a host can branch on. */
+export declare function loadError(error: number, passwordSupplied: boolean): PdfError;