@reekon-tools/react-native-pdf-canvas 0.2.1 → 0.4.0

package/dist/rasterizer/web/pdfium.js

@@ -48,6 +48,9 @@ import { PdfError } from '../../types.js';
 export const FPDF_BITMAP_BGRA = 4;
 /** Draw PDF-embedded annotations. Answers `RasterRequest.annotations`. */
 export const FPDF_ANNOT = 0x01;
+/** `FPDFText_FindStart` flags. Answer `TextSearchRequest.matchCase` / `.wholeWord`. */
+export const FPDF_MATCHCASE = 0x01;
+export const FPDF_MATCHWHOLEWORD = 0x02;
 /**
  * Write RGBA instead of BGRA.
  *
@@ -96,6 +99,8 @@ export function bindPdfium(module) {
         malloc: byteLength => pdfium.wasmExports.malloc(byteLength),
         free: pointer => pdfium.wasmExports.free(pointer),
         getFloat: pointer => Number(pdfium.getValue(pointer, 'float')),
+        getDouble: pointer => Number(pdfium.getValue(pointer, 'double')),
+        getInt32: pointer => Number(pdfium.getValue(pointer, 'i32')),
         FPDF_LoadMemDocument: (pointer, byteLength, password) => module.FPDF_LoadMemDocument(pointer, byteLength, password),
         FPDF_CloseDocument: document => {
             module.FPDF_CloseDocument(document);
@@ -118,6 +123,22 @@ export function bindPdfium(module) {
         FPDF_RenderPageBitmap: (bitmap, page, startX, startY, sizeX, sizeY, rotate, flags) => {
             module.FPDF_RenderPageBitmap(bitmap, page, startX, startY, sizeX, sizeY, rotate, flags);
         },
+        FPDF_PageToDevice: (page, startX, startY, sizeX, sizeY, rotate, pageX, pageY, deviceXOut, deviceYOut) => module.FPDF_PageToDevice(page, startX, startY, sizeX, sizeY, rotate, pageX, pageY, deviceXOut, deviceYOut),
+        FPDFText_LoadPage: page => module.FPDFText_LoadPage(page),
+        FPDFText_ClosePage: textPage => {
+            module.FPDFText_ClosePage(textPage);
+        },
+        FPDFText_CountChars: textPage => module.FPDFText_CountChars(textPage),
+        FPDFText_GetText: (textPage, startIndex, count, buffer) => module.FPDFText_GetText(textPage, startIndex, count, buffer),
+        FPDFText_FindStart: (textPage, findWhat, flags, startIndex) => module.FPDFText_FindStart(textPage, findWhat, flags, startIndex),
+        FPDFText_FindNext: handle => module.FPDFText_FindNext(handle),
+        FPDFText_FindClose: handle => {
+            module.FPDFText_FindClose(handle);
+        },
+        FPDFText_GetSchResultIndex: handle => module.FPDFText_GetSchResultIndex(handle),
+        FPDFText_GetSchCount: handle => module.FPDFText_GetSchCount(handle),
+        FPDFText_CountRects: (textPage, startIndex, count) => module.FPDFText_CountRects(textPage, startIndex, count),
+        FPDFText_GetRect: (textPage, rectIndex, leftOut, topOut, rightOut, bottomOut) => module.FPDFText_GetRect(textPage, rectIndex, leftOut, topOut, rightOut, bottomOut),
     };
 }
 /* ------------------------------------------------------------------ *

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

@@ -21,7 +21,7 @@
  * 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';
+import type { AlphaEncoding, PageGeometry, PdfErrorCode, PixelFormat, RasterRequest, TextMatch, TextSearchRequest } from '../../types.js';
 /**
  * Where the worker gets `pdfium.wasm`.
  *
@@ -65,11 +65,22 @@ export interface RenderRequest {
     request: RasterRequest;
 }
 /**
- * Drop a render that has not started yet.
+ * Find text on one page. Routed exactly as a render is — the same queue, the
+ * same yield, the same `cancel` by id — so a search never overtakes a render
+ * that was posted before it and a superseded search can still be dropped
+ * before it starts.
+ */
+export interface SearchRequest {
+    kind: 'search';
+    id: number;
+    request: TextSearchRequest;
+}
+/**
+ * Drop a render or a search 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
+ * `cancel` can only ever be delivered BETWEEN jobs — never into one. What it
+ * genuinely does is stop a QUEUED job 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.
@@ -94,7 +105,7 @@ export interface CancelRequest {
 export interface CloseRequest {
     kind: 'close';
 }
-export type WorkerRequest = OpenRequest | RenderRequest | CancelRequest | CloseRequest;
+export type WorkerRequest = OpenRequest | RenderRequest | SearchRequest | CancelRequest | CloseRequest;
 export interface OpenedResponse {
     kind: 'opened';
     id: number;
@@ -119,6 +130,12 @@ export interface RenderedResponse {
      */
     alpha: AlphaEncoding;
 }
+/** Plain data, structured-cloned whole: `DocRect`s and strings. */
+export interface SearchedResponse {
+    kind: 'searched';
+    id: number;
+    matches: TextMatch[];
+}
 export interface ErrorResponse {
     kind: 'error';
     /** Null for a failure that belongs to no single request. */
@@ -126,7 +143,7 @@ export interface ErrorResponse {
     code: PdfErrorCode;
     message: string;
 }
-export type WorkerResponse = OpenedResponse | RenderedResponse | ErrorResponse;
+export type WorkerResponse = OpenedResponse | RenderedResponse | SearchedResponse | ErrorResponse;
 /**
  * Is this a message from our worker?
  *

package/dist/rasterizer/web/protocol.js

@@ -33,5 +33,8 @@ export function isWorkerResponse(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const kind = value.kind;
-    return kind === 'opened' || kind === 'rendered' || kind === 'error';
+    return (kind === 'opened' ||
+        kind === 'rendered' ||
+        kind === 'searched' ||
+        kind === 'error');
 }

package/dist/rasterizer/web/session.js

@@ -180,6 +180,13 @@ export function createWorkerSession(deps) {
     let opening = null;
     let document = null;
     let disposed = false;
+    /**
+     * Renders AND searches, one queue. A search is a synchronous PDFium call
+     * like a render, wants the same between-jobs cancel window, and must not
+     * overtake a render posted before it — a page's text is parsed from the
+     * same loaded page the render uses, so keeping them in order keeps the
+     * engine's one-page cache hot for both.
+     */
     const queue = [];
     /**
      * Ids the main thread has given up on.
@@ -286,18 +293,27 @@ export function createWorkerSession(deps) {
                     if (cancelled.delete(job.id))
                         continue;
                     try {
-                        const raster = target.render(job.request);
-                        const buffer = raster.bytes.buffer;
-                        deps.post({
-                            kind: 'rendered',
-                            id: job.id,
-                            bytes: buffer,
-                            width: raster.width,
-                            height: raster.height,
-                            rowBytes: raster.rowBytes,
-                            format: raster.format,
-                            alpha: raster.alpha,
-                        }, [buffer]);
+                        if (job.kind === 'search') {
+                            deps.post({
+                                kind: 'searched',
+                                id: job.id,
+                                matches: target.search(job.request),
+                            });
+                        }
+                        else {
+                            const raster = target.render(job.request);
+                            const buffer = raster.bytes.buffer;
+                            deps.post({
+                                kind: 'rendered',
+                                id: job.id,
+                                bytes: buffer,
+                                width: raster.width,
+                                height: raster.height,
+                                rowBytes: raster.rowBytes,
+                                format: raster.format,
+                                alpha: raster.alpha,
+                            }, [buffer]);
+                        }
                     }
                     catch (error) {
                         postError(job.id, error);
@@ -387,7 +403,8 @@ export function createWorkerSession(deps) {
                     });
                     return;
                 }
-                case 'render': {
+                case 'render':
+                case 'search': {
                     queue.push(request);
                     void drain();
                     return;

package/dist/react/PdfContentView.js

@@ -158,6 +158,11 @@ export function PdfContentView({ content, zIndex, sampling = 'linear', paperColo
         const out = [];
         if (paperColor != null) {
             for (const page of content.pages) {
+                // A page outside the allow-list holds nothing and gets no paper: in a
+                // stacked layout its sheet would sit at the origin beside the one page
+                // that is meant to show (see PdfPageContent.drawable).
+                if (!page.drawable)
+                    continue;
                 const { pageRect } = page;
                 out.push(_jsx(Rect, { x: pageRect.x, y: pageRect.y, width: pageRect.width, height: pageRect.height, color: paperColor }, `paper:${page.page}`));
             }

package/dist/react/usePdfDocument.d.ts

@@ -16,7 +16,7 @@
  */
 import type { SkImage } from '@shopify/react-native-skia';
 import { PdfError } from '../types.js';
-import type { DocRect, DocSize, PageGeometry, PageRasterizer, PdfSource, PixelSize, RasterPixels, RasterizerCapabilities, RasterizerHandle } from '../types.js';
+import type { DocRect, DocSize, PageGeometry, PageRasterizer, PageRotation, PdfSource, PixelSize, RasterPixels, RasterizerCapabilities, RasterizerHandle, TextMatch, TextSearchOptions } from '../types.js';
 /** Install the rasterizer used when `usePdfDocument` / `openPdfDocument` are not
  * given one explicitly. Returns the previous value so a test can restore it. */
 export declare function setDefaultRasterizer(rasterizer: PageRasterizer | null): PageRasterizer | null;
@@ -61,6 +61,16 @@ export interface PdfRenderOptions {
      * compositing onto their own surface.
      */
     background?: 'white' | 'transparent';
+    /**
+     * Turn the page this many degrees clockwise on top of its own `/Rotate`.
+     *
+     * Defaults to 0. For 90 and 270 the default `docRect` — and therefore the
+     * raster — has the page's extents SWAPPED, and a `docRect` you pass yourself
+     * is read in that turned space (see `RasterRequest.rotation`). `widthPx` is
+     * the width of the turned raster. This is what a thumbnail strip passes so
+     * its tiles match a layer the host has rotated.
+     */
+    rotation?: PageRotation;
     signal?: AbortSignal;
 }
 export interface PdfDocument {
@@ -73,7 +83,22 @@ export interface PdfDocument {
     /** Intrinsic sizes of every page, in the order a `PdfPageLayout` expects. */
     pageSizes(): DocSize[];
     renderPage(index: number, options?: PdfRenderOptions): Promise<PdfPageRender>;
-    /** True once `close()` has run. Every further call rejects with `cancelled`. */
+    /**
+     * Every occurrence of `query` on one page, in reading order.
+     *
+     * `TextMatch.rects` are in the page's doc space — PDF points, origin at the
+     * DISPLAYED page's top-left, y down — with `options.rotation` applied, so
+     * pass the same rotation the page's layer or `renderPage` uses and a hit
+     * drawn at a rect lands on the glyphs. An empty or whitespace-only query
+     * resolves `[]` without asking the backend. Rejects `backend-failure` for a
+     * page index out of range or a closed document, `cancelled` when
+     * `options.signal` aborts.
+     */
+    searchPage(page: number, query: string, options?: TextSearchOptions): Promise<TextMatch[]>;
+    /**
+     * True once `close()` has run. Every further `renderPage` rejects with
+     * `cancelled`, every further `searchPage` with `backend-failure`.
+     */
     readonly closed: boolean;
     /**
      * Release the underlying file handle. `usePdfDocument` owns this for documents

package/dist/react/usePdfDocument.js

@@ -17,6 +17,7 @@
 import { useEffect, useState } from 'react';
 // Through the `./skia` barrel — see the note in `usePdfLayer.ts`.
 import { imageFromPixels } from '../skia/index.js';
+import { rotatedSize } from '../rotation.js';
 import { PdfError } from '../types.js';
 /* ------------------------------------------------------------------ *
  * Default rasterizer registry
@@ -145,11 +146,15 @@ export async function openPdfDocument(source, rasterizer) {
                 throw new PdfError('cancelled', 'renderPage aborted before it started');
             }
             const geometry = handle.pageGeometry(index);
+            const rotation = options?.rotation ?? 0;
+            // The whole page in the TURNED page's doc space: a 612x792 page at 90 is
+            // a 792x612 raster, and a caller's `widthPx` is the width of that.
+            const turned = rotatedSize(geometry, rotation);
             const docRect = options?.docRect ?? {
                 x: 0,
                 y: 0,
-                width: geometry.width,
-                height: geometry.height,
+                width: turned.width,
+                height: turned.height,
             };
             if (!(docRect.width > 0) || !(docRect.height > 0)) {
                 throw new PdfError('backend-failure', `renderPage needs a positive docRect, got ${docRect.width}x${docRect.height}`);
@@ -161,18 +166,22 @@ export async function openPdfDocument(source, rasterizer) {
             if (!(scale > 0) || !Number.isFinite(scale)) {
                 throw new PdfError('backend-failure', `renderPage needs a positive scale, got ${scale}`);
             }
+            const request = {
+                page: index,
+                docRect,
+                scale,
+                // A backend that cannot draw annotations would otherwise silently
+                // ignore the flag; downgrading here keeps the request honest.
+                annotations: (options?.annotations ?? true) && backend.capabilities.annotations,
+                background: options?.background ?? 'white',
+            };
+            // Only when the caller asked for a turn: an unrotated request stays the
+            // request it always was, key for key (see the controller's stamp).
+            if (rotation !== 0)
+                request.rotation = rotation;
             let pixels;
             try {
-                pixels = await handle.render({
-                    page: index,
-                    docRect,
-                    scale,
-                    // A backend that cannot draw annotations would otherwise silently
-                    // ignore the flag; downgrading here keeps the request honest.
-                    annotations: (options?.annotations ?? true) &&
-                        backend.capabilities.annotations,
-                    background: options?.background ?? 'white',
-                }, options?.signal);
+                pixels = await handle.render(request, options?.signal);
             }
             catch (cause) {
                 throw toPdfError(cause, `Failed to render page ${index}`);
@@ -201,6 +210,50 @@ export async function openPdfDocument(source, rasterizer) {
                 },
             };
         },
+        async searchPage(page, query, options) {
+            // `backend-failure`, not `renderPage`'s `cancelled`: nothing was
+            // superseded — the caller asked a closed document a question, which is
+            // a bug in the caller, and "cancelled" is the one code a host is
+            // expected to swallow silently.
+            if (closed) {
+                throw new PdfError('backend-failure', 'searchPage called on a closed PdfDocument');
+            }
+            if (!Number.isInteger(page) || page < 0 || page >= handle.pageCount) {
+                throw new PdfError('backend-failure', `page index ${page} is out of range (pageCount ${handle.pageCount})`);
+            }
+            // Nothing to find, and every engine would either refuse the query or
+            // answer it with nothing — so neither is asked. This is also what makes
+            // a find box that clears itself free.
+            if (query.trim().length === 0) {
+                return [];
+            }
+            if (isAborted(options?.signal)) {
+                throw new PdfError('cancelled', 'searchPage aborted before it started');
+            }
+            // RESOLVED HERE, once, for every backend: a backend is handed the three
+            // options with no defaults of its own left to drift.
+            const request = {
+                page,
+                query,
+                matchCase: options?.matchCase ?? false,
+                wholeWord: options?.wholeWord ?? false,
+                rotation: options?.rotation ?? 0,
+            };
+            let matches;
+            try {
+                matches = await handle.searchText(request, options?.signal);
+            }
+            catch (cause) {
+                throw toPdfError(cause, `Failed to search page ${page}`);
+            }
+            // A backend that answered anyway — the web worker cannot interrupt a
+            // search it has started — must not hand hits to a caller that already
+            // moved on to the next keystroke.
+            if (isAborted(options?.signal)) {
+                throw new PdfError('cancelled', 'searchPage aborted');
+            }
+            return matches;
+        },
         close() {
             if (closed) {
                 return;

package/dist/react/usePdfLayer.d.ts

@@ -20,7 +20,7 @@
  * host's transform does the panning and zooming; this hook only ever hears about
  * the viewport through the `controller` methods the host calls.
  */
-import type { PdfContent, PdfController, PdfDiagnostic, PdfPageLayout, RasterPolicy } from '../types.js';
+import type { PageRotation, PdfContent, PdfController, PdfDiagnostic, PdfPageLayout, RasterPolicy } from '../types.js';
 import type { PdfDocument } from './usePdfDocument.js';
 /**
  * Only the pages the viewport actually intersects may hold rasters.
@@ -88,6 +88,23 @@ export interface UsePdfLayerOptions {
      * and its raster cache: every cached tile was rendered one way or the other.
      */
     annotations?: boolean;
+    /**
+     * A per-page rotation the HOST applies on top of the document's own
+     * `/Rotate`, in degrees clockwise, indexed by page. A missing or undefined
+     * entry is 0; absent altogether, nothing about the layer changes.
+     *
+     * The layout is handed the ROTATED page sizes (a 612x792 page turned 90 is
+     * laid out as 792x612), the controller is handed geometry in the same
+     * orientation, and every tile request carries the rotation so the backend
+     * draws the page turned. Doc space is therefore the rotated page's: a host
+     * positioning its own layers over a turned page positions them in that
+     * space, and `content.pages[i].pageRect` already reports it.
+     *
+     * Changing an entry REBUILDS the controller and clears its raster cache —
+     * every cached tile was drawn one way up — exactly as `annotations` does. An
+     * all-zero list is the same controller as no list at all.
+     */
+    rotations?: readonly PageRotation[];
     onDiagnostic?: (diagnostic: PdfDiagnostic) => void;
 }
 export interface PdfLayer {
@@ -100,4 +117,4 @@ export interface PdfLayer {
      */
     controller: PdfController;
 }
-export declare function usePdfLayer({ document, pages: pageSelection, layout, policy, annotations, onDiagnostic, }: UsePdfLayerOptions): PdfLayer;
+export declare function usePdfLayer({ document, pages: pageSelection, layout, policy, annotations, rotations, onDiagnostic, }: UsePdfLayerOptions): PdfLayer;

package/dist/react/usePdfLayer.js

@@ -25,6 +25,7 @@ import { createRasterCache } from '../cache.js';
 import { createPdfController } from '../controller.js';
 import { continuousVertical, hasOverlappingPages } from '../layout.js';
 import { resolvePolicy } from '../policy.js';
+import { resolveRotations, rotatePageGeometry } from '../rotation.js';
 // Through the `./skia` barrel, not `../rasterizer/ingest.js` directly: that
 // barrel is the documented home of the ingest seam, and routing every internal
 // consumer through it is what keeps "which modules can touch Skia" a list of one
@@ -116,11 +117,17 @@ function disposeRaster(raster) {
     disposedImages.add(raster.image);
     raster.image.dispose();
 }
-/** Intrinsic geometry for every page, in page order. Cheap: loads no page. */
-function allPageGeometry(document) {
+/**
+ * Geometry for every page, in page order, as the host wants it displayed: a
+ * quarter turn swaps a page's extents (see `../rotation.ts`). Cheap: loads no
+ * page. With no rotations it is the intrinsic geometry exactly, object for
+ * object — `rotatePageGeometry` returns its input for a rotation that changes
+ * nothing.
+ */
+function rotatedPageGeometry(document, rotations) {
     const geometry = [];
     for (let index = 0; index < document.pageCount; index += 1) {
-        geometry.push(document.pageGeometry(index));
+        geometry.push(rotatePageGeometry(document.pageGeometry(index), rotations?.[index] ?? 0));
     }
     return geometry;
 }
@@ -181,7 +188,7 @@ export function usePdfLayer({ document,
 // The PUBLIC name stays `pages`; locally it is the SELECTION, and the
 // controller's own `pages` is the per-page geometry. Two very different things
 // one rename apart.
-pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, annotations = true, onDiagnostic, }) {
+pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, annotations = true, rotations, onDiagnostic, }) {
     // The diagnostic callback is almost always an inline arrow. Route it through a
     // ref so a fresh identity on every render never counts as a reason to rebuild
     // the controller.
@@ -194,14 +201,41 @@ pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, annotations = tru
     }, []);
     const pagesKey = pageSelectionKey(pageSelection);
     const policySignature = policyKey(policy);
+    /**
+     * Normalised every render — the option is an inline literal at every
+     * realistic call site, so its identity means nothing — and its joined form
+     * is the structural key the memos below depend on instead. `undefined` for
+     * an absent AND an all-zero list, so neither spelling of "nothing turned"
+     * can tear the controller down (see `resolveRotations`).
+     */
+    const resolvedRotations = resolveRotations(rotations, document?.pageCount ?? 0);
+    const rotationsSignature = resolvedRotations?.join(',') ?? '';
+    /**
+     * Every page's geometry as the host wants it shown. What the layout sizes
+     * pages from and what the controller divides page rects by, so the two are
+     * derived from ONE array and cannot disagree about a page's orientation.
+     */
+    const pageGeometry = useMemo(() => document === null
+        ? null
+        : rotatedPageGeometry(document, resolvedRotations), 
+    // `resolvedRotations` is rebuilt every render; its signature is a complete
+    // description of it and stands in — the same trade `policy` makes below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [document, rotationsSignature]);
     /**
      * Split out of the controller memo so the `__DEV__` check below can see the
      * rects without re-running the layout, and so a warning lives in an EFFECT
      * rather than inside a memo React is free to invoke twice.
      */
-    const pageRects = useMemo(() => document === null
+    const pageRects = useMemo(() => pageGeometry === null
         ? null
-        : (layout ?? DEFAULT_LAYOUT)(document.pageSizes()), [document, layout]);
+        : (layout ?? DEFAULT_LAYOUT)(
+        // The ROTATED sizes: a page the host turned a quarter is laid out
+        // at its displayed extents, and doc space is that page's.
+        pageGeometry.map(page => ({
+            width: page.width,
+            height: page.height,
+        }))), [pageGeometry, layout]);
     /**
      * A stacked layout (`singlePage()`) is correct ONLY with a one-element `pages`
      * list. Any other selection lets every page hold a base at the same doc rect,
@@ -234,7 +268,7 @@ pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, annotations = tru
             'continuousVertical() / spread().');
     }, [document, pageRects, pageSelection]);
     const layer = useMemo(() => {
-        if (document === null || pageRects === null) {
+        if (document === null || pageGeometry === null || pageRects === null) {
             return null;
         }
         const resolvedPolicy = resolvePolicy(policy);
@@ -245,7 +279,11 @@ pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, annotations = tru
         const controller = createPdfController({
             handle: document.handle,
             pageRects,
-            pages: allPageGeometry(document),
+            pages: pageGeometry,
+            // Undefined when nothing is turned, so the controller's default path
+            // — and the requests it builds — are exactly what they were before
+            // rotation existed.
+            rotations: resolvedRotations,
             policy: resolvedPolicy,
             ingest: ingestRaster,
             cache,
@@ -277,12 +315,17 @@ pages: pageSelection = DEFAULT_PAGE_SELECTION, layout, policy, annotations = tru
     // layout the resident cost goes from one page to as many as five. The measured
     // cost of the teardown is one page's rasters, which is the page you are turning
     // to and would have paid for anyway. See `__tests__/single-page.test.ts`.
+    //
+    // `rotations` follows the same rule as the two above: `rotationsSignature`
+    // stands in for it, and `resolvedRotations` is read inside on its strength.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
         document,
+        pageGeometry,
         pageRects,
         pagesKey,
         policySignature,
+        rotationsSignature,
         annotations,
         emitDiagnostic,
     ]);

package/dist/rotation.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The HOST's page rotation, and the one place its arithmetic lives.
+ *
+ * Two rotations exist in this package and they must not be confused:
+ *
+ *  - `PageGeometry.rotation` is the document's own `/Rotate`. PDFium folds it
+ *    into every size it reports and every render it draws, so from this
+ *    package's vantage point it is already applied and purely informational.
+ *  - `RasterRequest.rotation` — what this module is about — is a rotation the
+ *    host layers ON TOP of that: "show me this page turned a quarter
+ *    clockwise". It is PDFium's `rotate` argument, which every engine here
+ *    hard-coded to 0 until this existed.
+ *
+ * THE CONTRACT, stated once and honoured by every backend: doc space for a
+ * rotated page is the ROTATED page's. A 612x792 page turned 90 is a 792x612
+ * page whose origin is its displayed top-left, and a request's `docRect` and
+ * `scale` are in that space. So the layout lays out swapped sizes, the planner
+ * plans in them, the controller divides swapped page rects by swapped geometry
+ * (and `layoutScale` stays 1), and a backend keeps its negative-offset rect
+ * mechanism unchanged — the only thing it swaps is the page box it hands the
+ * engine. This module does the swapping; nothing else in `src/` repeats it.
+ *
+ * Pure, and deliberately without React: `usePdfLayer` calls it, and so does the
+ * test that pins what the layout is handed.
+ */
+import type { DocSize, PageGeometry, PageRotation } from './types.js';
+export declare const ROTATIONS: readonly PageRotation[];
+/**
+ * True for exactly the four values the type admits. For a value that arrived
+ * from JavaScript rather than through the type — a backend validating a request
+ * it did not build.
+ */
+export declare function isPageRotation(value: unknown): value is PageRotation;
+/** A quarter turn either way swaps a page's extents; a half turn does not. */
+export declare function swapsExtents(rotation: PageRotation): boolean;
+/** A page's size as displayed under `rotation`. */
+export declare function rotatedSize(size: DocSize, rotation: PageRotation): DocSize;
+/**
+ * The geometry the controller and the layout see for a page a host has turned.
+ *
+ * Returns the SAME object for a rotation that changes nothing, so a document
+ * with no rotations hands downstream exactly the geometry it did before this
+ * existed. `rotation` — the document's `/Rotate` — is carried through
+ * untouched: it describes the file, not the host's view of it.
+ */
+export declare function rotatePageGeometry(geometry: PageGeometry, rotation: PageRotation): PageGeometry;
+/**
+ * A host's `rotations` option, normalised to one entry per page — or
+ * `undefined` when it would change nothing.
+ *
+ * `undefined` for BOTH an absent option and an all-zero list, on purpose: the
+ * two mean the same controller, and `usePdfLayer` keys its controller memo on
+ * the result, so a host toggling between "no rotations" and `[0, 0, 0]` must
+ * not tear its raster cache down over a distinction without a difference. A
+ * value the type does not admit (from JavaScript) reads as 0 rather than
+ * throwing: a malformed entry should leave that page upright, not blank the
+ * document.
+ */
+export declare function resolveRotations(rotations: readonly PageRotation[] | undefined, pageCount: number): PageRotation[] | undefined;

package/dist/rotation.js

@@ -0,0 +1,85 @@
+/**
+ * The HOST's page rotation, and the one place its arithmetic lives.
+ *
+ * Two rotations exist in this package and they must not be confused:
+ *
+ *  - `PageGeometry.rotation` is the document's own `/Rotate`. PDFium folds it
+ *    into every size it reports and every render it draws, so from this
+ *    package's vantage point it is already applied and purely informational.
+ *  - `RasterRequest.rotation` — what this module is about — is a rotation the
+ *    host layers ON TOP of that: "show me this page turned a quarter
+ *    clockwise". It is PDFium's `rotate` argument, which every engine here
+ *    hard-coded to 0 until this existed.
+ *
+ * THE CONTRACT, stated once and honoured by every backend: doc space for a
+ * rotated page is the ROTATED page's. A 612x792 page turned 90 is a 792x612
+ * page whose origin is its displayed top-left, and a request's `docRect` and
+ * `scale` are in that space. So the layout lays out swapped sizes, the planner
+ * plans in them, the controller divides swapped page rects by swapped geometry
+ * (and `layoutScale` stays 1), and a backend keeps its negative-offset rect
+ * mechanism unchanged — the only thing it swaps is the page box it hands the
+ * engine. This module does the swapping; nothing else in `src/` repeats it.
+ *
+ * Pure, and deliberately without React: `usePdfLayer` calls it, and so does the
+ * test that pins what the layout is handed.
+ */
+export const ROTATIONS = Object.freeze([
+    0, 90, 180, 270,
+]);
+/**
+ * True for exactly the four values the type admits. For a value that arrived
+ * from JavaScript rather than through the type — a backend validating a request
+ * it did not build.
+ */
+export function isPageRotation(value) {
+    return ROTATIONS.includes(value);
+}
+/** A quarter turn either way swaps a page's extents; a half turn does not. */
+export function swapsExtents(rotation) {
+    return rotation === 90 || rotation === 270;
+}
+/** A page's size as displayed under `rotation`. */
+export function rotatedSize(size, rotation) {
+    return swapsExtents(rotation)
+        ? { width: size.height, height: size.width }
+        : { width: size.width, height: size.height };
+}
+/**
+ * The geometry the controller and the layout see for a page a host has turned.
+ *
+ * Returns the SAME object for a rotation that changes nothing, so a document
+ * with no rotations hands downstream exactly the geometry it did before this
+ * existed. `rotation` — the document's `/Rotate` — is carried through
+ * untouched: it describes the file, not the host's view of it.
+ */
+export function rotatePageGeometry(geometry, rotation) {
+    if (!swapsExtents(rotation))
+        return geometry;
+    return { ...geometry, width: geometry.height, height: geometry.width };
+}
+/**
+ * A host's `rotations` option, normalised to one entry per page — or
+ * `undefined` when it would change nothing.
+ *
+ * `undefined` for BOTH an absent option and an all-zero list, on purpose: the
+ * two mean the same controller, and `usePdfLayer` keys its controller memo on
+ * the result, so a host toggling between "no rotations" and `[0, 0, 0]` must
+ * not tear its raster cache down over a distinction without a difference. A
+ * value the type does not admit (from JavaScript) reads as 0 rather than
+ * throwing: a malformed entry should leave that page upright, not blank the
+ * document.
+ */
+export function resolveRotations(rotations, pageCount) {
+    if (rotations === undefined)
+        return undefined;
+    const resolved = [];
+    let any = false;
+    for (let page = 0; page < pageCount; page += 1) {
+        const rotation = rotations[page];
+        const clean = isPageRotation(rotation) ? rotation : 0;
+        if (clean !== 0)
+            any = true;
+        resolved.push(clean);
+    }
+    return any ? resolved : undefined;
+}