@reekon-tools/react-native-pdf-canvas 0.2.0 → 0.3.0

package/dist/rasterizer/web/engine.js

@@ -40,6 +40,7 @@
  * likely to be real.
  */
 import { FPDF_ANNOT, FPDF_BITMAP_BGRA, FPDF_REVERSE_BYTE_ORDER, loadError, } from './pdfium.js';
+import { isPageRotation, ROTATIONS, swapsExtents } from '../../rotation.js';
 import { PdfError } from '../../types.js';
 /**
  * MEASURED, not inherited from the other backends. An antialiased opaque-white
@@ -64,7 +65,6 @@ 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
  * ------------------------------------------------------------------ */
@@ -215,6 +215,13 @@ function createDocument(api, document, dataPointer, pages) {
                     `${docRect.width}x${docRect.height} at ` +
                     `(${docRect.x}, ${docRect.y}).`);
             }
+            // Read as `?? 0`, so a request built before the field existed renders
+            // as it always did; validated, because from here on it is arithmetic
+            // and `45 / 90` would silently be "upright".
+            const rotation = request.rotation ?? 0;
+            if (!isPageRotation(rotation)) {
+                throw new PdfError('backend-failure', `Rotation must be 0, 90, 180 or 270, got ${String(rotation)}.`);
+            }
             // 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));
@@ -223,8 +230,18 @@ function createDocument(api, document, dataPointer, pages) {
             // 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);
+            // THE PAGE BOX PDFIUM IS HANDED IS THE DISPLAYED ONE. `size_x` / `size_y`
+            // describe the box the page is drawn INTO after `rotate` is applied —
+            // `CPDF_Page::GetDisplayMatrix` maps the page's HEIGHT onto `size_x` for
+            // rotate 1 and 3 — so a quarter turn swaps the intrinsic extents here.
+            // Without the swap the turned page is squashed into the upright box and
+            // every pixel is stretched; with it, `docRect` (already in the turned
+            // page's space, see `RasterRequest.rotation`) needs nothing: the start
+            // offsets slide the whole turned page exactly as they slide an upright
+            // one.
+            const turned = swapsExtents(rotation);
+            const pageWidth = Math.round((turned ? geometry.height : geometry.width) * scale);
+            const pageHeight = Math.round((turned ? geometry.width : geometry.height) * scale);
             if (width * height > MAX_INT32 / 4 ||
                 pageWidth > MAX_INT32 ||
                 pageHeight > MAX_INT32) {
@@ -255,10 +272,12 @@ function createDocument(api, document, dataPointer, pages) {
                 }
                 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));
+                // The HOST's rotation, in quarter turns clockwise — and never the
+                // page's own `/Rotate`. PDFium has already folded that into
+                // `geometry` and into the render, so passing it here would turn the
+                // page twice; `rotation` is layered on top of it, which is exactly
+                // what this argument exists for.
+                rotation / 90, 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.

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 } 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 {

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}`);

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;
+}

package/dist/types.d.ts

@@ -220,6 +220,26 @@ export interface RasterRequest {
      */
     annotations: boolean;
     background: 'white' | 'transparent';
+    /**
+     * DEVICE rotation applied on top of the page's own `/Rotate`, in degrees
+     * clockwise. Optional: absent means 0, and every backend reads it as
+     * `rotation ?? 0`, so a request built before the field existed renders
+     * exactly as it did.
+     *
+     * THE COORDINATE CONTRACT: `docRect` and `scale` are expressed in the
+     * ROTATED page's doc space. For 90 and 270 the page's extents are swapped —
+     * a 612x792 page rotated 90 is a 792x612 page whose origin is its displayed
+     * top-left — so a whole-page request for it is `{0, 0, 792, 612}`. That is
+     * what lets a backend keep the negative-offset rect mechanism unchanged: it
+     * describes the whole TURNED page at `scale` and slides it by
+     * `(-round(x·s), -round(y·s))`, exactly as it does an upright one. The only
+     * thing a backend swaps is the page box it hands the engine.
+     *
+     * This is NOT `PageGeometry.rotation`. That one is the document's `/Rotate`,
+     * already folded into every size and render by PDFium and informational
+     * here; this one is a host's choice, layered on top. See `./rotation.ts`.
+     */
+    rotation?: PageRotation;
 }
 export interface RasterizerCapabilities {
     /** Can render PDF-embedded annotations into the raster. */

package/ios/Sources/PdfCanvasBridge/PdfCanvasModule.mm

@@ -324,6 +324,11 @@ RCT_EXPORT_METHOD(render
   req.width = [request[@"width"] doubleValue];
   req.height = [request[@"height"] doubleValue];
   req.scale = [request[@"scale"] doubleValue];
+  // OPTIONAL, DEFAULTING TO 0: a JS bundle older than this binary never sends it,
+  // and a page must not turn because a key is missing. The class check also covers
+  // a JS `null`, which the bridge delivers as `NSNull` rather than `nil`. The core
+  // validates the value; this only decides what "absent" means.
+  req.rotation = [request[@"rotation"] isKindOfClass:NSNumber.class] ? [request[@"rotation"] intValue] : 0;
   req.annotations = request[@"annotations"] == nil ? true : [request[@"annotations"] boolValue];
   req.background = [@"transparent" isEqual:request[@"background"]] ? pdfcanvas::Background::Transparent
                                                                     : pdfcanvas::Background::White;

package/native/CMakeLists.txt

@@ -80,6 +80,13 @@ if(WIN32)
 elseif(APPLE)
   set_target_properties(pdfcanvas_tests PROPERTIES
     BUILD_RPATH "${PDFCANVAS_PDFIUM_DIR}/lib")
+  # The rpath above cannot help on its own: the release dylib's install name is
+  # the CWD-relative `./libpdfium.dylib` (`otool -D`), not `@rpath/…`, so dyld
+  # looks beside the working directory and nowhere else. ctest runs the binary
+  # from the build directory, so — as on Windows — the library is copied there.
+  add_custom_command(TARGET pdfcanvas_tests POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+      "${PDFCANVAS_PDFIUM_DIR}/lib/libpdfium.dylib" "$<TARGET_FILE_DIR:pdfcanvas_tests>")
 else()
   set_target_properties(pdfcanvas_tests PROPERTIES
     BUILD_RPATH "${PDFCANVAS_PDFIUM_DIR}/lib")

package/native/core/include/pdfcanvas/types.h

@@ -48,6 +48,14 @@ struct RasterRequest {
   double scale = 1;
   /// Draw PDF-embedded annotations (and form fields) into the raster.
   bool annotations = true;
+  /// The HOST's rotation on top of the page's `/Rotate`, in degrees clockwise:
+  /// 0, 90, 180 or 270 — anything else is refused. `x`/`y`/`width`/`height`
+  /// are in the TURNED page's doc space (extents swapped for a quarter turn),
+  /// which is what keeps the negative-offset rect mechanism unchanged: the
+  /// only thing the render swaps is the page box it hands PDFium. Absent on
+  /// the wire means 0 on both bindings, so a JS/binary version skew cannot
+  /// turn a page by accident.
+  int rotation = 0;
   Background background = Background::White;
 
   /// Destination width in device pixels: ROUND, not ceil, and at least 1 —

package/native/core/src/document.cpp

@@ -365,6 +365,14 @@ RasterPixels Document::render(const RasterRequest& request, Cancellation* signal
                        " at (" + std::to_string(request.x) + ", " + std::to_string(request.y) + ").");
   }
 
+  if (request.rotation != 0 && request.rotation != 90 && request.rotation != 180 &&
+      request.rotation != 270) {
+    // Refused rather than folded: `45 / 90` is 0 in integer arithmetic, and a
+    // request that asked for a turn must not quietly come back upright.
+    throw PdfError(ErrorCode::BackendFailure,
+                   "Rotation must be 0, 90, 180 or 270, got " + std::to_string(request.rotation) + ".");
+  }
+
   const int pxW = request.pixelWidth();
   const int pxH = request.pixelHeight();
   const long long pixels = static_cast<long long>(pxW) * pxH;
@@ -377,8 +385,16 @@ RasterPixels Document::render(const RasterRequest& request, Cancellation* signal
   // byte-identical to the matrix form on every rect it tried.
   const long long startX = -std::llround(request.x * request.scale);
   const long long startY = -std::llround(request.y * request.scale);
-  const long long pageW = std::llround(geometry.width * request.scale);
-  const long long pageH = std::llround(geometry.height * request.scale);
+  // THE PAGE BOX HANDED TO PDFIUM IS THE DISPLAYED ONE. `size_x` / `size_y`
+  // describe the box the page is drawn INTO after `rotate` is applied —
+  // `CPDF_Page::GetDisplayMatrix` maps the page's HEIGHT onto `size_x` for
+  // rotate 1 and 3 — so a quarter turn swaps the intrinsic extents here. The
+  // request's rect is already in that space (see `RasterRequest::rotation`), so
+  // the start offsets above need nothing: they slide the whole turned page
+  // exactly as they slide an upright one.
+  const bool turned = request.rotation == 90 || request.rotation == 270;
+  const long long pageW = std::llround((turned ? geometry.height : geometry.width) * request.scale);
+  const long long pageH = std::llround((turned ? geometry.width : geometry.height) * request.scale);
   if (pixels > kMaxRasterPixels) {
     throw PdfError(ErrorCode::OutOfMemory,
                    "Refused a " + std::to_string(pxW) + "x" + std::to_string(pxH) + " raster (" +
@@ -451,6 +467,11 @@ RasterPixels Document::render(const RasterRequest& request, Cancellation* signal
   const int sy = static_cast<int>(startY);
   const int pw = static_cast<int>(pageW);
   const int ph = static_cast<int>(pageH);
+  // The HOST's rotation in quarter turns clockwise — never the page's own
+  // `/Rotate`, which PDFium has already folded into `geometry` and into the
+  // render. Passed to BOTH passes below, so a form field lands where the turned
+  // content says and not where the upright page had it.
+  const int rotate = request.rotation / 90;
 
   auto abandonWith = [&](PdfError error) -> PdfError {
     FPDFBitmap_Destroy(bitmap);
@@ -466,8 +487,7 @@ RasterPixels Document::render(const RasterRequest& request, Cancellation* signal
   // TOBECONTINUED when the pause adapter asked to stop, which it does only
   // once the signal is set; a live render runs to DONE in one call.
   PauseAdapter pause(signal);
-  int status = FPDF_RenderPageBitmap_Start(bitmap, page, sx, sy, pw, ph, /*rotate=*/0, flags,
-                                           &pause.pause);
+  int status = FPDF_RenderPageBitmap_Start(bitmap, page, sx, sy, pw, ph, rotate, flags, &pause.pause);
   while (status == FPDF_RENDER_TOBECONTINUED) {
     if (signal != nullptr && signal->isCancelled()) {
       FPDF_RenderPage_Close(page);
@@ -487,7 +507,7 @@ RasterPixels Document::render(const RasterRequest& request, Cancellation* signal
   // state — with the same offsets, so they land exactly where the page put
   // them.
   if (request.annotations && impl_->form != nullptr) {
-    FPDF_FFLDraw(impl_->form, bitmap, page, sx, sy, pw, ph, /*rotate=*/0, flags);
+    FPDF_FFLDraw(impl_->form, bitmap, page, sx, sy, pw, ph, rotate, flags);
   }
 
   FPDFBitmap_Destroy(bitmap);