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

package/README.md

@@ -0,0 +1,1391 @@
+# @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);
+```
+
+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.
+
+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.
+
+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.
+
+**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.
+
+### Web startup
+
+```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.
+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
+
+> **The transform decides _when_ to rasterize, never _what_ to draw.**
+
+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.
+
+Two consequences, both load-bearing:
+
+- **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.
+
+The package therefore never reads `worldTransform.value` and never accepts a
+`Transforms3d`. The host **pushes** a plain `{visibleDocRect, scale}` snapshot at settle
+rate.
+
+## Usage
+
+```tsx
+import {Canvas, Group} from '@shopify/react-native-skia';
+import {
+  usePdfDocument,
+  usePdfLayer,
+  PdfContentView,
+} from '@reekon-tools/react-native-pdf-canvas';
+
+function Sheet({uri, worldTransform, viewport}) {
+  // ABOVE the <Canvas>. Not stylistic — see "Where the hooks go".
+  const {document} = usePdfDocument({uri});
+  const {content, controller} = usePdfLayer({document});
+
+  // Your gestures, your transform. Tell the package when you settled.
+  const pan = Gesture.Pan()
+    .onBegin(() => runOnJS(controller.suppress)())
+    .onFinalize(() => runOnJS(controller.settle)(viewport()));
+
+  return (
+    <GestureDetector gesture={pan}>
+      <Canvas style={{flex: 1}}>
+        <Group transform={worldTransform}>
+          <PdfContentView content={content} />
+          {/* everything else, in the same doc space */}
+        </Group>
+      </Canvas>
+    </GestureDetector>
+  );
+}
+```
+
+### 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.
+
+```ts
+import {
+  DEFAULT_POLICY,
+  resolvePolicy,
+} from '@reekon-tools/react-native-pdf-canvas';
+
+usePdfLayer({document, policy: {sharpnessBand: 1.2, quietZoomMs: 400}});
+```
+
+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.
+
+```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';
+
+setDefaultRasterizer(
+  configureWebPdfium({
+    createWorker: () => new PdfCanvasWorker(),
+    wasm: {url: wasmUrl},
+  }),
+);
+```
+
+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
+```
+
+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
+```
+
+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
+```
+
+`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.
+
+### The native suites
+
+Both native backends are React-free libraries with their own test runners, and neither
+needs an app:
+
+```bash
+cd ios && swift test                    # 82 XCTest cases, ~2s, on the Mac itself
+
+export JAVA_HOME="/path/to/Android Studio/jbr"   # JDK 17
+cd android && ./gradlew connectedDebugAndroidTest # runs on every attached device
+```
+
+`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
+```
+
+`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`.
+
+### Consuming it
+
+**Both apps take this package as a git dependency over ssh**, and the two package managers
+need different fragment syntax:
+
+```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"
+
+// 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"
+```
+
+`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