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

package/README.md

@@ -1,124 +1,162 @@
 # @reekon-tools/react-native-pdf-canvas
 
-PDF pages as Skia images, drawn at exact doc-space rects inside **somebody else's**
-transform.
-
-This package owns no `<Canvas>`, no gestures, no viewport state and no document model.
-It contributes **zero** Reanimated shared values to the Skia subtree, so a host that
-drives its world transform from the UI thread keeps its per-frame budget of one.
-
-> **Status: 0.1.0, pre-release.** The pure core, the cadence controller, the React
-> layer and a deterministic fake backend are implemented and tested. **All three
-> backends now exist**: Android (`PdfRenderer`) and iOS (CoreGraphics + PDFKit) are
-> implemented and proven on device end to end; web (PDFium in a worker) is implemented
-> but must be configured, because how a worker is built and where `pdfium.wasm` lives
-> are the host bundler's business. On a platform with no native module
-> `getDefaultRasterizer()` returns one that throws a descriptive `PdfError` at
-> `open()`, and everything else is usable against `createFakeRasterizer()`.
->
-> The platform backend is **not** installed for you. It lives on its own subpath so that
-> importing the package never drags a native module into a web or test bundle:
->
-> ```ts
-> import {setDefaultRasterizer} from '@reekon-tools/react-native-pdf-canvas';
-> import {getDefaultRasterizer} from '@reekon-tools/react-native-pdf-canvas/rasterizer';
->
-> setDefaultRasterizer(getDefaultRasterizer()); // once, at app startup
-> ```
->
-> Skip it and every `openPdfDocument` / `usePdfDocument` call fails with
-> `unsupported: No PageRasterizer available` — the two `getDefaultRasterizer`s are
-> deliberately different functions (see `src/rasterizer/index.native.ts`), and only the
-> subpath one knows about the native module.
-
-## Subpaths, and why the root has none of Skia in it
-
-| Subpath        | What it is                                                                      |
-| -------------- | ------------------------------------------------------------------------------- |
-| `.`            | Pure core, layouts, policy, controller, cache, planner, hooks, `PdfContentView` |
-| `./skia`       | `ingestRaster` / `imageFromPixels` / `rasterByteLength`, and `skiaApi()`        |
-| `./rasterizer` | Platform backend registry (`getDefaultRasterizer`) and backend helpers          |
-| `./web-init`   | `loadPdfCanvasSkiaWeb()` — web only                                             |
-| `./worker`     | The PDFium module worker. A bundler entry point, web only                       |
-| `./testing`    | `createFakeRasterizer()` and the deterministic scenes                           |
-
-**Nothing reachable from `.` touches the Skia runtime at module scope, and that is
-enforced by a test, not by convention** (`src/__tests__/module-ordering.test.ts` runs a
-real Vite build of each entry and inspects the module graph and the emitted text).
-
-The reason is one line in `@shopify/react-native-skia`:
-
-```js
-// lib/module/skia/Skia.web.js
-export const Skia = JsiSkApi(global.CanvasKit);
+[![npm](https://img.shields.io/npm/v/@reekon-tools/react-native-pdf-canvas)](https://www.npmjs.com/package/@reekon-tools/react-native-pdf-canvas)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](./LICENSE)
+
+Renders PDF pages as Skia images positioned at exact PDF-space rectangles within a
+host-supplied transform. A single PDFium engine serves iOS, Android and web, so a given tile is
+byte-identical across all three platforms.
+
+## Overview
+
+The package does not provide a PDF viewer. It owns no `<Canvas>`, no gesture handlers, no
+viewport state and no document model; each of those remains the responsibility of the host
+application. What it provides is rasterized page tiles, each paired with the document-space
+rectangle it occupies, for the host to draw inside its own transform alongside its own content.
+
+```tsx
+<Canvas>
+  <Group transform={worldTransform}>
+    <PdfContentView content={content} />
+    {/* Host content: annotations, measurements, overlays — same doc space, same transform */}
+  </Group>
+</Canvas>
+```
+
+Conventional PDF components encapsulate the scroll view, the zoom transform and the rendered
+output. Content drawn above such a component must be registered against its internal viewport,
+and that registration is approximate. This package inverts the arrangement: it emits rectangles
+in PDF points and never reads the host's transform. Four properties follow.
+
+- **Exact registration.** A single transform is applied once, to the page and to the host's
+  content alike. No error term is introduced, because the package performs no conversion to
+  screen space.
+- **No contention for the frame budget.** The package contributes zero Reanimated shared values
+  to the Skia subtree, so a host driving its world transform from the UI thread retains a
+  per-frame budget of one.
+- **Deferred rasterization.** Rendering occurs when the host reports that its viewport has
+  settled, rather than on every frame. A stale tile is soft but never mispositioned, which is
+  the property that makes deferral safe.
+- **Bounded memory at any zoom level.** Detail tiles track the viewport rather than the page, so
+  a 36-inch sheet at 8× magnification costs no more than the same sheet at 1×.
+
+### Intended use
+
+React Native and web applications that render their own content above a PDF and require it to
+register exactly: markup and annotation tools, field measurement, takeoff and estimating, CAD
+and drawing review, and form overlays.
+
+### Out of scope
+
+The package supplies no viewer chrome — no scroll view, page controls or navigation — and
+deliberately requires the host to provide the canvas, the gesture handling and the page layout.
+It does not extract text, perform search, or modify documents; its function is rasterization.
+
+## Project status
+
+Version 0.2.0 is a pre-release. The core, the cadence controller, the React layer and a
+deterministic fake backend are implemented and tested. All three platform backends render with
+PDFium, so annotations, form fields, passwords and page rotation behave identically on each. The
+native core is covered by a host-machine C++ suite, and the web backend by 45 tests driving real
+PDFium WebAssembly under Node.
+
+Two areas remain unverified: the web backend has not yet been exercised in a browser, and the
+iOS binding requires a device pass.
+
+## Requirements
+
+| Peer dependency              | Range      | Required                                   |
+| ---------------------------- | ---------- | ------------------------------------------ |
+| `react`                      | `>=19.0.0` | Always                                     |
+| `@shopify/react-native-skia` | `>=2.8.0`  | Always                                     |
+| `react-native`               | `>=0.78.0` | Native platforms only                      |
+| `react-native-reanimated`    | `>=3.19.1` | Only if the host transform is driven by it |
+| `@embedpdf/pdfium`           | `>=2.15.0` | Web only                                   |
+
+PDFium is not an npm dependency. It is retrieved at build time from
+[pdfium-binaries](https://github.com/bblanchon/pdfium-binaries), pinned by SHA-256 digest in
+`scripts/pdfium-manifest.json`, and adds approximately 6.5 MB per platform. iOS retrieves it
+during CocoaPods podspec evaluation; Android retrieves it from a Gradle task. Air-gapped builds
+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
+npm install @reekon-tools/react-native-pdf-canvas
 ```
 
-That call is taken at **module scope, once, for the life of the bundle**. Reach it before
-`LoadSkiaWeb` has resolved and every factory on `Skia` closes over `undefined` — and
-re-importing the specifier hands back the identical broken object, because ES modules
-evaluate once. There is no in-bundle recovery.
+The platform backend is not registered automatically. It resides on a dedicated subpath so that
+importing the package never introduces a native module into a web or test bundle.
+
+### iOS and Android
 
-It is easy to reach by accident: RN Skia declares no `sideEffects: false` and no
-`exports` map, and its root barrel funnels everything through `export {Skia} from
-"./Skia"`, so **any** value import of the bare specifier — a `<Group>`, a `ColorType` —
-evaluates it. rock-desktop is `{ssr: true}` with `flatRoutes()` and no prerender, so
-every route module is evaluated in Node on every request; one route naming this package's
-root would have been enough.
+Autolinking handles the native module. Register the backend once, during application startup:
 
-So: `AlphaType` / `ColorType` and the four Skia node components are imported from their
-own leaf modules, `Skia` itself is reached through a call-time `skiaApi()` accessor
-(`src/skia/skia-api.ts`), and the ingest seam lives on `./skia` rather than on the root.
+```ts
+import {setDefaultRasterizer} from '@reekon-tools/react-native-pdf-canvas';
+import {getDefaultRasterizer} from '@reekon-tools/react-native-pdf-canvas/rasterizer';
+
+setDefaultRasterizer(getDefaultRasterizer());
+```
 
-**On native none of this applies** — `Skia` there is `global.SkiaApi`, installed
-synchronously by RN Skia's own import-time side effect — which is why
-`src/index.native.ts` imports the barrel quite happily and only the web entries are under
-the claim.
+Then run `pod install` in the `ios` directory.
 
-### Web startup
+### Web
+
+Web configuration requires three steps, performed once before the first render.
+
+**1. Load CanvasKit.** This step may be omitted by hosts that already load CanvasKit themselves,
+whether through `WithSkiaWeb`, RN Skia's `LoadSkiaWeb`, or a `<script>` tag that assigns
+`globalThis.CanvasKit`; the package detects any of these. `loadPdfCanvasSkiaWeb` is the
+awaitable equivalent:
 
 ```ts
 import {loadPdfCanvasSkiaWeb} from '@reekon-tools/react-native-pdf-canvas/web-init';
 
-// Once, before the first raster. The locator is YOURS — this package never
-// hardcodes a CanvasKit URL, because the version that must match is the one your
-// tree installed.
+// The host supplies the locator. The package never hardcodes a CanvasKit URL, because
+// the version that must match is the one installed in the host's dependency tree.
 await loadPdfCanvasSkiaWeb({
   locateFile: file =>
     `https://cdn.jsdelivr.net/npm/canvaskit-wasm@${canvasKitVersion}/bin/full/${file}`,
 });
 ```
 
-A host that already loads CanvasKit its own way (a `WithSkiaWeb` around its canvas, RN
-Skia's bare `LoadSkiaWeb`, a `<script>` that sets `globalThis.CanvasKit`) needs no call:
-the web entry point installs a resolver that reads `globalThis.CanvasKit` on first use.
-`loadPdfCanvasSkiaWeb` is the version you can `await`.
-
-`PdfContentView` deliberately does **not** wrap itself in a `WithSkiaWeb`. It mounts
-inside somebody else's `<Group transform>` inside somebody else's `<Canvas>`; a lazy
-component boundary there would break the Skia subtree, and boldr-utils already found that
-`WithSkiaWeb` cannot forward refs through it. Put your own around the whole canvas if you
-want one.
-
-## The one rule
+**2. Configure the PDFium worker.** The package ships the worker but constructs neither a
+`Worker` nor a URL of its own, as worker bundling and the location of `pdfium.wasm` are
+properties of the host's build pipeline. Under Vite:
 
-> **The transform decides _when_ to rasterize, never _what_ to draw.**
+```ts
+import PdfCanvasWorker from '@reekon-tools/react-native-pdf-canvas/worker?worker';
+import wasmUrl from '@embedpdf/pdfium/pdfium.wasm?url';
+import {configureWebPdfium} from '@reekon-tools/react-native-pdf-canvas/rasterizer';
+import {setDefaultRasterizer} from '@reekon-tools/react-native-pdf-canvas';
 
-Doc space is PDF points, y-down, origin at the page's top-left — exactly what PDFium's
-`CPDF_Page::GetDisplayMatrix()` emits. Every rect the package emits lives there, with
-plain-number values constant for the life of an epoch. The host's
-`<Group transform={worldTransform}>` does 100% of the pan and zoom.
+setDefaultRasterizer(
+  configureWebPdfium({
+    createWorker: () => new PdfCanvasWorker(),
+    wasm: {url: wasmUrl},
+  }),
+);
+```
 
-Two consequences, both load-bearing:
+Any other means of producing a **module** worker is equally acceptable, including
+`new Worker(url, {type: 'module'})`. The `wasm` option also accepts `{binary}` for hosts with
+their own asset pipeline, at the cost of a 4.6 MB structured clone per document.
 
-- **A stale raster is never wrong, only soft.** That is what makes "don't rasterize
-  during a gesture" safe. In screen space a stale raster would be _mispositioned_, which
-  is why screen-space designs must re-render continuously.
-- **Registration with the layers above is exact by construction.** One transform,
-  applied once, to the page and to whatever you draw on top. There is no error term.
+**3. Do not wrap `PdfContentView` in `WithSkiaWeb`.** The component mounts within the host's
+`<Group>` inside the host's `<Canvas>`, where a lazy component boundary would break the Skia
+subtree. A `WithSkiaWeb` boundary belongs around the canvas as a whole.
 
-The package therefore never reads `worldTransform.value` and never accepts a
-`Transforms3d`. The host **pushes** a plain `{visibleDocRect, scale}` snapshot at settle
-rate.
+If configuration is omitted, every `openPdfDocument` and `usePdfDocument` call fails with a
+descriptive `unsupported: No PageRasterizer available` error rather than degrading silently.
+`createFakeRasterizer()`, exported from the `./testing` subpath, keeps the remainder of the API
+usable under test.
 
 ## Usage
 
@@ -131,11 +169,11 @@ import {
 } from '@reekon-tools/react-native-pdf-canvas';
 
 function Sheet({uri, worldTransform, viewport}) {
-  // ABOVE the <Canvas>. Not stylistic — see "Where the hooks go".
+  // Both hooks must be mounted above the <Canvas>. See "Hook placement".
   const {document} = usePdfDocument({uri});
   const {content, controller} = usePdfLayer({document});
 
-  // Your gestures, your transform. Tell the package when you settled.
+  // Gesture handling and the transform remain the host's. Report settle events.
   const pan = Gesture.Pan()
     .onBegin(() => runOnJS(controller.suppress)())
     .onFinalize(() => runOnJS(controller.settle)(viewport()));
@@ -145,7 +183,7 @@ function Sheet({uri, worldTransform, viewport}) {
       <Canvas style={{flex: 1}}>
         <Group transform={worldTransform}>
           <PdfContentView content={content} />
-          {/* everything else, in the same doc space */}
+          {/* Remaining host content, in the same doc space */}
         </Group>
       </Canvas>
     </GestureDetector>
@@ -153,1239 +191,103 @@ function Sheet({uri, worldTransform, viewport}) {
 }
 ```
 
-### Where the hooks go
-
-**Above the `<Canvas>`, always.** React context does not cross the Canvas boundary — RN
-Skia mounts its own reconciler for the Skia subtree — and a magnifier loupe is a
-_second_ Canvas, i.e. a second reconciler root with its own copy of every hook. A cache
-instantiated inside the Canvas is created twice, concurrently, doubling tens of MB.
-Hoisting the hook and passing the same `content` to both canvases is what makes a loupe
-free.
-
-### Why `settle()` must be called, not sniffed
-
-A `withDecay` fling at 2000 px/s animates for **~38 seconds** at Reanimated's default
-deceleration, changing the shared value every frame the whole time. A "no change for N
-ms" gate never fires; a "delta < 1 px/frame" gate does not fire until ~17.5 s in. On web
-it is ~53 s. And there is no pollable escape: `_animation` is set on start and cleared
-only on _interruption_, never on natural completion — so `if (sv._animation)` is
-permanently true after the first animation.
-
-A library cannot observe a consumer's animation from outside. Hence the contract:
-
-| Call                    | When                                               | Delay                |
-| ----------------------- | -------------------------------------------------- | -------------------- |
-| `controller.suppress()` | gesture begin                                      | —                    |
-| `controller.settle(v)`  | gesture end, or an animation's completion callback | 0 ms                 |
-| `controller.hint(v)`    | continuous input: wheel, trackpad, momentum        | trailing quiet timer |
-
-## Render model
-
-Two standing layers per page, plus a transient.
-
-| Layer      | What                                                                           | Changes when                                      |
-| ---------- | ------------------------------------------------------------------------------ | ------------------------------------------------- |
-| **Base**   | Whole page at fit-zoom display scale. An **array** of pieces.                  | Once on mount; again on rotation / resize         |
-| **Detail** | Visible rect inflated 25% each side, at display scale. An **array** of pieces. | Replaced wholesale on settle                      |
-| _Retiring_ | The previous detail set                                                        | Held across the swap, released on the next commit |
-
-The base is the entire anti-blank mechanism and is never **emptied** once populated —
-`PdfPageContent.base` is a set of pieces whose union is exactly the page rect, and a page
-inside the live window always has all of it. Every shipping PDF viewer has one — pdf.js's
-base canvas under `PDFPageDetailView`, Apple's `backgroundImageView` under
-`TiledPDFView`, androidx.pdf's `fullPageBitmap` under its `TileBoard`.
-
-**Why the detail is viewport-sized rather than whole-page:** `bytes = W·H·scale²·4`. An
-ARCH-D sheet at 1:1 on a DPR-3 phone is 154 MB; at 4× it is 2.46 GB. A viewport-sized
-detail is ~25 MiB **at every zoom**, because it tracks the screen and not the page.
-
-**Why both layers are arrays, and TWO caps decide it.**
-
-- `maxTextureDimension` (4096) is a **hardware** ceiling. Past it the texture upload
-  fails and the piece draws _nothing_ — not a soft failure. 4096 is the only
-  near-universal value. On this axis alone a phone never splits; a 1440×900 CSS browser
-  at DPR 2 needs 4320 px on an axis and splits into 2.
-- `maxPieceDimension` (1024) is a **memory** policy, and it is the bigger lever of the
-  two. One piece's bytes exist simultaneously as a platform bitmap, a transport copy, a
-  JS `Uint8Array` and an `SkData`, so the whole-flow transient peak scales with the
-  largest _single_ raster in flight, not with the epoch's total. The un-tiled 1755×3798
-  phone detail raster (25.4 MiB of pixels) measured a **~237 MiB** transient peak; at
-  1024 that is ~29.7 MiB, at 512 ~7.4 MiB, for the same resident bytes. The base gets
-  the same treatment, and it was the larger hole: `baseMaxPixels` allows 4 MP, ~4.8× a
-  whole 1024-tiled detail epoch.
-
-The effective cap is `min(maxPieceDimension, maxTextureDimension)`; the grid is also
-clamped to 32 pieces per axis so a nonsense cap degrades instead of planning millions of
-items. Pieces have no persistent identity and no cross-epoch reuse — this is a coarse
-split derived from a limit and a budget, not a tile pyramid.
-
-**Pieces overlap, never inset.** RN Skia's `<Image>` has no src-rect prop; both draw
-paths hardcode src to the whole image. `PdfRaster.docRect` is exactly the rect the bytes
-were rendered for.
-
-### How many pieces render at once
-
-`RasterizerCapabilities.maxConcurrentRenders` — the **backend's** number, defaulting to
-
-1. The controller runs that many lanes over the plan's items, so a backend that never
-   declared it keeps the strictly-sequential schedule it was written against, and one that
-   did gets `min(bound, plan.items.length)` lanes.
-
-Results are written into a **slot indexed by plan position**, never appended as they
-land: pieces overlap, so array order is draw order, and the base-swap test in `commit`
-compares fresh against mounted element by element. Completion order is not observable
-anywhere. One failing piece records one missing key and its siblings carry on; an
-**abort** is the only thing that stops a lane claiming more work, and a render that
-resolves after `destroy()` is dropped _before_ `ingest`, so no SkImage is minted that no
-content object exists to free.
-
-**It is not a lever at all on Android — it is a brake, and the numbers say why.** On an
-LG V60 (Snapdragon 865, API 33), a 6-piece detail epoch at the field's 131.25 device px/pt
-with 1024 px tiles, on the JSI transport and over a real field-measure drawing: the whole
-Java side is 116 ms at one lane and 153 ms at two, and the worst of 21 rounds is 137 ms at
-one lane against 238 ms at two. Android therefore declares **1**, and the note on
-`poolSize` in `src/rasterizer/android.ts` carries the four passes and the mechanism. On the
-base64 transport this used to read ~200 ms at one lane and ~150 ms at two, and that win was
-the base64 **encode** spreading across threads — the JSI path deletes the encode, and with
-it the only phase of a tile that was genuinely parallel. The app measured **595 ms per
-tile** on that old transport — so ~95% of what the user then waited for was a
-5,592,408-character base64 string crossing the bridge and being decoded on the JS thread,
-and the JS thread is one thread.
-
-That 595 was never the same tile, and the difference is NOT the ingest — `raster.ms` does
-exclude the mount, but the mount is 4 ms. Two things account for the gap, both measured:
-
-- **Payload.** `decodeBase64` is dead linear in payload at ~5.6 M chars/s, so per-tile cost
-  tracks the raster. The live session's 595 is a **2,674,748-char** tile (bridge 88.86 +
-  decode 478.73 = 567.6 ms), not the 5,592,408-char 1024² tile.
-- **Lane contamination.** Across 58 tiles of a live pan/zoom, `bridgeMs` is 83.4 ms p50 for
-  the first piece returned in an epoch and **399.6 ms p50 for every later one** — the later
-  ones spend that await watching the other lane's `decodeBase64` hold the single JS thread.
-  Any bridge figure averaged over all pieces is mostly the other lane's decode.
-
-So the 1024² tile measured **serially** is **1109.63 ms** (table below), and serial is the
-LOWER bound — a second lane only inflates it. Use the split-phase numbers; 595 is kept here
-only because it is what the pool sizing was originally reasoned from, and that reasoning is
-now retired: the JS-thread cost the second lane existed to pipeline is 0.02 ms on the JSI
-transport.
-
-AOSP serialises `PdfRenderer` behind a process-wide PDFium lock (`openPage` throughput is
-flat at 0.084 / 0.073 / 0.074 ops/ms across 1 / 2 / 4 threads, while an identical pure-Java
-workload scales 2.8×) — and the lock **convoys**, so contending for it makes each call
-slower rather than merely unparallel: four threads inflate per-tile `openPage` 16.2×,
-`render` 10.9× and `recycle+close` 33.6× on the drawing, and `render` 30.9× on a dense
-electrical schematic. With the encode gone a tile is 35.6% parallelisable work against
-60.2% PDFium-serialised, so there is no headroom for the convoy to eat into.
-
-Re-measured on the JSI path with `laneScheduleOnTheJsiTransport` — N lanes over one shared
-cursor of 6 plan items, 21 interleaved rounds each. Mean epoch wall clock relative to one
-lane, higher is better:
-
-| document                   | 2 lanes                      | 3 lanes                    | 4 lanes                    |
-| -------------------------- | ---------------------------- | -------------------------- | -------------------------- |
-| field-measure drawing (x4) | 0.82 / 0.81 / 0.95 / 0.76×   | 0.54 / 0.61 / 0.85 / 0.58× | 0.59 / 0.58 / 0.92 / 0.55× |
-| dense electrical schematic | 0.48×                        | 0.41×                      | 0.38×                      |
-| synthetic fixture          | 1.06–1.25× — see the warning | ~1.00×                     | ~1.00×                     |
-
-One lane is never beaten on a real document, and the tail — which is what a user sees as a
-stutter — is far worse with more. **The synthetic fixture inverts this verdict** and must
-not be used for it: with no `customer.pdf` pushed, `PdfCanvasPhaseTimingTest` falls back to
-a vector-rects-and-lines page whose `PdfRenderer.render` is 0.8 ms rather than 6.5 ms, which
-shrinks the serialised fraction. The fixture warns that it is an optimistic bound; this is
-the decision that proves it. **Android declares `poolSize` 1** — which is also one file
-descriptor and one parsed document rather than two.
-
-### A hole repairs itself
-
-An epoch records coverage from what it **produced**, so a piece lost to a backend failure
-or a budget refusal leaves a genuine hole in `EpochState.coveredRects` and the coverage
-predicate fires the moment it is consulted. It used to never be consulted: every entry
-point is host-driven, and a host whose viewport has stopped moving has no reason to
-settle — so the epoch published `settling: true` and stopped, and on the phone that is a
-low-resolution rectangle in the middle of a sharp page that never sharpens.
-
-A run that ends with pieces missing now arms **one re-evaluation** against the latest
-viewport (`{type: 'repair'}` in the diagnostics), through the same seam the min-interval
-back-off already uses. It is not a retry timer: it re-enters `evaluate`, so every
-predicate, the min-interval floor and the identical-plan guard still apply, and the plan
-asks for the same geometry-derived keys — every piece that landed is a cache hit and only
-the hole costs a render. The delay doubles from 250 ms to a 30 s ceiling and resets
-whenever the hole changes, so a permanently-broken piece costs a render a minute rather
-than four a second.
-
-This is also why `cacheBudgetBytes` was **not** raised. At high zoom a run pins four sets
-at its peak — the base, the mounted detail grid, the `retiring` grid one epoch older, and
-the grid being built — and that is what overruns the budget in the field. The pressure is
-transient by construction: the commit that publishes the partial epoch is the commit that
-releases the retired grid, so the re-evaluation has a whole grid of headroom and fills the
-hole in. A bigger number would paper over a run that is momentarily over by exactly one
-grid, and would have to grow again with the next screen size.
-
-## Policy
-
-Every cadence constant is a field on `RasterPolicy` with an exported default, because
-they are **derived, not measured**. A consumer with letter-size text documents on a
-DPR-1 display swaps two fields rather than forking the package.
+`viewport()` returns a plain `{visibleDocRect, scale}` snapshot. The package never reads the
+host's shared values; the host pushes the snapshot.
 
-```ts
-import {
-  DEFAULT_POLICY,
-  resolvePolicy,
-} from '@reekon-tools/react-native-pdf-canvas';
+### Viewport cadence
 
-usePdfLayer({document, policy: {sharpnessBand: 1.2, quietZoomMs: 400}});
-```
+The host is required to report when its viewport settles. The package cannot determine this
+independently: a `withDecay` fling animates for approximately 38 seconds at Reanimated's default
+deceleration, and no reliable means exists for a library to observe a consumer's animation from
+outside it.
 
-The one you should measure before shipping is **`minEpochIntervalMs`** (default 300, a
-placeholder). PDFKit's `draw(with:to:)` and Android's `PdfRenderer.render` are
-synchronous and uninterruptible once entered, so an abort only prevents the _next_ piece
-starting. Set it to your measured p95 raster time, or a user pinch-nudging while reading
-a dimension can supersede every render before it lands and never see detail at all.
-
-## Extension seams
-
-Four values you inject. No subclassing, no magic-string config.
-
-| Seam             | Shape                                                                                     |
-| ---------------- | ----------------------------------------------------------------------------------------- |
-| `PageRasterizer` | The backend. `createFakeRasterizer()` ships for tests and demos.                          |
-| `RasterPolicy`   | Every cadence constant, plus `planRasters` / `shouldReraster` exported as pure functions. |
-| `PdfPageLayout`  | `(pages: DocSize[]) => DocRect[]`. Ships `singlePage`, `continuousVertical`, `spread`.    |
-| `children`       | Skia's own idiom — colorFilter / imageFilter / shader nodes on `<PdfContentView>`.        |
-
-**Not extensible, deliberately:** the node tree (a consumer-injected component means a
-consumer-injected hook, which the loupe would duplicate), doc space (two conventions is
-how DPR gets applied twice), `SkImage` ownership (the package creates and disposes every
-image it draws), and gestures.
-
-## Gotchas encoded in this package
-
-Each of these is a real trap that was verified in RN Skia's source, and each is handled
-internally — listed so nobody "fixes" one back:
-
-- **`<Image>` defaults to `fit="contain"`.** Every raster is drawn `fit="fill"` into its
-  exact doc rect. Contain letterboxes and silently misregisters against the layers above.
-- **Mipmaps do not work.** `ImageCmd::draw` hardcodes `kStrict_SrcRectConstraint`, which
-  Skia's header says disables mipmaps and anisotropic filtering. Setting
-  `MipmapMode.Linear` silently does nothing. Minification is handled by _scheduling_.
-- **`sampling` is a string union**, mapped to module-level frozen constants. RN Skia's
-  `shallowEq` is reference equality, so an inline options object breaks memoization.
-- **A `<Paint>` child would draw the layer twice** — once at the declared paint and once
-  at the inherited one — and `paintDeclarations.clear()` runs on the first drawing, so it
-  would apply to the base and none of the detail pieces. Only _filter_ children work; the
-  component dev-warns otherwise.
-- **An epoch requires a React commit.** `PdfContent` is a new frozen object per epoch;
-  identity change _is_ the swap signal. A stable handle mutated in place would never
-  reach the Skia tree, because `prepareUpdate` returns null on reference equality.
-- **Retirement never owns a commit.** It is piggybacked onto the commit that mounts the
-  next epoch. A retire timer means a second full `stopMapper` → `visit()` →
-  `startMapper` over the _consumer's_ entire scene, frequently landing on the first frame
-  of the next gesture.
-- **Ingest is one copy on native, two on web.** `SkImages::RasterFromData` shares; web's
-  `CanvasKit.MakeImage` copies into a WASM heap that never shrinks.
-- **A mounted raster costs ~2× its pixels, and `PdfRaster.bytes` says so.**
-  `RasterFromData` _shares_ the `SkData`, which means it **retains** it for the image's
-  whole life, and the first GPU draw uploads a budgeted texture of the same dimensions.
-  `cacheBudgetBytes` is unchanged at 96 MB, so its meaning tightened: it covers half as
-  many pixels as it nominally used to. It always did — the cache just did not know, and
-  was choosing eviction victims on numbers wrong by 2×.
-
-## Backends
-
-| Platform | Engine                                                   | `id`                  | Status                     |
-| -------- | -------------------------------------------------------- | --------------------- | -------------------------- |
-| iOS      | `CGContextDrawPDFPage` for tiles, PDFKit for annotations | `ios-coregraphics`    | ✅ implemented — see below |
-| Android  | `PdfRenderer.Page.render(bitmap, null, matrix, …)`       | `android-pdfrenderer` | ⚠️ **partial** — see below |
-| Web      | `@embedpdf/pdfium` WASM in a worker                      | `web-pdfium`          | ✅ implemented — configure |
-| Any      | `createFakeRasterizer()`                                 | configurable          | ✅ implemented             |
-
-**The plan said "use PDFKit, not `CGPDFDocument`, because the latter does not render
-annotations". Both halves of that turned out to be true, and the conclusion was wrong.**
-`CGContextDrawPDFPage` really does draw the content stream without compositing annotation
-appearance streams — which is not a limitation, it is exactly what
-`RasterRequest.annotations: false` asks for, and it is what the controller passes for
-every tile. So iOS ships both and picks per render, which makes it the only backend that
-honours the flag in both directions. See "iOS" below.
-
-### Web — PDFium in a module worker
-
-**The engine is PDFium, and cross-engine parity is the whole argument.** Android's
-`PdfRenderer` _is_ PDFium, so a user measuring on a phone and a colleague measuring in a
-browser see the same pixels. pdf.js was measured and rejected: on the same doc, rect and
-scale the two engines disagree on **23,473 / 262,144 pixels (8.95%)**, 2,140 of them at
-full `maxDelta` 255, concentrated in glyphs.
-
-#### Wiring it up — the package builds no worker and no URL
-
-`configureWebPdfium` takes a **worker factory** and a **wasm locator**. It never
-constructs a `Worker` from a path of its own — not a hardcoded URL and not
-`new URL('./worker.js', import.meta.url)`, which works in some bundlers, some `base`
-settings and no SSR pass, and fails at _runtime in the host's production build_ when it
-fails at all.
+| Method                  | Called on                                          |
+| ----------------------- | -------------------------------------------------- |
+| `controller.suppress()` | Gesture begin                                      |
+| `controller.settle(v)`  | Gesture end, or an animation's completion callback |
+| `controller.hint(v)`    | Continuous input: wheel, trackpad, momentum        |
 
-```ts
-import PdfCanvasWorker from '@reekon-tools/react-native-pdf-canvas/worker?worker';
-import wasmUrl from '@embedpdf/pdfium/pdfium.wasm?url';
-import {configureWebPdfium} from '@reekon-tools/react-native-pdf-canvas/rasterizer';
-import {setDefaultRasterizer} from '@reekon-tools/react-native-pdf-canvas';
+`hint` is debounced behind a trailing quiet timer. `settle` takes effect immediately.
 
-setDefaultRasterizer(
-  configureWebPdfium({
-    createWorker: () => new PdfCanvasWorker(),
-    wasm: {url: wasmUrl},
-  }),
-);
-```
+### Hook placement
 
-Any other way of producing a **module** worker is equally fine
-(`new Worker(url, {type: 'module'})`); the entry is ESM and statically imports
-`@embedpdf/pdfium`. `wasm` also takes `{binary}` for a host with its own asset pipeline —
-at the cost of a 4.6 MB structured clone per `open()`, since transferring would neuter the
-host's copy.
-
-`@embedpdf/pdfium` is an **optional peer dependency**. Exactly one file imports it —
-`src/rasterizer/web/worker.ts`, behind the `./worker` subpath — so a consumer who ships
-native only never resolves it. Until `configureWebPdfium` is called,
-`getDefaultRasterizer()` returns the self-describing placeholder that fails at `open()`,
-so the pure core, the Skia ingest path and the fake backend keep working untouched.
-
-#### What it does
-
-- **`pageGeometry` is synchronous and loads no page.** Every page is measured once at
-  open with `FPDF_GetPageSizeByIndexF` + `EPDF_GetPageRotationByIndex`, both of which work
-  off the page dictionary. The size is the CropBox **after** `/Rotate` — measured: a
-  200x100 MediaBox with `/Rotate 90` reports 100x200 — so this package does no rotation
-  arithmetic of its own. (`EPDF_GetPageSizeByIndexNormalized` sounds like the one you want
-  and is the opposite: it normalises the rotation away.)
-- **An arbitrary doc rect at an arbitrary scale**, by describing the whole page at that
-  scale and sliding it: `FPDF_RenderPageBitmap(bmp, page, -round(x·s), -round(y·s),
-round(pageW·s), round(pageH·s), 0, flags)` into a tile-sized bitmap.
-  `FPDF_RenderPageBitmapWithMatrix` was measured byte-identical on every rect tried,
-  fractional device offsets included, and has a trap this form does not — **a NULL clip
-  renders nothing at all**, silently.
-- **The background is filled before PDFium draws**, always. PDFium composites onto the
-  destination and never clears it, and a fresh buffer is transparent _black_, which under
-  the app's annotation layers is a black page rather than a blank one.
-- **`format: 'rgba8888'`** via `FPDF_REVERSE_BYTE_ORDER`, and **`alpha: 'straight'`**.
-  The alpha is measured, not assumed: an antialiased opaque-white edge over a transparent
-  page reads `[255, 255, 255, 50]`, where premultiplied would be `[50, 50, 50, 50]`.
-  Android is `'premultiplied'`; that disagreement is why `RasterPixels.alpha` is a
-  required field rather than a constant in `ingest.ts`.
-- **`rowBytes` is read from `FPDFBitmap_GetStride`**, never computed. PDFium's own
-  allocator was tight at every width tried (1, 3, 7, 13, 1023, 1025) — measured, and still
-  not assumed, because a wrong stride shears an image instead of failing.
-- **`annotations` genuinely honours both settings** (`FPDF_ANNOT`), unlike Android, which
-  can only ever draw them. `usePdfDocument` silently downgrades the request when the
-  capability is false, so this is a claim that had to be true rather than optimistic.
-
-#### Tile registration: exact, with one measured caveat
-
-A tile must equal the same region of a larger render, because detail pieces **overlap**
-rather than abut and the base layer is tiled by the same cap. Measured here, against real
-PDFium:
-
-- **Axis-aligned geometry is bit-exact.** 10 rects x 7 scales (1 / 2 / 2.7 / 3 / 3.3 / 4 /
-  5.5), fractional and half-pixel device offsets included: **0 mismatching bytes,
-  `maxDelta` 0**, on a page inked edge to edge with fractionally-placed fills.
-- **A shallow DIAGONAL antialiased edge differs by one level.** 24 pixels of 9,600 on one
-  tile at scale 4; 558 bytes of 80,000 on a 0.7pt hairline grid. Always `maxDelta 1`, and
-  tracing the diagonal through the tile's **interior** rather than clustering at its
-  border, so it is not a clipping artefact. Invisible on screen, irrelevant to a seam --
-  but it qualifies the "0 / 262,144, maxDelta 0" figure this backend was designed around,
-  which was taken on a document that evidently had no such edge at that scale. The test
-  asserts `maxDelta <= 1` rather than skipping the case, so the exception stays on record.
-
-Two things that property **cannot** see, and are checked separately: it is RELATIVE, so a
-constant added to every render's device origin leaves it green (measured -- `+1` on
-`startX` passes the whole registration suite), and it says nothing about a page whose
-`/Rotate` is mishandled. A known doc-space edge at a known device pixel covers the first;
-the geometry tests cover the second.
-
-#### One worker per document, and why
-
-`close()` **terminates** the worker. The Emscripten heap grows one way — it never returns
-pages to the OS — so on web the _peak_ footprint of a session is permanent for the rest of
-the tab's life. Measured: 24 consecutive 512² tiles and 24 consecutive 1024² tiles leave
-the heap flat at 17.75 MiB, while **one** whole-page 2448x3168 render takes it to 32.625
-MiB and keeps it there. Growth begins at 2048², which is why `maxPieceDimension: 1024` is
-validated on web rather than merely inherited, and why **a whole page is never rendered in
-one buffer here**. Terminating is the only way to give a document's footprint back; the
-cost is one wasm instantiation per document, measured at 19 ms cold and 10 ms warm.
-
-#### `interruptibleRender: false`, honestly
-
-`FPDF_RenderPageBitmap` is synchronous and a worker reads one message at a time, so
-nothing can interrupt a render that has started. What an abort does is reject the caller
-immediately and stop a **queued** render from starting — which only works because the
-worker drains its queue one render per macrotask, leaving a window in which a `cancel` can
-land. PDFium's progressive API (`FPDF_RenderPageBitmap_Start` / `FPDF_RenderPage_Continue`
-with an `IFSDK_PAUSE`) is what would make the flag true, and is not used.
-
-#### What is proven, and where
-
-**PDFium runs in vitest under node** — `@embedpdf/pdfium`'s `import` build takes
-`wasmBinary` straight off disk — so `src/__tests__/web-rasterizer.test.ts` (**45 tests**)
-drives the real WASM: the tile-registration property at six rect/scale combinations
-including a fractional and a half-pixel device offset, absolute placement of a known
-doc-space edge, overlapping tiles agreeing inside their overlap, a padded stride forced
-through `FPDFBitmap_CreateEx`'s caller-owned-buffer form, both backgrounds, straight alpha,
-byte order, `/Rotate` for all four rotations, the CropBox, annotations on and off, and the
-error table. The worker's _logic_ is driven the same way, over an in-process channel that
-uses node's own `structuredClone` — transfer list honoured, so a transferred buffer really
-is neutered and "the client must copy a caller's `{data}`" is a claim a test can fail.
-`composition.test.ts` adds the join the two suites miss: a real PDFium raster ingested
-through the real `ingestRaster` and composited by real CanvasKit.
-
-Every assertion above that could be satisfied trivially was **mutation-checked** —
-`-round(x*s)` swapped for `round(-x*s)`, the background fill removed, `rowBytes` computed
-as `width * 4`, the byte-order and annotation flags dropped, the drain loop's yield
-deleted, the `{data}` copy removed. Two of those found real holes in the first draft of
-the suite (a fixture that left the tiles on blank paper, and a registration property that
-is blind to a uniform origin shift); both are fixed above.
-
-**Not proven:** nothing in this backend has run in a browser or in rock-desktop. What
-cannot run under node is the `self` binding in `worker.ts` (two lines), the `{url}` wasm
-form (Emscripten's `locateFile` wants a URL a browser can fetch), and real `Worker`
-termination — which is the step that actually reclaims the WASM heap, so the memory model
-above is reasoned rather than observed. Those need a QA pass on a real page. Structured
-cloning IS exercised, by node's own `structuredClone` with the transfer list honoured.
-
-**Two upstream RN Skia bugs a web host will hit, both diagnosed here and neither ours.**
-Recorded so the next person does not spend a day on them.
-
-1. **`dispose()` poisons the canvas element for reuse, which React StrictMode then reuses.**
-   `WebGLRenderer.dispose()` (`lib/module/views/SkiaPictureView.web.js`) ends with
-   `canvas.getContext('webgl2')?.getExtension('WEBGL_lose_context')?.loseContext()`.
-   StrictMode's dev double-invoke runs the effect as mount -> cleanup -> mount against the
-   SAME `<canvas>` node, and `getContext` returns the SAME, now-lost context object. It is
-   TRUTHY, so skia's `if (!this.contextHandle) throw` guard passes, and `MakeWebGLContext`
-   then reads `.rangeMin` off the `null` that `getShaderPrecisionFormat` returns for a lost
-   context: **`can't access property "rangeMin", a is null`**. Present in every release
-   **2.6.4 through 2.11.0** — reverting does not escape it. The GPU resources are already
-   freed by `releaseResourcesAndAbandonContext()` + `deleteContext()` immediately above, so
-   `loseContext()` only additionally breaks reuse; removing it fixes the crash and was
-   verified over four consecutive mount/dispose cycles on one element. rock-desktop carries
-   that as a yarn `patch:`.
-
-2. **A pending redraw can outlive the picture it was scheduled for.** The view defers
-   drawing (`redraw()` -> `requestAnimationFrame(flushRedraw)`, which reads
-   `pictureRef.current` when the frame fires), while the reconciler independently calls
-   `disposeRecording(recording)` -> `recording.lastPicture.dispose()`. Nothing clears
-   `pictureRef` or cancels the pending frame, so the rAF can draw a deleted picture:
-   **`BindingError: Cannot pass deleted object as a pointer of type sk_sp<Picture>`**. The
-   only `cancelAnimationFrame` is in an unmount effect, which does not help mid-session.
-
-   **Measured severity: dev-only.** With StrictMode it reproduces about 1 run in 3 under
-   aggressive wheel-zoom (4 GL context acquisitions per load); with StrictMode removed it
-   was 0 in 3 (2 acquisitions). It needs the double-mount's two concurrent recordings. It
-   is also non-fatal — the frame is dropped and the next redraw recovers; all pages still
-   painted in every run. **Deliberately NOT patched**: it is exactly the class of unsafe
-   effect StrictMode exists to surface, and guarding it in vendored code would hide a real
-   upstream defect for no production benefit. Anything that re-records often — like this
-   package's epoch swaps — makes it more likely without causing it; there are no frames
-   from this package in the stack.
-
-**Deliberately not solved here, and structurally the HOST's to solve: WebGL context loss.** A
-browser may drop the GPU context at any time — a background tab reclaimed, a driver reset,
-a GPU switch on a laptop — and RN Skia has no handling for it at **any** version in
-2.6.2–2.11.0. 2.7.0 went the wrong way: it REMOVED CanvasKit's clone-and-replace fallback
-in favour of a bare `throw new Error("Could not create surface")`. Nothing in this backend
-changes that. The rasters this package mints are CPU `SkImage`s, so the PDF bytes
-themselves survive; what does not survive is the surface they are drawn onto, and the
-failure presents as a thrown error from the host's `<Canvas>` rather than as anything a
-`PdfError` code can describe. A host that must survive it needs to remount its own canvas
-— there is no in-package recovery, and this note exists so that gap is stated rather than
-discovered.
-
-**Why deferring is a decision and not an omission**, verified rather than assumed:
-
-- **The package creates no GPU resources at all.** No `Surface.Make*`, no
-  `makeImageFromView`, no `GrDirectContext`, no GL call anywhere in `src/` — grep it.
-- **The images it caches are CPU rasters, so context loss cannot invalidate them.**
-  CanvasKit's `MakeImage` is `_malloc` + `HEAPU8.set` + `_MakeImage` (read from
-  `canvaskit-wasm/bin/canvaskit.js`) — a raster image, not a texture. They re-upload on the
-  next draw against whatever surface exists then.
-
-So there is nothing for this package to drop, re-create, or re-raster on a restore: the
-cache stays valid across the event. Adding recovery machinery here would be adding a
-listener for something that cannot corrupt any state we own. The real gap is RN Skia's, and
-it lives at the `<Canvas>` the host mounts.
-
-### iOS — CoreGraphics for tiles, PDFKit for annotations
-
-`ios/Sources/PdfCanvasCore/` is a **React-free Objective-C library**. It imports
-CoreGraphics, PDFKit and Foundation, and nothing from React Native, JSI or Nitro — so it
-is provable on a laptop with no device, no simulator and no CocoaPods:
-
-```bash
-cd ios && swift test        # 82 tests, ~1s
-```
+Both hooks must be mounted above the `<Canvas>`. React context does not cross the canvas
+boundary, as RN Skia mounts a separate reconciler for the Skia subtree, and a magnifier loupe
+constitutes a second canvas with its own copy of every hook. A cache instantiated inside the
+canvas is therefore created twice, concurrently, doubling tens of megabytes. Hoisting the hook
+and passing the same `content` object to both canvases is what makes a loupe free.
 
-That works because `ios/Package.swift` builds the same sources for **macOS**, where
-CoreGraphics and PDFKit exist and UIKit does not. A UIKit import anywhere in the core
-breaks that build immediately, which is when it should break. It is the same split
-`android/src/main` draws against `android/src/reactnative`, and it exists for the same
-reason: a bug in the binding must never be able to hide as a bug in rasterizing.
-
-`ios/Sources/PdfCanvasBridge/` is the React binding and the JSI slot store. It can only
-be built by the podspec — it needs `<jsi/jsi.h>` and `<React/RCTBridgeModule.h>` — and
-its only proof is a device session.
-
-#### Two engines, one backend, selected per render
-
-| `annotations` | Engine                              | Who asks for it                            |
-| ------------- | ----------------------------------- | ------------------------------------------ |
-| `false`       | `CGContextDrawPDFPage`              | every tile the controller plans            |
-| `true`        | `-[PDFPage drawWithBox:toContext:]` | `renderPage`'s default — thumbnails, print |
-
-**This makes iOS the only backend that honours `annotations: false`.** Android cannot
-(`PdfRenderer.Page.render` takes a render mode and no annotation switch, at any API
-level) and the web PDFium backend does not pass `FPDF_ANNOT`. So an app that draws its
-own copy of a PDF-embedded annotation on the Skia layer sees it **once on iOS and twice
-on Android** — a real cross-platform difference, and the right way round.
-
-The two are interchangeable geometrically, which is what makes choosing per render safe:
-on a page with no annotations they agree **byte-for-byte** — 0 of 1,280,000 bytes
-differing, maxDelta 0, at scale 4 over an 800×400 raster.
-
-#### What CoreGraphics and PDFKit actually do — measured, because the docs do not say
-
-Six behaviours, each measured before any of it was assumed. Four of them decided a line
-of code and two of them contradicted the plan:
-
-- **`CGContextDrawPDFPage` applies neither `/Rotate` nor the CropBox origin.** Both are
-  in `PdfCanvasPdfToDocTransform`. Drawing a `/Rotate 90` letter page with the rotation
-  in the transform puts the marker at the displayed top-right (correct); without it, at
-  the top-left, clipped.
-- **`-[PDFPage drawWithBox:toContext:]` applies BOTH — and
-  `-[PDFPage boundsForBox:]` does not.** On the same `/Rotate 90` page, `boundsForBox:`
-  returns `(0, 0, 612, 792)` while `drawWithBox:` draws a 792×612 landscape page. **The
-  widely-copied "flip by `page.bounds(for:).size.height`, then draw" recipe is therefore
-  correct only for unrotated pages** — flip a rotated one by that number and it lands
-  rotated, off-centre and clipped, with no error anywhere. The post-rotation height comes
-  from `PdfCanvasPageGeometry` instead.
-- **A tile is pixel-identical to that region of a whole-page render** — 0 of 41,984
-  pixels differing, maxDelta 0, for a 64×41pt tile at doc (37, 23) at scale 4. Spike S1
-  measured the same for Android's `PdfRenderer` and S3 for PDFium on web, so the
-  off-page-origin transform the whole detail layer depends on is now exact on **all
-  three** engines.
-- **Cost is flat in scale.** A 512² tile of a dense 540-line ARCH-D page costs
-  0.49 / 0.39 / 0.43 / 0.39 ms at scale 1 / 2 / 4 / 8. CoreGraphics clips rather than
-  rasterizing the page and discarding it — the premise "a viewport-sized detail raster is
-  constant in zoom" now holds on every engine this package has.
-- **Alpha is premultiplied, and it is not a choice.** `CGBitmapContextCreate` **refuses**
-  `kCGImageAlphaLast` and `kCGImageAlphaFirst` — straight alpha, either byte order —
-  returning NULL, while `premultipliedLast | 32Big`, `premultipliedFirst | 32Little` and
-  `noneSkipLast` are accepted. So an 8-bit RGBA context is premultiplied or alpha-less,
-  and alpha-less would break `background: 'transparent'`. **This closes the one cell the
-  spec's alpha table had marked NOT MEASURED.** An antialiased opaque-white edge over a
-  transparent page reads `[a, a, a, a]`, not `[255, 255, 255, a]`.
-- **`CGBitmapContextCreate` refuses a `bytesPerRow` that is not a multiple of 4** at 32
-  bits per pixel (`width * 4 + 1 / + 2 / + 3 / + 15` all NULL; `+ 0 / + 4 / + 8 / + 12 /
-  - 16 / + 64` accepted). This backend uses a tight stride, so it is unaffected — but row
-    alignment is expressible only in whole pixels if it ever pays for itself.
-
-#### Three things iOS does that Android cannot
-
-- **Encrypted documents work.** `CGPDFDocumentUnlockWithPassword` gives a clean
-  three-way answer, so `password-required`, `password-incorrect` and "opens and renders"
-  are all reachable. `PdfRendererPool.open` on Android **rejects any password** with
-  `unsupported`, because `android.graphics.pdf.LoadParams` landed at API 35.
-- **No poison guard is needed.** `PdfPreflight.java` exists because on API 24 a
-  `PdfRenderer` constructor that throws permanently poisons PDFium for the whole process.
-  CoreGraphics returns NULL and carries on — measured: a `%PDF-` header over garbage
-  fails as `corrupt` five times in a row, interleaved with good documents that open and
-  render fine, in one process. `PdfCanvasPreflight` exists only to tell "no such file"
-  from "no permission" from "empty" from "not a PDF", because
-  `CGPDFDocumentCreateWithURL` returning NULL is one signal for all four.
-- **`close()` while a render is in flight has no window.** `PdfRendererPool.close()`
-  closes leased renderers too and its own comment calls that "the only honest option".
-  Here a lease owns a CoreFoundation reference to its document, so `close` cannot free
-  one out from under a worker — non-blocking **and** no use-after-free.
-
-#### The transport — zero copies, which is one fewer than Android
-
-Same shape as Android and the same reason: neither the legacy bridge nor
-new-architecture codegen has a binary type. Measured by reading RN 0.86.2's own source,
-`TurboModuleConvertUtils::convertObjCObjectToJSIValue` handles `NSString`, `NSNumber`,
-`NSDictionary`, `NSArray` and `kCFNull` and returns `undefined` for everything else — so
-an `NSData` in a resolved promise arrives in JS as `undefined`.
-
-The fallback is base64. The default is a JSI `ArrayBuffer` over a slot, negotiated at
-construction by round-tripping eight known bytes, exactly as on Android.
-
-**What differs is the copy count.** Android's fast path costs one full-raster `memcpy`
-and cannot do better: a `Bitmap` owns its own pixel memory and there is no way to tell
-`PdfRenderer` where to put the pixels. `CGBitmapContextCreate` **takes the destination
-pointer as an argument**, so `PdfCanvasSlotSink` reserves the buffer and CoreGraphics
-writes the tile straight into the memory that becomes the JS `ArrayBuffer`. Zero copies,
-end to end.
-
-That is what the `PdfCanvasPixelSink` protocol is for, and it is also why the core can
-stay React-free: it knows how to render into a destination it is handed, and knows
-nothing about what a slot is.
-
-A sink may **refuse** its reservation, in which case the render falls through to the heap
-and the tile still goes out as base64. The refusal happens **before** anything is drawn,
-which is the structural advantage over Android — there, `nativeStoreFromBitmap` can only
-refuse after the raster already exists.
-
-#### Getting the runtime, on both architectures
-
-`installJsiTransport` is a blocking synchronous method, and both halves of that are
-load-bearing. Measured by reading RN 0.86.2:
-
-- `ObjCTurboModule::performMethodInvocation` runs a sync method through
-  `nativeMethodCallInvoker_->invokeSync`, and `ModuleNativeMethodCallInvoker::invokeSync`
-  is `work()` — inline, on the calling thread, which for a JS-initiated call is the **JS
-  thread**. That is the only thread where `bridge.runtime` is a live pointer.
-- **A sync method must return an object.** For a non-void, non-promise return the interop
-  layer does `void *rawResult; [inv getReturnValue:&rawResult]; result = (__bridge
-id)rawResult;`. A method declared to return `double` or `BOOL` would have its bits
-  reinterpreted as an object pointer. `RCT_EXPORT_BLOCKING_SYNCHRONOUS_METHOD` defaults
-  the return type to `id` for exactly this reason.
-
-The runtime itself comes from `self.bridge.runtime` through a forward-declared category,
-which is satisfied by `RCTCxxBridge` on the old architecture and by `RCTBridgeProxy`
-under bridgeless. That is not invented here: `@shopify/react-native-skia`'s
-`SkiaManager.mm` does the same thing, in the same app, on the same RN version.
-
-#### `maxConcurrentRenders: 1`, and why the Android evidence does not apply
-
-**CoreGraphics parallelises. Android's `PdfRenderer` does not.** On a dense 540-line
-ARCH-D page, 24× 1024px tiles at scale 4: **1.00x / 1.66x / 2.22x** at 1 / 2 / 4 lanes
-(Apple-silicon Mac, `swift test`). Android measures **0.82x / 0.54x / 0.59x** on a real
-drawing, because AOSP serialises `PdfRenderer` behind a process-wide PDFium lock that
-_convoys_.
-
-So the reason Android declares one lane is not a reason iOS should. **iOS still
-defaults to one**, because the measurement above is a Mac with many cores and a fixture
-whose tiles cost about a millisecond — and the Android note records exactly this mistake
-being made in the other direction, where a synthetic fixture measured 1.06x–1.25x and a
-real drawing measured 0.82x. Raise it with `createIosRasterizer(native, {poolSize: 2})`
-after measuring on a device with a real drawing.
-
-#### What is proven, and where
-
-**Proven on a Mac, by `swift test`:** 102 tests over the doc-space contract (quadrant
-placement, tile equivalence, overlap agreement, flat cost in scale), the two engines and
-their agreement, all four rotations, offset and overhanging crop boxes, the white
-pre-fill and the transparent case, premultiplied alpha, stride and format, per-page
-content, the eight error codes, encryption in both engines, preflight's header window,
-the sink contract (reserve/publish/abandon, refusal, idempotent release), cancellation at
-each checkpoint, lane correctness against a serial render, and close-while-rendering.
-
-That count includes **the real slot store**, not a test double. `PdfCanvasSlots.mm`
-guards `<jsi/jsi.h>` with `__has_include` — the same split
-`android/src/jsi/cpp/pdfcanvas-jsi.cpp` draws — so the storage compiles without React
-Native and the transport's own failure modes get tested: that slot bytes are
-**byte-identical to the heap path for a real raster**, that a slot is taken exactly once,
-that a reserved buffer is unreachable from the store until it is published (the
-reload-lands-mid-draw case), and that every abandon path frees. Those are leaks and
-use-after-frees rather than wrong pixels, so a device session cannot show them — 48 tiles
-rendering correctly while the store leaked every superseded raster would look identical.
-
-**Proven in vitest:** the TypeScript adapter, including that both native backends accept
-the same fake native module and marshal the same request to byte-identical pixels.
-
-**Proven on device** — an **iPhone 14 Pro Max, iOS 18.7.8**, inside a React Native
-0.86.2 / Expo SDK 57 app running the **new architecture (bridgeless, Fabric)**:
-
-- Autolinking installs the pod (`Installing PdfCanvas (0.1.0)`), and
-  `NativeModules.PdfCanvas` resolves with every method — including the two
-  **blocking synchronous** ones, through the TurboModule interop layer.
-- `installJSIBindingsWithRuntime:callInvoker:` is called and installs
-  `__pdfCanvasTakePixels`, and `negotiateTransport` then **armed the fast path**: the
-  eight probe bytes round-tripped exactly. This is byte-fidelity of the transport,
-  measured on the device rather than argued from the source.
-- **48 real tiles rendered end to end** through the JSI transport into `SkImage`s, in
-  a live `PdfContentView` under the app's own pan/zoom. Every one reported
-  `chars=0` (nothing was stringified), `decode=0` and `tight=true`, and every byte
-  count was exactly `round(docRect × scale) × 4` for its rect. Zero errors, zero
-  fallbacks to base64.
-- **Timings, 48 tiles at scale 13.31 device-px/pt (~0.74 Mpx each):**
-
-  | Phase       | p50      | p95      | max      |
-  | ----------- | -------- | -------- | -------- |
-  | `bridgeMs`  | 12.79 ms | 42.03 ms | 50.01 ms |
-  | `decodeMs`  | 0.00 ms  | 0.01 ms  | 2.62 ms  |
-  | `ingestMs`  | 0.61 ms  | 7.69 ms  | 23.67 ms |
-  | **`total`** | 13.91 ms | 43.09 ms | 60.32 ms |
-
-  `bridgeMs` is the whole round trip including the native render. `decodeMs` is the
-  term the transport deletes — on Android's base64 path the same term was **1005 ms**
-  for one 1024² tile. **This is the `p95` raster time the spec lists as "still open"
-  for iOS**, and at 43 ms it is far below the 250 ms the quiet-timer default assumes.
-
-**Proven by looking at it, on the host.** `PreviewTests.swift` writes what the
-rasterizer produced to PNG — the ARCH-D base, one detail tile, the doc-space quadrants,
-all four rotations, an offset crop box through both engines, the annotation flag both
-ways, a transparent background, and a page from the middle of a multi-page document.
-It is deliberately **not** a golden-image test: byte-exact references churn on every OS
-update, and every property worth asserting is asserted numerically elsewhere. What it
-adds is that somebody can open the files and see that a page looks like a page.
-
-**Still not proven:** the combination of the two — a tile drawn by this backend,
-composed by `PdfContentView`, on a real screen — because there is no screenshot or tap
-automation for a physical device in this toolchain, and driving a dev-client Simulator
-needs synthetic taps that need an accessibility grant. Each half is covered separately
-(the rasterizer by the PNGs above, the composition by `composition.test.ts`, which
-renders the real `PdfContentView` through the real RN Skia reconciler into a CanvasKit
-surface). Also unproven: cancellation and the error-code mapping _across the bridge_ —
-both covered in the core, neither exercised from JS — and a RELEASE bundle, since every
-figure above is the dev bundle over Metro.
-
-### Android — what is and is not proven
-
-**Proven on device:** the rasterizer core and the raster transport. **57 instrumented
-tests** pass on an LG V60 (API 33) — tiling, the white pre-fill, page geometry, byte order
-and stride, pool concurrency, cancellation, the error codes, and the eleven that hold the
-JSI transport to base64's bytes. The core 33 of them have also been run on **API 24, 31 and
-33**; the transport 11 have so far only been run on 33.
-
-**Also proven on device:** the JS↔native bridge, on an **API 33 x86_64 emulator**, inside a
-React Native 0.86 / Expo SDK 57 app running the **new architecture (bridgeless, Fabric)**.
-Autolinking registers `PdfCanvasPackage`, and `NativeModules.PdfCanvas` resolves with all
-six methods (`open`, `render`, `cancel`, `close`, `rotationSupport`, `isBackendPoisoned`)
-even though `global.__turboModuleProxy` is `undefined` — the interop layer does backfill a
-legacy module, so `NativeModules` rather than `TurboModuleRegistry` is the correct lookup.
-A two-page document opened (`pageCount: 2`, geometry `200x200` and `300x150`,
-`rotationSupport: supported`). A 100x100pt tile at doc-space origin (50, 50), scale 2, came
-back `200x200`, `rowBytes: 800`, `format: rgba8888`, 160 000 bytes, in 251 ms; its four
-quadrant samples were exactly `[255,0,0,255]`, `[0,255,0,255]`, `[0,0,255,255]`,
-`[0,0,0,255]`, which pins the doc-space origin, the scale, the row order and the channel
-order at once. `imageFromPixels` produced a 200x200 `SkImage` (`colorType` RGBA_8888,
-`alphaType` Premul) whose `readPixels` round-tripped the same values.
-
-**Still not proven:** cancellation, pool concurrency and the error-code mapping _across the
-bridge_ — all proven in the core, none of them exercised from JS; the JSI host function
-itself, which no build the instrumented suite can run even contains (see below) and which is
-therefore covered only by the negotiation probe at runtime and by the device sessions in
-`app/dev-pdf-canvas-probe.tsx`; a RELEASE bundle, since every JS-side figure here is the dev
-bundle over Metro; and all of iOS and web.
-
-`android/` is a **React-free Android library**. The rasterizer
-(`android/src/main/java/tools/reekon/pdfcanvas/`) imports nothing from React Native or
-Nitro, so it can be proven on a bare emulator with no app around it:
-
-```bash
-export JAVA_HOME="/path/to/Android Studio/jbr"   # JDK 17
-cd android && ./gradlew connectedDebugAndroidTest # runs on every attached device
-```
+## API reference
 
-The React binding lives in `android/src/reactnative/java/` and joins the source set only
-when a host app autolinks the package — see the `standalone` flag in
-`android/build.gradle`. That is what keeps the tested half testable.
-
-Three things the platform does that the docs do not mention, all measured on API 24, 31
-and 33:
-
-- **A tile is pixel-identical to the same region of a larger render** —
-  `setScale(s,s); postTranslate(-x·s, -y·s)`, 0/262144 mismatching pixels on every level.
-  Tiling on the platform renderer works.
-- **`/Rotate` is not applied when rendering on API 24.** Page DIMENSIONS swap, the content
-  does not, and it lands clipped. 31 and 33 are correct. There is no way to read a page's
-  `/Rotate` below API 35, so this cannot be compensated for — the backend probes the
-  device and reports `rotationSupport` instead of pretending.
-- **A `PdfRenderer` constructor that THROWS permanently poisons PDFium on API 24.** One
-  failed open plus a garbage collection, and the next successful open segfaults in
-  `CPDF_Document`. `PdfPreflight` keeps bad files away from the constructor and a latch
-  refuses rather than crashing if one gets through.
-
-#### The transport — two of them, negotiated at runtime
-
-Pixels used to cross the bridge as **base64**, because neither the legacy bridge nor
-codegen has a binary type. That is now the **fallback**. The default is a JSI
-`ArrayBuffer`:
-
-1. The render worker finishes a `byte[]` and copies it into C++-owned memory
-   (`PdfCanvasPixelBridge.nativeStore`) under a monotonic **slot** id. This is the only
-   copy the transport adds, it is 4 MiB of `GetByteArrayRegion`, and it happens on the
-   worker — not the JS thread.
-2. The promise resolves with `pixelsSlot` instead of `base64`.
-3. JS calls `__pdfCanvasTakePixels(slot)`, a host function installed from C++, which wraps
-   that same memory in a `jsi::ArrayBuffer` via `jsi::MutableBuffer`. **No copy**, and the
-   buffer is exactly the raster, so `isTightBuffer` holds by construction.
-4. The slot map drops its reference on the take, so the ArrayBuffer is the sole owner and
-   Hermes's GC frees the vector.
-
-Three lifetime details that are the difference between this and a use-after-free:
-
-- **The slot counter is PROCESS-WIDE (`static`), because the slot map is.** The map is one
-  `std::unordered_map` in `pdfcanvas-jsi.cpp`; a per-instance counter starting at 1 would
-  hand the same id to two `PdfCanvasModule`s — RN builds a fresh set of native modules for
-  every reload — and the second store would silently replace the first's buffer, so that
-  module's take would return ANOTHER tile's pixels. A wrong image, not an error.
-- **`nativeStore` converts its C++ failures into Java throwables.** It is the only
-  allocating method on the surface, `std::bad_alloc` for a 4 MiB raster is reachable, and a
-  C++ exception unwinding out of a JNI method reaches `std::terminate` — so the documented
-  "a store that fails falls that tile back to base64" only exists because the throw is
-  translated (`OutOfMemoryError`) rather than allowed to escape.
-- **`invalidate()` clears `jsiEnabled` FIRST, then drains.** `shutdownNow` cannot interrupt
-  a worker that is inside `PdfRenderer.render`, so it will reach `putPixelsSlot` after
-  `nativeReleaseAll` has run; with the flag already off it encodes base64 into a dead
-  promise instead of parking a raster nothing can ever take.
-
-Nothing downstream pins the buffer: `Skia.Data.fromBytes` is `MakeWithCopy`, so the cache
-holds SkImages and the redeemed ArrayBuffer is garbage the moment ingest returns.
-
-**It is proven before it is used, and it degrades in silence-free ways.** `installJsiTransport`
-parks eight known bytes and JS compares them against its own copy of the constant
-(`TRANSPORT_PROBE_BYTES`); only a byte-for-byte match calls `enableJsiTransport(true)`. A
-build with no `libpdfcanvasjsi.so`, an app binary predating the methods, a runtime that
-refuses a host function or an engine that cannot back an ArrayBuffer with external memory
-all leave the flag off and every render goes back to base64 — and the negotiated result is
-reported as `RasterizerCapabilities.transport`, with the per-tile one as
-`RasterPhaseTimings.transport`, precisely because a silent fallback is how a large speedup
-ships as none.
-
-**Why not Nitro.** `react-native-nitro-modules` was the first candidate — BOLDR already has
-it at 0.35.2 and the app is bridgeless — and reading its source is what ruled it out.
-`cpp/core/ArrayBuffer.hpp` in the installed copy declares
-`class ArrayBuffer : public jsi::MutableBuffer`, with `wrap(data, size, deleteFn)` and
-`copy(data, size)`: Nitro's ArrayBuffer IS the primitive this file reaches directly. So
-adopting it would buy the same `jsi::MutableBuffer` at the price of a peer dependency every
-consumer must install, a `find_package(NitroModules)` prefab that only resolves in an
-autolinked build, and — unless the spec is hand-written — the `nitrogen` toolchain (not
-installed here) plus checked-in generated sources.
-
-Two of those are fatal rather than merely unwelcome. The package's instrumented suite runs
-from a **standalone** `./gradlew connectedDebugAndroidTest` with no React Native and no
-consumer `node_modules` anywhere on the classpath; a Nitro HybridObject cannot compile in
-that build at all, so the 11 tests that prove the transport's byte fidelity would need a
-whole app built around them to run. And a codegen TurboModule is worse still: the spec
-language has no `ArrayBuffer` return type to express.
-
-So the transport is ~40 lines of plain JNI + JSI in `android/src/jsi/`, behind one `#ifdef`
-so the identical storage code compiles with and without `jsi.h`, plus a branch in
-`PdfCanvasModule.render`. No new dependency, optional or otherwise; the core does not know
-it happened.
-
-#### What that base64 hop cost — measured, not estimated
-
-The Android backend fills `RasterPixels.timings` and the controller re-emits it as a
-`raster-phases` diagnostic, so the per-tile cost is split rather than totalled.
-
-Measured on an LG V60 (Snapdragon 865, API 33, dev bundle), five **serial** 1024x1024
-tiles at 131.25 device px/pt — 4 194 304 bytes, 5 592 408 base64 characters — medians:
-
-| term                                                       | ms          | share     |
-| ---------------------------------------------------------- | ----------- | --------- |
-| bridge round trip (string marshalling + ALL the Java work) | 100.07      | 9.0%      |
-| `decodeBase64` on the JS thread                            | 1005.46     | 90.6%     |
-| `Skia.Data.fromBytes` + `Skia.Image.MakeImage` (`ingest`)  | **4.09**    | **0.37%** |
-| **per tile**                                               | **1109.63** |           |
-
-The Java half of that bridge figure is 27.5 ms p50 (`PdfCanvasPhaseTimingTest`), of which
-19.88 ms is the base64 ENCODE — so **pure string marshalling is ~72.6 ms**, and the
-un-removable Java work is ~7.6 ms.
-
-Four things follow, and each contradicts something that tends to get assumed:
-
-- **The decode is the cost. The copies are not.** `decodeBase64` runs at ~5.6 M chars/s in
-  Hermes and is dead linear in payload. Skia's two copies together are 4 ms for the same
-  4 MiB. The term no transport change can remove is **0.37%** of the tile.
-- **`raster.ms` does NOT include the ingest.** The `raster` diagnostic is emitted before
-  `ingest()` is called (see `controller.ts`), so it is `handle.render` alone — bridge plus
-  decode. Any "end to end per tile" figure taken from it has the mount missing entirely,
-  and subtracting the Java time from it leaves marshalling + decode, not "everything
-  between the byte[] and the SkImage".
-- **`bridgeMs` is only meaningful for the first piece of an epoch.** It is wall time across
-  an `await`, and the pool ran two lanes when this was captured, so every later piece spent
-  that await watching the other lane's decode hold the JS thread: over 58 tiles of a real
-  pan/zoom session the contaminated pieces read 399.6 ms p50 against 83.4 ms for the clean
-  ones. At `poolSize` 1 there is no other lane, so the contamination is gone — which is a
-  side benefit of that change and not a reason for it.
-- **`tighten()` is already a no-op here.** `tight` is true on every sample, because
-  `decodeBase64` allocates an exact buffer. A transport handing back a tightly-sized
-  `ArrayBuffer` removes no copy that is being paid today — it preserves a property this
-  path already has.
-
-The probe (`app/dev-pdf-canvas-probe.tsx` in the BOLDR app) shows the split live, logs each
-tile as `PDFCANVAS-PHASES`, and carries two benches that remove the interleaving: `Tile`
-renders single tiles serially through the real backend (the table above), and `Bench` times
-`decodeBase64` and the Skia calls on synthetic buffers of exactly those sizes. The two
-agree to 0.6% on the decode (999.92 vs 1005.46 ms), which is what makes the synthetic one
-usable when a device session cannot be driven.
-
-#### What the transport actually bought — measured on device, both paths
-
-The probe's `Tile` bench renders **the same tile on both transports, back to back, on one
-handle**, five serial renders each, medians — because a speedup quoted against a number
-from a previous session on a previous build is two numbers, not a ratio. LG V60, API 33,
-dev bundle, 1024x1024 device px at 131.25 devpx/pt (4 194 304 bytes):
-
-| term                       | `jsi-arraybuffer` | `base64`    |
-| -------------------------- | ----------------- | ----------- |
-| bridge round trip          | **13.88**         | 56.01       |
-| payload decode / slot take | **0.02**          | 997.50      |
-| `ingest` (Skia)            | 4.18              | 4.09        |
-| **per tile**               | **17.75**         | **1057.60** |
-| payload characters         | **0**             | 5 592 408   |
-| `tight`                    | true              | true        |
-| FNV-1a of the raster       | `ac5c9dc5`        | `ac5c9dc5`  |
-
-**59.6x**, and the two rasters are byte-identical. Three consecutive runs with nothing else
-in flight gave 59.57x / 60.80x / 54.34x. A fourth run taken while the screen was still
-repairing an epoch read 116x — the contamination inflates the BASE64 half (its bridge went
-56 -> 1348 ms, because that await now watches the other lane's decode), so the honest figure
-is the quiet one and the noisy one is quoted here only to say why it is not.
-
-**Replicated in a later session, on a cold JS reload and a different document** (6-page
-lease, same 1024x1024 tile at 131.25 devpx/pt): fast bridge 15.68, take 0.02, `ingest`
-3.71, **19.41 ms per tile**, `chars` 0, `tight` true, and the digest `ac5c9dc5` again —
-identical to the base64 half of that run. Its base64 half WAS contaminated (bridge
-1230 ms, so it read 108x) which is why the ratio is not quoted from it, but `decodeMs` is
-a synchronous loop between two clock reads with no await inside it, so contamination
-cannot touch it: **868.46 ms**, against 997.50 here. The honest range across sessions is
-therefore ~48-60x, and the term that sets it is the decode, which is why the same digest
-appearing on both halves matters more than the ratio's last digit.
-
-The transport's own new cost is the one thing it ADDS, and it is smaller than the encode it
-deletes: `nativeStore`'s `GetByteArrayRegion` of 4 MiB is **1.67-1.78 ms** against
-**19.23-19.96 ms** for `Base64.encodeToString` of the same buffer
-(`PdfCanvasJsiTransportTest.measuresTheStoreCostAgainstTheBase64EncodeItReplaces`), and it
-runs on the render worker rather than the JS thread.
-
-**The profile inverts, as the split phase predicted.** Over a real 134-tile pan/zoom session
-on the fast transport: bridge 23.48 ms p50, take 0.02 ms, `ingest` 3.52 ms, **27.14 ms per
-tile p50** (min 14.82, max 168.82), and `payloadChars` was **0 on all 134** — no tile
-silently fell back. `ingest` is now **13%** of the median tile against 0.37% before, while
-being the same 3-4 ms it always was. That is the point at which Skia's two copies become
-worth a second look, and not before.
-
-**`tighten()` is a no-op on this path, confirmed rather than assumed.** `tight` was true on
-every sample of both transports — 15 bench renders and all 134 live ones. The redeemed
-ArrayBuffer is exactly the raster (`byteOffset` 0, `byteLength` = `buffer.byteLength` =
-4 194 304), so `Skia.Data.fromBytes` — which ignores `byteOffset`/`byteLength` and copies
-the whole buffer — copies the raster and nothing else. The transport PRESERVES a property
-the base64 path already had; it does not remove a copy that was being paid.
-
-## Versions and peer ranges
-
-**Every `devDependency` that the app also ships is pinned EXACTLY.** Not a caret — a
-caret is what went wrong. `"@shopify/react-native-skia": "^2.6.2"` had quietly resolved
-to **2.11.0** here while BOLDR pinned **2.6.2**, so the whole suite, every offscreen
-CanvasKit pixel test included, had been validating a version the app does not ship. A
-library validated against a floating version is not validated. The pinned set is
-`@shopify/react-native-skia 2.11.0`, `react 19.2.3`, `react-native 0.86.2`,
-`react-native-reanimated 4.5.3`, `@types/react 19.2.17`.
-
-Two of those are the app's **intended** versions, not its present ones: BOLDR pins skia
-**2.6.2** and reanimated **4.5.1** today. Re-check this table when it moves.
-
-`@types/react` has no 1:1 mapping onto a React patch; 19.2.17 is what BOLDR's own
-`~19.2.4` resolves to today, so both trees typecheck against the same React types. That
-is a floating range on the app's side, so it will drift.
-
-### `engines` and `@types/node`
-
-`node` is copied verbatim from BOLDR's own field (`^20.19.4 || ^22.13.0 || >=24`) rather
-than invented, replacing a bare `>=18`. **Nothing in the package or its tests depended on
-Node 18 semantics, so nothing changed** — and raising the floor legitimises less than it
-looks like it should: `structuredClone` (17.0), `AbortSignal.timeout` (17.3), global
-`fetch` (18.0) and `node:module`'s `createRequire` (12.2) were _all_ already available on 18. The only one of them this package actually uses is `createRequire`, in the pixel
-harness (`src/__tests__/support/canvaskit.ts`).
-
-`@types/node` tracks the **lowest** supported major (20.x), not the v24 the dev machine
-runs, so `tsc` rejects a Node 22+/24-only API the declared floor could not provide.
-
-### Why the skia peer floor is `>=2.8.0`
-
-It was **unsatisfied by BOLDR when it was set** (the app pinned 2.6.2), and that was the
-point: once the floor was enforced (next section), the app's `yarn install` failed until
-skia was bumped. It has since been bumped to 2.8.0, so the app satisfies it and the gate
-exits 0 — but the bump is not OTA-safe, because 2.8.0 moves the prebuilt binaries into
-separate packages and therefore needs a native rebuild.
-
-**Exactly one requirement sets it, and it landed in exactly 2.8.0.** Not 2.7.0 — an
-earlier note here hedged between the two, and hedging is how a fix gets misattributed.
-Verified by extracting `lib/module` from every published tarball from 2.6.2 to 2.11.0:
-
-| Signal                                       | 2.6.2 | 2.6.9 | 2.7.0 | **2.8.0** | …   | 2.11.0 |
-| -------------------------------------------- | ----- | ----- | ----- | --------- | --- | ------ |
-| `sksg/Container.web.js` `dispose` call sites | 1     | 1     | 1     | **6**     | 6   | 6      |
-| `sksg/Recorder/FrameScope.js` exists         | no    | no    | no    | **yes**   | ✓   | ✓      |
-
-Below it the web reconciler leaks a CanvasKit `Paint` per drawn tile per frame into the
-Emscripten heap — which grows **one way**, because Emscripten never returns pages to the
-OS. This package's entire memory policy is built on that asymmetry: base _and_ detail
-tiled to `maxPieceDimension`, `RETIRING` released on the next commit rather than kept,
-resident bytes booked at 2x. All of it exists because **peak** simultaneous raster bytes,
-not average, sets a tab's floor for the session. A reconciler that leaks every frame makes
-that policy unenforceable, so `<2.8.0` is a configuration in which the package's stated
-contract cannot hold.
-
-**And nothing after 2.8.0 is required, so the floor is not 2.11.0 just because that is
-what the dev tree pins.** The web backend is being built against 2.11.0, which invites
-"then require 2.11.0" — but every file on the web draw path is **byte-identical** from
-2.8.0 through 2.11.0: `sksg/Container.web.js`, `Reconciler.js`, `HostConfig.js`,
-`Recorder/FrameScope.js`, web `JsiSkDataFactory.js`, and `types/Image/ColorType.js` /
-`AlphaType`. Web `JsiSkImageFactory.js` differs only in that 2.10.1 renamed two sibling
-methods this package never calls (`MakeImageFromTexture` → `MakeImageFromNativeTexture`,
-`MakeTextureFromImage` → `MakeNativeTextureFromImage`); the `MakeImage` body `ingest.ts`
-depends on is unchanged. `canvaskit-wasm` is pinned **0.41.0** by every release in the
-range, so no CanvasKit-side improvement can justify a higher floor either. The other
-changes in the range are a Reanimated shared-value-**selector** feature (2.11.0,
-`sksg/utils.js` + `Recorder/Core.js` — this package contributes zero shared values), WebGPU
-device-API renames, and `Platform.web.resolveAsset` handling an Expo interop object (asset
-loading; this package never loads an asset).
-
-**The floor is a memory-correctness claim, not a compile constraint, and it is worth being
-clear about which.** The full suite — the offscreen CanvasKit pixel tests
-included — and `tsc --noEmit` both pass against skia **2.8.0** _and_ against **2.6.2**,
-measured by re-pinning a copy of this tree and reinstalling. So the native path genuinely
-works on 2.6.2; BOLDR ships it. A peer range is nonetheless a claim about correctness
-rather than about compilability, and understating one is exactly how the 2.6.2-vs-2.11.0
-skew survived unnoticed.
-
-The other three floors moved for a different and duller reason: they were **dead ranges**.
-Every skia release in range peers `react >=19.0` and `react-native >=0.78`, so `react ^18`
-and `react-native 0.74`–`0.77` were never satisfiable alongside the skia peer sitting next
-to them; skia 2.8.0 peers `reanimated >=3.19.1`, so `>=3.0.0` likewise named versions no
-host could reach. Note where reanimated 4 actually became mandatory for skia: **2.10.0**,
-which is where the peer becomes `reanimated >=4.0.0` plus `react-native-worklets >=0.7.0`
-(`npm view @shopify/react-native-skia@2.10.0 peerDependencies`) — _not_ 2.11.0, as an
-earlier version of this section said. That combination is skia's business, not this
-package's, but it is why `>=2.8.0` and `reanimated >=3.19.1` can sit next to each other
-here and still describe a reachable configuration.
-
-### Enforcing the floor — and what the ecosystem actually does
-
-**Short answer to "is it standard for a package to fail `yarn install` on a too-low
-peer?": no.** Measured across all **2020** packages installed in BOLDR, exactly **six**
-declare any `preinstall`/`install`/`postinstall` hook — `@firebase/util`, `esbuild`,
-`@sentry/cli`, `@shopify/react-native-skia`, `protobufjs`, `unrs-resolver` — and **none of
-them checks a peer's version**. Every one is downloading or wiring up its _own_ native
-asset (skia's `postinstall` is `node scripts/install-libs.js`, which copies its prebuilt
-libs). Zero use `preinstall`.
-
-What packages with hard native peers do instead is **declare + assert at runtime**:
-
-| Mechanism                     | Who does it                                                                                  | Does it fire?                                                                                   |
-| ----------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `peerDependencies`            | universal                                                                                    | yarn 1 **warns**; npm (measured 8.19.2) hard-errors `ERESOLVE`; **never** evaluated for `link:` |
-| runtime `__DEV__` **throw**   | skia (`sksg/Container.native.ts`), reanimated (`assertWorkletsVersion`)                      | yes, on first use — the only layer that catches a drift no install ran                          |
-| production `console.error`    | skia, once, then degrades to `StaticContainer`                                               | yes                                                                                             |
-| a shipped semver check script | reanimated (`scripts/validate-worklets-version.js`, `semver` as a real `dependencies` entry) | yes, called from the runtime assert — **not** from an install hook                              |
-| `postinstall` peer check      | **nobody**                                                                                   | —                                                                                               |
-
-Two details of reanimated's script are worth copying and are copied here: it **skips
-prerelease versions entirely** ("The user knows what they're doing"), and it returns
-`{ok: true}` when no compatibility entry matched — i.e. it **fails open on "cannot tell"**.
-
-**What yarn 1.22.19 actually runs**, measured with a probe package declaring every hook,
-installed both ways:
-
-|                        | `preinstall` / `install` / `postinstall` | `prepare` | `bin` in `.bin` | package's `peerDependencies` | consumer `postinstall` can fail the install |
-| ---------------------- | ---------------------------------------- | --------- | --------------- | ---------------------------- | ------------------------------------------- |
-| tarball / registry dep | **all three run**                        | no        | **yes**         | **warns**                    | yes, exit code preserved                    |
-| `link:` dep (BOLDR)    | **none run**                             | no        | **no**          | silent                       | yes, exit code preserved                    |
-
-So for BOLDR **nothing inside this package can run itself**, and the bin name does not
-exist. That also **corrects an earlier claim in this README**: `prepare` does _not_ build
-on install for a linked consumer. It builds when you run `yarn install` in _this_ tree.
-Keep `yarn dev` running while iterating; a consumer gets whatever `dist/` happens to hold.
-
-Hence four layers, weakest to strongest:
-
-1. **`peerDependencies`** — the declarative contract, and the only real gate for a
-   registry consumer. `package.json`'s `//peerDependencies` key is the **single source of
-   truth for the floor**: the other layers parse `>=2.8.0` out of it rather than restating
-   it, so a bump is one line. Keep it a bare `>=x.y.z` — the checker refuses to guess at a
-   union or a caret and degrades to a warning, and a test asserts the shape.
-2. **`scripts/check-skia-peer.mjs`**, exposed as `bin: pdf-canvas-check-skia` and runnable
-   as `yarn check-peers`. Plain `.mjs` with no dependencies, because under `link:` neither
-   `dist/` nor a declared dependency exists at install time.
-3. **the consumer's `postinstall`.** BOLDR chains it as
-   `patch-package && node node_modules/@reekon-tools/react-native-pdf-canvas/scripts/check-skia-peer.mjs`
-   — invoked **by path**, because that form works for a `link:` and a tarball consumer
-   alike, whereas the bin name only exists for the latter.
-4. **a dev-only runtime warning** on the first raster (`src/peer-check.ts`, called from
-   `imageFromPixels`). The only layer that catches a drift no install ran. It **warns
-   rather than throwing**, unlike skia's and reanimated's asserts, because their check is
-   "this feature does not work at all" while ours is a web memory-policy floor that native
-   demonstrably clears at 2.6.2 — see the file header.
-
-Two things the checker gets right that are easy to get wrong, both measured:
-
-- **It resolves the CONSUMER's skia, never its own.** Under `link:` the package directory
-  is a sibling checkout _with its own `node_modules`_, so resolving from the script's own
-  location does not fail — it succeeds, answering **2.11.0** while the app ships **2.6.2**.
-  A false pass. Resolution therefore starts at `INIT_CWD` then `process.cwd()`, and a
-  result that landed inside this package while the consumer is elsewhere is reported as
-  "cannot tell", never as "ok".
-- **Only "too low" is fatal.** A crash in an install-time checker is a broken
-  `yarn install` for the whole app, so a release below the floor exits 1 while an absent
-  skia, an unparseable version, an unparseable floor, a self-resolution and any thrown
-  error all **warn and exit 0**. `--strict` promotes those for CI that owns its layout.
-  A **prerelease** below the floor also only warns, which is not laxity: strict
-  `satisfies('2.12.0-next.1', '>=2.8.0')` is **false**, because a prerelease only satisfies
-  a range naming its own `[major,minor,patch]` tuple — failing an install for being too
-  _new_ is the canonical wrong reason to fail.
-
-The comparison uses the real `semver` when the tree has one (it does under `link:`, via
-this package's own dev tree) and a built-in `>=x.y.z` comparator when it does not (a
-tarball consumer, verified: `loadSemver()` returns null there). Both arms are live in the
-wild, so `src/__tests__/peer-check.test.ts` pins them and the runtime layer's third
-implementation to the same table — every skia prerelease published in the range included,
-with `semver` as referee.
-
-Measured end to end, yarn 1.22.19, real installs:
-
-| Consumer | skia           | Result                                                                  |
-| -------- | -------------- | ----------------------------------------------------------------------- |
-| `link:`  | 2.6.2          | `yarn install` **fails, exit 1**, naming 2.6.2, `>=2.8.0` and the fix   |
-| `link:`  | 2.11.0         | clean, exit 0                                                           |
-| `link:`  | absent         | warns, **exit 0**; `--strict` → exit 1                                  |
-| tarball  | 2.6.2          | peer warning **and** the check fails, exit 1                            |
-| tarball  | 2.8.0          | clean, exit 0                                                           |
-| BOLDR    | 2.6.2 (before) | `yarn install` failed after `patch-package` applied — fixed by the bump |
-
-(The same experiments confirm the `optional` flags do their job: neither `react-native` nor
-`react-native-reanimated` warns when absent.)
-
-`react-native` and `react-native-reanimated` stay **optional**, and that is load-bearing:
-the package must load with neither present. That is what lets the pure core, the planner,
-the cadence policy and the CanvasKit pixel suite run under plain node, and it is why
-`src/rasterizer/index.native.ts` reaches the native module through a `require()` inside a
-`try` instead of a static import. Nothing in `src/` imports reanimated at all.
-
-> Installing `react-native-reanimated` in this dev tree leaves one **expected** unmet
-> peer: reanimated 4.x requires `react-native-worklets` (`0.10.x - 0.11.x`). It is not
-> added, because this tree has no Babel or Metro pipeline for a worklet plugin to run in
-> and nothing here imports reanimated — adding it would trade one warning for its own two
-> (`@babel/core`, `@react-native/metro-config`). `react-native`'s own
-> `@react-native/codegen` likewise wants `@babel/core`. Both are inert here.
-
-## Development
-
-```bash
-yarn install
-yarn typecheck     # tsc --noEmit
-yarn test:run      # vitest
-yarn build         # tsc -> dist/
-yarn dev           # tsc --watch, for local linking
-```
+### Entry points
 
-`react-native` is in the dev tree for its **types**, not to be loaded. Under vitest
-`require('react-native')` now resolves the file and throws
-`SyntaxError: Unexpected token 'typeof'` on its Flow syntax, where before it threw
-`MODULE_NOT_FOUND`. Both land in the same `catch`, so `getDefaultRasterizer()` still
-returns the self-describing placeholder — but the `try` is now catching a parse error
-rather than a resolution error, which is worth knowing before someone "tidies" it.
+| Subpath        | Exports                                                                                                             |
+| -------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `.` (root)     | `usePdfDocument`, `usePdfLayer`, `PdfContentView`, `openPdfDocument`, `createPdfController`, layouts, policy, types |
+| `./rasterizer` | `getDefaultRasterizer`, `configureWebPdfium`                                                                        |
+| `./web-init`   | `loadPdfCanvasSkiaWeb()` — web only                                                                                 |
+| `./worker`     | The PDFium module worker; a bundler entry point, web only                                                           |
+| `./skia`       | `ingestRaster`, `imageFromPixels`, `rasterByteLength`, `skiaApi()`                                                  |
+| `./testing`    | `createFakeRasterizer()` and the deterministic scenes                                                               |
 
-### The native suites
+The root barrel contains no module-scope Skia, which permits it to be evaluated in Node during a
+server-side rendering pass. The Skia ingest seam is reached through the `./skia` subpath.
 
-Both native backends are React-free libraries with their own test runners, and neither
-needs an app:
+### Page layouts
 
-```bash
-cd ios && swift test                    # 82 XCTest cases, ~2s, on the Mac itself
+`singlePage()`, `continuousVertical(gap)` and `spread(gap)` are provided. A host may supply any
+function of the form `(pages: DocSize[]) => DocRect[]`.
 
-export JAVA_HOME="/path/to/Android Studio/jbr"   # JDK 17
-cd android && ./gradlew connectedDebugAndroidTest # runs on every attached device
-```
+### Render policy
+
+Cadence is configured through a partial `RasterPolicy`. Every constant has an exported default:
 
-`ios/Package.swift` compiles `Sources/PdfCanvasCore` for **macOS**, which is what makes
-`swift test` possible at all — CoreGraphics and PDFKit exist there and UIKit does not, so
-a UIKit import anywhere in the core breaks the build immediately. That is the point: the
-core is not allowed to depend on anything a laptop cannot run.
-
-`Sources/PdfCanvasBridge` is deliberately outside that target. It needs `<jsi/jsi.h>` and
-`<React/RCTBridgeModule.h>` from pods SwiftPM cannot see, so its only build is the
-podspec's and its only proof is a device session — the same shape as Android's
-`src/reactnative` source set.
-
-**Driving it on a device** goes through the consuming app's dev probe
-(`app/dev-pdf-canvas-probe.tsx`), which reads one agreed path so a measurement is
-repeatable:
-
-```bash
-# iOS — the app's own Documents directory. The path carries a per-install UUID, so
-# the probe reads it at runtime rather than hardcoding it.
-xcrun devicectl device copy to --device <udid> \
-  --domain-type appDataContainer --domain-identifier com.reekon.boldrpro.dev \
-  --source some.pdf --destination Documents/pdf-canvas-probe.pdf
-
-# and reach the probe route on a COLD start — a warm deep link is intercepted by the
-# app's own share-link handler
-xcrun devicectl device process launch --device <udid> --terminate-existing \
-  --payload-url "boldrpro-dev://dev-pdf-canvas-probe" com.reekon.boldrpro.dev
-
-# Android
-adb push some.pdf \
-  /sdcard/Android/data/com.reekon.boldrpro.dev/files/pdf-canvas-probe.pdf
+```ts
+usePdfLayer({document, policy: {sharpnessBand: 1.2, quietZoomMs: 400}});
 ```
 
-`console.log` from a dev build goes to **Metro**, not to the device console, so the
-`PDFCANVAS-PHASES` lines the probe emits per tile show up in the `expo start` output
-rather than in `devicectl --console`.
+`minEpochIntervalMs` (default 300) should be measured before production use and set to the
+observed p95 raster time. A value set too low permits a user adjusting the zoom to supersede
+each render before it completes.
 
-### Consuming it
+## Platform support
 
-**Both apps take this package as a git dependency over ssh**, and the two package managers
-need different fragment syntax:
+| Platform | Engine                                        | Backend identifier |
+| -------- | --------------------------------------------- | ------------------ |
+| iOS      | PDFium via `PDFium.xcframework`               | `ios-pdfium`       |
+| Android  | PDFium via `libpdfium.so`                     | `android-pdfium`   |
+| Web      | PDFium WebAssembly in a module worker         | `web-pdfium`       |
+| Any      | `createFakeRasterizer()`, for tests and demos | Configurable       |
 
-```jsonc
-// rock-desktop (yarn Berry) — "#head=" is the unambiguous branch lookup; a bare
-// fragment is a commit->tag->head fallback, so a tag named main would win.
-"@reekon-tools/react-native-pdf-canvas":
-  "ssh://git@gitlab.com/reekon-tools/software/rock-pro/react-native-pdf-canvas.git#head=main"
+All three platform backends link the same pinned PDFium release. Annotations, form fields,
+passwords and the `/Rotate` page attribute are therefore handled identically on each.
 
-// rock-pro-app (yarn 1) — a BARE fragment. yarn 1's resolver has no key=value
-// handling, so "#head=main" is read as a literal ref name and fails.
-"@reekon-tools/react-native-pdf-canvas":
-  "ssh://git@gitlab.com/reekon-tools/software/rock-pro/react-native-pdf-canvas.git#main"
-```
+## License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) for the full terms.
 
-`dist/` is gitignored and absent from the git tree deliberately — the `prepare` script
-builds it at install time. **Do not remove `prepare`**: yarn 1 gates its
-clone-install-pack path on `Boolean(scripts.prepare)` and otherwise falls back to
-`git archive`, which would install the raw repo with zero `dist` files and no obvious
-error. `prepack` alone covers Berry and is not enough for yarn 1.
-
-The edit loop is therefore commit, push, then re-resolve in the consumer
-(`yarn upgrade @reekon-tools/react-native-pdf-canvas`). Yarn 1 caches the packed tarball
-keyed by resolved sha, so a force-push that reuses a sha serves the stale pack.
-
-#### The older `link:` arrangement, and why its traps still matter
-
-Both apps used to link this in from a sibling checkout (`link:../BOLDR_PdfCanvas`). That is
-no longer how either consumes it, but the two traps below are the reason several comments in
-this repo and in the apps read the way they do, and they come straight back if anyone goes
-back to `link:` for local iteration:
-
-- **The app resolves `dist/`, not `src/`.** A consumer gets whatever `dist/` happens to
-  contain, and a stale one fails as a missing module deep inside the package rather than
-  as anything obvious. **`prepare` does NOT build on the app's install** — measured: yarn
-  1 runs none of a `link:` dependency's lifecycle scripts, so `prepare` only fires on a
-  `yarn install` in _this_ tree. Keep `yarn dev` running while iterating. (This is also
-  why the peer-floor gate is a plain `.mjs` under `scripts/` rather than anything in
-  `dist/` — see "Enforcing the floor".)
-- **On Windows, yarn 1's `link:` creates a JUNCTION, and Metro will not traverse one.**
-  The bundle fails with `Unable to resolve module @reekon-tools/react-native-pdf-canvas`,
-  which reads exactly like the package was never installed — while Gradle follows the
-  junction fine, so autolinking succeeds and only JS breaks. Replacing it with a real
-  symlink (`mklink /D`) works but is undone by the next `yarn install`. rock-pro-app's
-  `metro.config.js` instead mapped the package name straight to the sibling checkout via
-  `resolver.extraNodeModules`, which survives reinstalls. **That entry is removed now**, and
-  it had to be: with a git dependency the mapping still wins over `node_modules` for anyone
-  holding the checkout, so `tsc` reads the packed copy while Metro bundles the working tree.
-  Its `LOCAL_PACKAGES` list is empty and documents that only `link:` deps belong in it.
-
-## Design docs
-
-The reasoning behind every constant and every trap above. **In this repo**, because they
-describe this package and therefore have to version with it:
-
-- [`docs/pdf-canvas-package-spec.md`](./docs/pdf-canvas-package-spec.md) — render model,
-  cadence, API, verified traps
-- [`docs/pdf-canvas-export.md`](./docs/pdf-canvas-export.md) — getting a PDF back out
-
-**In the `rock-pro-app` repo** under `docs/`, because they describe the Nutrient-removal
-programme across both consuming apps rather than this package:
-
-- `pdf-canvas-mvp-plan.md` — phases, spikes, backend decisions
-- `pdf-canvas-integration.md` — how it meets the shared annotation canvas, and the shared
-  storage line
+The package may be used in commercial and closed-source software. Redistribution requires
+retaining the copyright notice and the attributions in [NOTICE](./NOTICE), and stating any
+modifications made to the files.
+
+### Third-party components
+
+Because this package builds against PDFium, an application that ships it also ships PDFium and
+its bundled components, licensed variously under BSD-3-Clause, MIT, Apache-2.0, the FreeType
+License, the zlib License and the IJG License. [NOTICE](./NOTICE) enumerates the attributions to
+reproduce in an application's third-party notices. Complete license texts are included in the
+`licenses/` directory of every PDFium archive retrieved during the build.
+
+## Internals
+
+The rationale behind each constant, each measured figure and each upstream defect the package
+works around is documented in `CLAUDE.md` in the repository, alongside extended design
+documentation under `docs/`. Neither is included in the published tarball. The relevant section
+should be consulted before altering behavior it describes.
+
+```sh
+yarn install
+yarn ci                  # Format check, typecheck, tests, build
+yarn pdfium:fetch host   # Retrieve and verify PDFium for the local machine
+yarn native:test         # Build and run the C++ core suite locally
+```