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

package/PdfCanvas.podspec

@@ -1,6 +1,7 @@
 require "json"
 
 package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+pdfium = JSON.parse(File.read(File.join(__dir__, "scripts", "pdfium-manifest.json")))
 
 # FETCH PDFIUM WHILE THE PODSPEC IS EVALUATED.
 #
@@ -50,10 +51,17 @@ Pod::Spec.new do |s|
   s.authors      = { "REEKON Tools" => "hello@reekon.tools" }
   s.source       = { :git => "https://gitlab.com/reekon-tools/software/rock-pro/react-native-pdf-canvas.git", :tag => "#{s.version}" }
 
-  # 13.0 is the floor of the PDFium dylib bblanchon ships (MinimumOSVersion in
-  # the framework's Info.plist is written to match). Nothing in this pod needs
-  # anything newer.
-  s.platforms    = { :ios => "13.0" }
+  # THE FLOOR IS THE ENGINE'S, NOT OURS. Nothing this pod compiles needs anything
+  # newer than iOS 13, but the vendored PDFium dylib is built for whatever
+  # `ios_deployment_target` bblanchon used (17.0 since 2026-08-14), and that is
+  # what dyld enforces on the device and what App Store processing checks
+  # against the framework's Info.plist (ITMS-90208). The value is declared once
+  # in scripts/pdfium-manifest.json, verified against every slice's Mach-O by
+  # fetch-pdfium.mjs above, and written into the framework plist from the same
+  # field — so it is read here rather than restated. Declaring it as the pod's
+  # platform makes a host with a lower deployment target fail at `pod install`
+  # ("PdfCanvas does not support iOS 16.4") instead of at upload.
+  s.platforms    = { :ios => pdfium["iosMinimumOSVersion"] }
   s.requires_arc = true
 
   # THE CORE IS C++ AND SHARED WITH ANDROID: `native/core` is compiled into this

package/README.md

@@ -80,6 +80,11 @@ during CocoaPods podspec evaluation; Android retrieves it from a Gradle task. Ai
 may direct `PDFCANVAS_PDFIUM_CACHE` or `PDFCANVAS_PDFIUM_MIRROR` at a local copy, which is still
 verified against the manifest.
 
+The prebuilt engine sets the native floors: **iOS 17.0** (`iosMinimumOSVersion` in the manifest,
+declared by the pod and checked against the dylib at fetch time) and **Android API 24**. A host app
+with a lower iOS deployment target fails at `pod install`; raise the target rather than the
+framework's plist, since the dylib will not load on older systems either.
+
 ## Installation
 
 ```sh
@@ -245,6 +250,23 @@ usePdfLayer({document, policy: {sharpnessBand: 1.2, quietZoomMs: 400}});
 observed p95 raster time. A value set too low permits a user adjusting the zoom to supersede
 each render before it completes.
 
+### Page rotation
+
+A host may show a page turned a quarter, half or three-quarter turn clockwise on top of the
+document's own `/Rotate`, per page:
+
+```ts
+// Page 0 shown turned 90° clockwise; pages without an entry stay upright.
+usePdfLayer({document, rotations: [90]});
+// A matching thumbnail. `widthPx` is the width of the TURNED raster.
+document.renderPage(0, {widthPx: 160, rotation: 90});
+```
+
+Doc space for a turned page is the turned page's: a 612x792 page at 90 is laid out as 792x612,
+`content.pages[i].pageRect` reports that rect, and anything the host draws over the page is
+positioned in the same space. Changing a page's rotation rebuilds the layer's raster cache,
+exactly as changing `annotations` does.
+
 ## Platform support
 
 | Platform | Engine                                        | Backend identifier |

package/android/src/androidTest/java/tools/reekon/pdfcanvas/PdfCanvasNativeTest.java

@@ -102,7 +102,7 @@ public class PdfCanvasNativeTest {
 
     long[] shape = new long[4];
     byte[] bytes = PdfCanvasNative.render(
-        service, handle, 0, 0, 0, 200, 100, 2, false, false, 1, false, shape);
+        service, handle, 0, 0, 0, 200, 100, 2, 0, false, false, 1, false, shape);
     assertNotNull("a heap render returns bytes", bytes);
     assertEquals(0L, shape[0]);
     assertEquals(400L, shape[1]);
@@ -122,14 +122,38 @@ public class PdfCanvasNativeTest {
   public void annotationsFlagReachesTheCore() throws Exception {
     int handle = open(TestPdfs.annotated(ctx(), "jni-annotated.pdf"));
     long[] shape = new long[4];
-    byte[] with = PdfCanvasNative.render(service, handle, 0, 0, 0, 200, 200, 1, true, false, 1, false, shape);
-    byte[] without = PdfCanvasNative.render(service, handle, 0, 0, 0, 200, 200, 1, false, false, 2, false, shape);
+    byte[] with = PdfCanvasNative.render(service, handle, 0, 0, 0, 200, 200, 1, 0, true, false, 1, false, shape);
+    byte[] without = PdfCanvasNative.render(service, handle, 0, 0, 0, 200, 200, 1, 0, false, false, 2, false, shape);
     int rowBytes = (int) shape[3];
     assertPixel(with, rowBytes, 100, 100, 0, 255, 0);
     assertPixel(without, rowBytes, 100, 100, 255, 255, 255);
     PdfCanvasNative.close(service, handle);
   }
 
+  /**
+   * CATCHES: the rotation not surviving the JNI int hop, or landing in the
+   * wrong argument slot (a swapped {@code annotations} would still compile).
+   * Doc top-left is blue and bottom-left red; a quarter turn clockwise puts
+   * the bottom-left at the top-left and the top-left at the top-right. The
+   * rect is the TURNED page's: 100x200 for a 200x100 page.
+   */
+  @Test
+  public void rotationReachesTheCore() throws Exception {
+    int handle = open(TestPdfs.quadrants(ctx(), "jni-rotated.pdf", 200, 100));
+    long[] shape = new long[4];
+    byte[] bytes =
+        PdfCanvasNative.render(service, handle, 0, 0, 0, 100, 200, 2, 90, false, false, 1, false, shape);
+    assertNotNull(bytes);
+    assertEquals(200L, shape[1]);
+    assertEquals(400L, shape[2]);
+    int rowBytes = (int) shape[3];
+    assertPixel(bytes, rowBytes, 20, 20, 255, 0, 0);     // red: doc bottom-left, now top-left
+    assertPixel(bytes, rowBytes, 180, 20, 0, 0, 255);    // blue: doc top-left, now top-right
+    assertPixel(bytes, rowBytes, 180, 380, 0, 0, 0);     // black: doc top-right, now bottom-right
+    assertPixel(bytes, rowBytes, 20, 380, 0, 255, 0);    // green: doc bottom-right, now bottom-left
+    PdfCanvasNative.close(service, handle);
+  }
+
   /* ================================================================ *
    * 2. The transport
    * ================================================================ */
@@ -144,11 +168,11 @@ public class PdfCanvasNativeTest {
   public void slotBytesEqualHeapBytesForARealRaster() throws Exception {
     int handle = open(TestPdfs.quadrants(ctx(), "jni-slot.pdf", 300, 200));
     long[] heapShape = new long[4];
-    byte[] heap = PdfCanvasNative.render(service, handle, 0, 37, 23, 64, 41, 4, false, false, 1, false, heapShape);
+    byte[] heap = PdfCanvasNative.render(service, handle, 0, 37, 23, 64, 41, 4, 0, false, false, 1, false, heapShape);
     assertNotNull(heap);
 
     long[] slotShape = new long[4];
-    byte[] none = PdfCanvasNative.render(service, handle, 0, 37, 23, 64, 41, 4, false, false, 2, true, slotShape);
+    byte[] none = PdfCanvasNative.render(service, handle, 0, 37, 23, 64, 41, 4, 0, false, false, 2, true, slotShape);
     assertNull("a slot render returns no bytes", none);
     assertTrue("a slot render names a slot", slotShape[0] > 0);
     assertEquals(heapShape[1], slotShape[1]);
@@ -215,7 +239,7 @@ public class PdfCanvasNativeTest {
     }
     int handle = open(TestPdfs.quadrants(ctx(), "jni-range.pdf", 40, 40));
     try {
-      PdfCanvasNative.render(service, handle, 7, 0, 0, 10, 10, 1, false, false, 1, false, new long[4]);
+      PdfCanvasNative.render(service, handle, 7, 0, 0, 10, 10, 1, 0, false, false, 1, false, new long[4]);
       fail("an out-of-range page must throw");
     } catch (PdfRasterException e) {
       assertEquals(PdfErrorCode.NOT_FOUND, e.code());
@@ -228,24 +252,24 @@ public class PdfCanvasNativeTest {
     PdfCanvasNative.registerCancellation(service, handle, 5);
     PdfCanvasNative.cancel(service, handle, 5);
     try {
-      PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, false, false, 5, false, new long[4]);
+      PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, 0, false, false, 5, false, new long[4]);
       fail("a cancelled render must throw");
     } catch (PdfRasterException e) {
       assertEquals(PdfErrorCode.CANCELLED, e.code());
     }
     // The signal was consumed: the same token renders fine afterwards.
-    assertNotNull(PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, false, false, 5, false, new long[4]));
+    assertNotNull(PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, 0, false, false, 5, false, new long[4]));
   }
 
   @Test
   public void invalidateClosesEverythingAndRefusesAfterwards() throws Exception {
     int handle = open(TestPdfs.quadrants(ctx(), "jni-invalidate.pdf", 40, 40));
-    PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, false, false, 1, true, new long[4]);
+    PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, 0, false, false, 1, true, new long[4]);
     assertEquals(1, PdfCanvasNative.slotCount());
     PdfCanvasNative.invalidateService(service);
     assertEquals("invalidate drains parked slots", 0, PdfCanvasNative.slotCount());
     try {
-      PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, false, false, 2, false, new long[4]);
+      PdfCanvasNative.render(service, handle, 0, 0, 0, 40, 40, 1, 0, false, false, 2, false, new long[4]);
       fail("a render after invalidate must throw");
     } catch (PdfRasterException e) {
       assertEquals(PdfErrorCode.BACKEND_FAILURE, e.code());

package/android/src/main/cpp/pdfcanvas-jni.cpp

@@ -172,8 +172,8 @@ JNIEXPORT void JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_registerCance
 
 JNIEXPORT jbyteArray JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_render(
     JNIEnv* env, jclass, jlong service, jint handle, jint page, jdouble x, jdouble y, jdouble width,
-    jdouble height, jdouble scale, jboolean annotations, jboolean transparent, jlong token,
-    jboolean useSlot, jlongArray out) {
+    jdouble height, jdouble scale, jint rotation, jboolean annotations, jboolean transparent,
+    jlong token, jboolean useSlot, jlongArray out) {
   return guarded<jbyteArray>(env, nullptr, [&]() -> jbyteArray {
     Service* s = serviceOf(service);
     if (s == nullptr) throw PdfError(ErrorCode::BackendFailure, "The native service is gone.");
@@ -188,6 +188,8 @@ JNIEXPORT jbyteArray JNICALL Java_tools_reekon_pdfcanvas_PdfCanvasNative_render(
     request.width = width;
     request.height = height;
     request.scale = scale;
+    // Degrees clockwise on top of the page's /Rotate; the core validates it.
+    request.rotation = rotation;
     request.annotations = annotations == JNI_TRUE;
     request.background = transparent == JNI_TRUE ? pdfcanvas::Background::Transparent
                                                  : pdfcanvas::Background::White;

package/android/src/main/java/tools/reekon/pdfcanvas/PdfCanvasNative.java

@@ -107,6 +107,10 @@ public final class PdfCanvasNative {
   /**
    * Renders one raster on the calling thread.
    *
+   * @param rotation the HOST's rotation on top of the page's {@code /Rotate},
+   *     in degrees clockwise: 0, 90, 180 or 270. The rect is in the TURNED
+   *     page's doc space — extents swapped for a quarter turn. The core refuses
+   *     anything else.
    * @param useSlot ask for the zero-copy transport. The store may still refuse,
    *     so the result says where the pixels ARE: a non-null return is heap
    *     bytes, a null return means {@code out[0]} names a slot.
@@ -122,6 +126,7 @@ public final class PdfCanvasNative {
       double width,
       double height,
       double scale,
+      int rotation,
       boolean annotations,
       boolean transparent,
       long token,

package/android/src/reactnative/java/tools/reekon/pdfcanvas/rn/PdfCanvasModule.java

@@ -294,7 +294,7 @@ public class PdfCanvasModule extends ReactContextBaseJavaModule {
       return;
     }
     // The whole request is turned into plain values HERE, on the bridge thread.
-    final int page;
+    final int page, rotation;
     final double x, y, width, height, scale;
     final boolean annotations, transparent;
     try {
@@ -304,6 +304,13 @@ public class PdfCanvasModule extends ReactContextBaseJavaModule {
       width = request.getDouble("width");
       height = request.getDouble("height");
       scale = request.getDouble("scale");
+      // 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 core
+      // validates the value; this only decides what "absent" means.
+      rotation =
+          request.hasKey("rotation") && !request.isNull("rotation")
+              ? request.getInt("rotation")
+              : 0;
       annotations = !request.hasKey("annotations") || request.getBoolean("annotations");
       transparent = "transparent".equals(request.getString("background"));
     } catch (RuntimeException e) {
@@ -329,8 +336,8 @@ public class PdfCanvasModule extends ReactContextBaseJavaModule {
               final long[] shape = new long[4];
               final byte[] bytes =
                   PdfCanvasNative.render(
-                      service, handle, page, x, y, width, height, scale, annotations, transparent,
-                      token, fast, shape);
+                      service, handle, page, x, y, width, height, scale, rotation, annotations,
+                      transparent, token, fast, shape);
               slot = shape[0];
 
               WritableMap result = Arguments.createMap();

package/dist/controller.d.ts

@@ -37,7 +37,7 @@
  * which key comes from `./planner.js`. A private copy of either is how the two
  * silently drift until the tested one is testing nothing that runs.
  */
-import type { DocRect, PageGeometry, PdfContent, PdfController, PdfDiagnostic, PdfRaster, RasterizerHandle, RasterPixels, RasterPolicy, RasterRole } from './types.js';
+import type { DocRect, PageGeometry, PageRotation, PdfContent, PdfController, PdfDiagnostic, PdfRaster, RasterizerHandle, RasterPixels, RasterPolicy, RasterRole } from './types.js';
 import type { RasterCache } from './cache.js';
 export interface ScheduledHandle {
     cancel(): void;
@@ -62,6 +62,28 @@ export interface PdfControllerOptions {
     pageRects: DocRect[];
     /** Parallel to `pageRects`. Every page, in page order. */
     pages: PageGeometry[];
+    /**
+     * The HOST's per-page rotation on top of the document's `/Rotate`, indexed
+     * by page like `pageRects`; a missing or undefined entry is 0. Stamped onto
+     * every `RasterRequest` for that page as `rotation` — and only that. The
+     * controller does no rotation arithmetic of its own.
+     *
+     * WHY A PARALLEL ARRAY AND NOT A FIELD ON `PageGeometry`. `PageGeometry` is
+     * the backend's statement of a page's intrinsic size, and its `rotation` is
+     * already taken: it is the document's own `/Rotate`. A host preference on
+     * the same object would give the type two rotations with different meanings,
+     * and would ride into every backend that constructs one (the fake, the web
+     * engine, the native bridge) for a value none of them produce. This
+     * controller already takes its per-page inputs as parallel arrays, so a
+     * third costs nothing new and touches nothing outside this file.
+     *
+     * THE GEOMETRY MUST ALREADY BE ROTATED. For a page turned 90 or 270, `pages`
+     * and `pageRects` must both carry the SWAPPED extents — see `../rotation.ts`
+     * — because `layoutScale` is `pageRect.width / geometry.width` and is only
+     * right when both sides describe the same orientation. `usePdfLayer` does
+     * the swap; a host driving this directly must too.
+     */
+    rotations?: readonly PageRotation[];
     policy: RasterPolicy;
     ingest: (pixels: RasterPixels, meta: RasterIngestMeta) => PdfRaster;
     cache: RasterCache;

package/dist/controller.js

@@ -137,6 +137,7 @@ export function createPdfController(options) {
             page,
             pageRect,
             layoutScale: Number.isFinite(raw) && raw > 0 ? raw : 1,
+            rotation: options.rotations?.[page] ?? 0,
         };
     });
     const listeners = new Set();
@@ -405,24 +406,35 @@ export function createPdfController(options) {
         };
         const renderOne = async (item, slot, info) => {
             const startedAt = now();
+            const request = {
+                page: item.page,
+                // Page-LOCAL rect: the planner works in LAYOUT space, but a backend
+                // renders a page and knows nothing about where the layout put it.
+                // For a page the host has turned this is the ROTATED page's space:
+                // `pageRects` and `pages` both carry the swapped extents, which is
+                // what keeps `layoutScale` at 1 and lets the backend slide the whole
+                // turned page exactly as it slides an upright one.
+                docRect: {
+                    x: (item.docRect.x - info.pageRect.x) / info.layoutScale,
+                    y: (item.docRect.y - info.pageRect.y) / info.layoutScale,
+                    width: item.docRect.width / info.layoutScale,
+                    height: item.docRect.height / info.layoutScale,
+                },
+                scale: item.scale * info.layoutScale,
+                // See `PdfControllerOptions.annotations`: true unless the host
+                // draws the PDF's annotations itself.
+                annotations: drawAnnotations,
+                background: 'white',
+            };
+            // STAMPED ONLY WHEN IT IS NOT THE DEFAULT. A host that never rotates
+            // hands its backend the exact request it always did, key for key — a
+            // host-injected backend that compares requests structurally sees no
+            // change at all — and every shipped backend reads `rotation ?? 0`.
+            if (info.rotation !== 0)
+                request.rotation = info.rotation;
             let pixels;
             try {
-                pixels = await handle.render({
-                    page: item.page,
-                    // Page-LOCAL rect: the planner works in LAYOUT space, but a backend
-                    // renders a page and knows nothing about where the layout put it.
-                    docRect: {
-                        x: (item.docRect.x - info.pageRect.x) / info.layoutScale,
-                        y: (item.docRect.y - info.pageRect.y) / info.layoutScale,
-                        width: item.docRect.width / info.layoutScale,
-                        height: item.docRect.height / info.layoutScale,
-                    },
-                    scale: item.scale * info.layoutScale,
-                    // See `PdfControllerOptions.annotations`: true unless the host
-                    // draws the PDF's annotations itself.
-                    annotations: drawAnnotations,
-                    background: 'white',
-                }, state.abort.signal);
+                pixels = await handle.render(request, state.abort.signal);
             }
             catch (error) {
                 missing.push(item.key);

package/dist/rasterizer/fake.d.ts

@@ -14,8 +14,14 @@
  *     checks and an accidental clip is visible as a blank margin;
  *   - each piece carries a 1px border, so a piece that has been inset or
  *     stretched shows its border in the wrong place;
- *   - each piece encodes its own doc rect into a corner swatch, so a test can
- *     read back what a raster BELIEVES it is without any Skia in the loop.
+ *   - each piece encodes its own doc rect AND its rotation into a corner
+ *     swatch, so a test can read back what a raster BELIEVES it is without any
+ *     Skia in the loop;
+ *   - the checker is drawn in the PAGE's own space and turned by the request's
+ *     `rotation`, the way a real engine turns its page — so a raster at 90 is
+ *     the raster at 0 turned a quarter clockwise, pixel for pixel outside the
+ *     border and swatch, and a pipeline that rotated its geometry but forgot
+ *     to stamp the request shows an unturned board in a turned frame.
  *
  * Everything here is a pure function of the request, so the same request always
  * produces byte-identical output.
@@ -89,4 +95,10 @@ export declare function fakePageColor(page: number): [number, number, number];
  * was too small to carry a swatch.
  */
 export declare function decodeFakeDocRect(pixels: RasterPixels): DocRect | null;
+/**
+ * Read the rotation a fake raster was rendered at, or null when the raster was
+ * too small to carry a swatch. What a pipeline test reads to prove the
+ * controller's stamp reached the backend.
+ */
+export declare function decodeFakeRotation(pixels: RasterPixels): PageRotation | null;
 export declare function createFakeRasterizer(options?: FakeRasterizerOptions): PageRasterizer;

package/dist/rasterizer/fake.js

@@ -14,12 +14,19 @@
  *     checks and an accidental clip is visible as a blank margin;
  *   - each piece carries a 1px border, so a piece that has been inset or
  *     stretched shows its border in the wrong place;
- *   - each piece encodes its own doc rect into a corner swatch, so a test can
- *     read back what a raster BELIEVES it is without any Skia in the loop.
+ *   - each piece encodes its own doc rect AND its rotation into a corner
+ *     swatch, so a test can read back what a raster BELIEVES it is without any
+ *     Skia in the loop;
+ *   - the checker is drawn in the PAGE's own space and turned by the request's
+ *     `rotation`, the way a real engine turns its page — so a raster at 90 is
+ *     the raster at 0 turned a quarter clockwise, pixel for pixel outside the
+ *     border and swatch, and a pipeline that rotated its geometry but forgot
+ *     to stamp the request shows an unturned board in a turned frame.
  *
  * Everything here is a pure function of the request, so the same request always
  * produces byte-identical output.
  */
+import { isPageRotation } from '../rotation.js';
 import { PdfError } from '../types.js';
 /* ------------------------------------------------------------------ *
  * Page sizes, in PDF points (1pt = 1/72in)
@@ -171,9 +178,10 @@ function writePixel(out, offset, r, g, b, a, format) {
  * The corner swatch
  * ------------------------------------------------------------------ */
 /**
- * The swatch is RAW BYTES, not a colour: four pixels, each carrying one doc
- * rect component as a 24-bit fixed-point value in channels 0..2 with channel 3
- * held at 255. Because it is written without the format swizzle, the decoder is
+ * The swatch is RAW BYTES, not a colour: five pixels, each carrying one value
+ * as a 24-bit fixed-point number in channels 0..2 with channel 3 held at 255 —
+ * the four doc rect components, then the request's rotation in degrees.
+ * Because it is written without the format swizzle, the decoder is
  * format-independent — it reads back the same numbers from an RGBA and a BGRA
  * raster.
  */
@@ -182,7 +190,9 @@ const SWATCH_FIXED_POINT = 16;
 const SWATCH_BIAS = 0x800000;
 const SWATCH_ORIGIN_X = 1;
 const SWATCH_ROW = 1;
-const SWATCH_PIXELS = 4;
+const SWATCH_PIXELS = 5;
+/** Index of the rotation value within the swatch, after x, y, width, height. */
+const SWATCH_ROTATION = 4;
 /** Smallest raster that has room for the swatch inside its border. */
 const SWATCH_MIN_WIDTH = SWATCH_ORIGIN_X + SWATCH_PIXELS + 1;
 const SWATCH_MIN_HEIGHT = SWATCH_ROW + 2;
@@ -194,7 +204,7 @@ function encodeSwatchValue(out, offset, value) {
     out[offset + 2] = clamped & 0xff;
     out[offset + 3] = 255;
 }
-function encodeSwatch(out, rowBytes, width, height, docRect) {
+function encodeSwatch(out, rowBytes, width, height, docRect, rotation) {
     if (width < SWATCH_MIN_WIDTH || height < SWATCH_MIN_HEIGHT) {
         return;
     }
@@ -203,39 +213,81 @@ function encodeSwatch(out, rowBytes, width, height, docRect) {
     encodeSwatchValue(out, base + BYTES_PER_PIXEL, docRect.y);
     encodeSwatchValue(out, base + BYTES_PER_PIXEL * 2, docRect.width);
     encodeSwatchValue(out, base + BYTES_PER_PIXEL * 3, docRect.height);
+    encodeSwatchValue(out, base + BYTES_PER_PIXEL * SWATCH_ROTATION, rotation);
+}
+/** One swatch value back out, or null when the raster is too small to carry a
+ * swatch at all. `component` is the pixel index within the swatch. */
+function decodeSwatchValue(pixels, component) {
+    const { bytes, width, height, rowBytes } = pixels;
+    if (width < SWATCH_MIN_WIDTH || height < SWATCH_MIN_HEIGHT) {
+        return null;
+    }
+    const o = SWATCH_ROW * rowBytes + (SWATCH_ORIGIN_X + component) * BYTES_PER_PIXEL;
+    // In range by the size guard above; `?? 0` satisfies
+    // noUncheckedIndexedAccess on TypedArray indexing.
+    const raw = ((bytes[o] ?? 0) << 16) | ((bytes[o + 1] ?? 0) << 8) | (bytes[o + 2] ?? 0);
+    return (raw - SWATCH_BIAS) / SWATCH_FIXED_POINT;
 }
 /**
  * Read the doc rect a fake raster believes it covers, or null when the raster
  * was too small to carry a swatch.
  */
 export function decodeFakeDocRect(pixels) {
-    const { bytes, width, height, rowBytes } = pixels;
-    if (width < SWATCH_MIN_WIDTH || height < SWATCH_MIN_HEIGHT) {
+    const x = decodeSwatchValue(pixels, 0);
+    const y = decodeSwatchValue(pixels, 1);
+    const width = decodeSwatchValue(pixels, 2);
+    const height = decodeSwatchValue(pixels, 3);
+    if (x === null || y === null || width === null || height === null) {
         return null;
     }
-    const base = SWATCH_ROW * rowBytes + SWATCH_ORIGIN_X * BYTES_PER_PIXEL;
-    const read = (component) => {
-        const o = base + component * BYTES_PER_PIXEL;
-        // In range by the size guard above; `?? 0` satisfies
-        // noUncheckedIndexedAccess on TypedArray indexing.
-        const raw = ((bytes[o] ?? 0) << 16) |
-            ((bytes[o + 1] ?? 0) << 8) |
-            (bytes[o + 2] ?? 0);
-        return (raw - SWATCH_BIAS) / SWATCH_FIXED_POINT;
-    };
-    return {
-        x: read(0),
-        y: read(1),
-        width: read(2),
-        height: read(3),
-    };
+    return { x, y, width, height };
+}
+/**
+ * Read the rotation a fake raster was rendered at, or null when the raster was
+ * too small to carry a swatch. What a pipeline test reads to prove the
+ * controller's stamp reached the backend.
+ */
+export function decodeFakeRotation(pixels) {
+    const rotation = decodeSwatchValue(pixels, SWATCH_ROTATION);
+    if (rotation === null)
+        return null;
+    return isPageRotation(rotation) ? rotation : null;
 }
 /* ------------------------------------------------------------------ *
  * Rendering
  * ------------------------------------------------------------------ */
-function renderPixels(request, cfg) {
+/**
+ * The inverse of the request's rotation: a point in the TURNED page's doc space
+ * back to the page's own. `pageWidth` / `pageHeight` are the page's intrinsic
+ * (unturned) extents.
+ *
+ * These are the inverses of PDFium's `CPDF_Page::GetDisplayMatrix` for rotate
+ * 1..3, restated in y-down doc units — the same mapping the real backends'
+ * tests hold a turned render to, so the fake and the engine agree on what "90
+ * clockwise" means.
+ */
+function unrotate(rotation, pageWidth, pageHeight) {
+    switch (rotation) {
+        case 90:
+            return (x, y) => [y, pageHeight - x];
+        case 180:
+            return (x, y) => [pageWidth - x, pageHeight - y];
+        case 270:
+            return (x, y) => [pageWidth - y, x];
+        default:
+            return (x, y) => [x, y];
+    }
+}
+function renderPixels(request, cfg, geometry) {
     const { docRect, scale, page, background } = request;
     const { width, height } = fakePixelSize(request);
+    // Read as `?? 0` and then VALIDATED, as every real backend does: the fake
+    // stands in for them in the controller suite, so it must refuse what they
+    // refuse rather than quietly draw an upright page.
+    const rotation = request.rotation ?? 0;
+    if (!isPageRotation(rotation)) {
+        throw new PdfError('backend-failure', `Fake rasterizer: rotation must be 0, 90, 180 or 270, got ${String(rotation)}.`);
+    }
     if (width * height > cfg.maxPixels) {
         throw new PdfError('out-of-memory', `Fake rasterizer refused a ${width}x${height} raster ` +
             `(${width * height} pixels > maxPixels ${cfg.maxPixels}).`);
@@ -256,18 +308,23 @@ function renderPixels(request, cfg) {
             writePixel(bytes, o, tintR, tintG, tintB, 255, cfg.format);
         }
     }
-    // Dark checker cells, in DOC space. Pixel CENTRES are converted to doc
-    // coordinates — a corner-based conversion puts the sample exactly on a cell
-    // boundary whenever the piece origin happens to align with one, and the
-    // parity then flips on a floating-point tie.
+    // Dark checker cells, in the PAGE's DOC space. Pixel CENTRES are converted
+    // to doc coordinates — a corner-based conversion puts the sample exactly on
+    // a cell boundary whenever the piece origin happens to align with one, and
+    // the parity then flips on a floating-point tie. The request's rect is in
+    // the TURNED page's space, so each centre is mapped back through the inverse
+    // rotation before its cell is looked up: that is what makes the board turn
+    // with the request, the way a real engine's page does.
     const cell = cfg.checkerDocSize;
+    const toPage = unrotate(rotation, geometry.width, geometry.height);
     for (let py = 0; py < height; py++) {
-        const docY = docRect.y + (py + 0.5) / scale;
-        const cellY = Math.floor(docY / cell);
+        const turnedY = docRect.y + (py + 0.5) / scale;
         let offset = py * rowBytes;
         for (let px = 0; px < width; px++, offset += BYTES_PER_PIXEL) {
-            const docX = docRect.x + (px + 0.5) / scale;
+            const turnedX = docRect.x + (px + 0.5) / scale;
+            const [docX, docY] = toPage(turnedX, turnedY);
             const cellX = Math.floor(docX / cell);
+            const cellY = Math.floor(docY / cell);
             if (((cellX + cellY) & 1) === 1) {
                 writePixel(bytes, offset, r, g, b, 255, cfg.format);
             }
@@ -288,7 +345,7 @@ function renderPixels(request, cfg) {
             writePixel(bytes, row + lastCol, 0, 0, 0, 255, cfg.format);
         }
     }
-    encodeSwatch(bytes, rowBytes, width, height, docRect);
+    encodeSwatch(bytes, rowBytes, width, height, docRect, rotation);
     return {
         bytes,
         width,
@@ -384,7 +441,7 @@ function createHandle(cfg) {
         async render(request, signal) {
             throwIfAborted(signal);
             requireOpen();
-            requirePage(request.page);
+            const geometry = requirePage(request.page);
             if (cfg.latencyMs > 0) {
                 await delay(cfg.latencyMs, signal);
             }
@@ -396,7 +453,7 @@ function createHandle(cfg) {
             if (failure) {
                 throw new PdfError(failure, `Fake rasterizer failed page ${request.page} by configuration.`);
             }
-            return renderPixels(request, cfg);
+            return renderPixels(request, cfg, geometry);
         },
         close() {
             closed = true;

package/dist/rasterizer/native-bridge.d.ts

@@ -81,6 +81,17 @@ export interface NativeRenderRequest {
     scale: number;
     annotations: boolean;
     background: 'white' | 'transparent';
+    /**
+     * Degrees clockwise, 0 / 90 / 180 / 270, on top of the page's `/Rotate`.
+     *
+     * ALWAYS PRESENT on the wire — 0 when the `RasterRequest` carried none —
+     * while both native modules read it as optional-defaulting-to-0. That pair
+     * is what makes a version skew safe in both directions: a JS bundle newer
+     * than its binary sends a key the binary never looks for, and a binary newer
+     * than its bundle reads 0 for a key that never arrives. Neither can turn a
+     * page by accident.
+     */
+    rotation: number;
 }
 export interface NativeSource {
     uri?: string;

package/dist/rasterizer/native-bridge.js

@@ -343,6 +343,7 @@ export function createNativeHandle(native, opened, transport, alpha, label) {
                     scale: request.scale,
                     annotations: request.annotations,
                     background: request.background,
+                    rotation: request.rotation ?? 0,
                 }, token);
             }
             catch (error) {