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

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

@@ -0,0 +1,63 @@
+/**
+ * The web default rasterizer: PDFium in a module worker.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THIS NEEDS A CALL AND ANDROID DOES NOT
+ * ------------------------------------------------------------------------
+ *
+ * `index.native.ts` can resolve its backend by itself, because a native module
+ * either is in the binary or is not and `NativeModules.PdfCanvas` answers that
+ * question with no help from anyone. On web the equivalent question — "how do I
+ * construct a worker, and where is `pdfium.wasm`" — has no answer this package
+ * can discover. It depends entirely on the host's bundler, its `base`, its asset
+ * pipeline and its CSP, and every scheme a library might guess at
+ * (`new URL('./worker.js', import.meta.url)`, a CDN default, a same-origin path)
+ * fails somewhere in production rather than at build time.
+ *
+ * So the host says it once, and this module holds the answer:
+ *
+ *     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},
+ *       }),
+ *     );
+ *
+ * The second call is separate on purpose: `setDefaultRasterizer` lives on the
+ * React side (`react/usePdfDocument.ts`), and reaching it from here would put
+ * React into the bundle of anyone who imports the backend registry.
+ *
+ * Until it is configured, `getDefaultRasterizer()` returns the self-describing
+ * placeholder that fails at `open()` — the same shape as before, so the pure
+ * core, the Skia ingest path and the fake backend all keep working in a browser
+ * and in vitest.
+ */
+import type { WebRasterizerOptions } from './web/index.js';
+import type { PageRasterizer } from '../types.js';
+export * from './index.js';
+export * from './web/index.js';
+/**
+ * Install the web backend and return it.
+ *
+ * IDENTITY IS STABLE PER CONFIGURATION, which is what
+ * `getDefaultRasterizer`'s contract requires — a rasterizer identity change is
+ * a reason to reopen every document, so the default must not be a fresh object
+ * per call. Calling this a second time with different options DOES change the
+ * identity, and that is correct: the backend genuinely changed.
+ */
+export declare function configureWebPdfium(options: WebRasterizerOptions): PageRasterizer;
+/** Forget the configuration. Exists for tests; harmless anywhere. */
+export declare function resetWebPdfium(): void;
+/**
+ * See the note in `index.native.ts`: `react/usePdfDocument.ts` exports a
+ * registry accessor of the same name and a different meaning, so the root index
+ * must not `export *` from this module.
+ */
+export declare const getDefaultRasterizer: () => PageRasterizer;

package/dist/rasterizer/index.web.js

@@ -0,0 +1,75 @@
+/**
+ * The web default rasterizer: PDFium in a module worker.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THIS NEEDS A CALL AND ANDROID DOES NOT
+ * ------------------------------------------------------------------------
+ *
+ * `index.native.ts` can resolve its backend by itself, because a native module
+ * either is in the binary or is not and `NativeModules.PdfCanvas` answers that
+ * question with no help from anyone. On web the equivalent question — "how do I
+ * construct a worker, and where is `pdfium.wasm`" — has no answer this package
+ * can discover. It depends entirely on the host's bundler, its `base`, its asset
+ * pipeline and its CSP, and every scheme a library might guess at
+ * (`new URL('./worker.js', import.meta.url)`, a CDN default, a same-origin path)
+ * fails somewhere in production rather than at build time.
+ *
+ * So the host says it once, and this module holds the answer:
+ *
+ *     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},
+ *       }),
+ *     );
+ *
+ * The second call is separate on purpose: `setDefaultRasterizer` lives on the
+ * React side (`react/usePdfDocument.ts`), and reaching it from here would put
+ * React into the bundle of anyone who imports the backend registry.
+ *
+ * Until it is configured, `getDefaultRasterizer()` returns the self-describing
+ * placeholder that fails at `open()` — the same shape as before, so the pure
+ * core, the Skia ingest path and the fake backend all keep working in a browser
+ * and in vitest.
+ */
+import { createMissingBackendRasterizer } from './index.js';
+import { createWebRasterizer } from './web/index.js';
+export * from './index.js';
+export * from './web/index.js';
+const MISSING = createMissingBackendRasterizer('missing-web', 'The web PDFium rasterizer has not been configured: call ' +
+    '`configureWebPdfium({createWorker, wasm})` once at startup, handing it a ' +
+    'factory for a MODULE worker built from ' +
+    "'@reekon-tools/react-native-pdf-canvas/worker' and a locator for " +
+    "'@embedpdf/pdfium/pdfium.wasm'. This package constructs neither by " +
+    'itself, because both depend on your bundler.');
+let configured = null;
+/**
+ * Install the web backend and return it.
+ *
+ * IDENTITY IS STABLE PER CONFIGURATION, which is what
+ * `getDefaultRasterizer`'s contract requires — a rasterizer identity change is
+ * a reason to reopen every document, so the default must not be a fresh object
+ * per call. Calling this a second time with different options DOES change the
+ * identity, and that is correct: the backend genuinely changed.
+ */
+export function configureWebPdfium(options) {
+    configured = createWebRasterizer(options);
+    return configured;
+}
+/** Forget the configuration. Exists for tests; harmless anywhere. */
+export function resetWebPdfium() {
+    configured = null;
+}
+/**
+ * See the note in `index.native.ts`: `react/usePdfDocument.ts` exports a
+ * registry accessor of the same name and a different meaning, so the root index
+ * must not `export *` from this module.
+ */
+export const getDefaultRasterizer = () => configured ?? MISSING;

package/dist/rasterizer/ingest.d.ts

@@ -0,0 +1,180 @@
+/**
+ * RasterPixels -> SkImage.
+ *
+ * This is the only module in the package that CALLS the Skia runtime — the
+ * planner, the cadence policy and the fake backend are all pure, which is what
+ * keeps them testable in vitest with no native modules loaded. The two resolver
+ * files under `../skia/` are the only others that name it at all, and neither
+ * calls anything: they hand this file a way to find it. All three are reachable
+ * only from the `./skia` subpath.
+ *
+ * ------------------------------------------------------------------------
+ * PLATFORM SPLIT — how many copies of the pixels exist once ingest returns.
+ * ------------------------------------------------------------------------
+ *
+ * NATIVE: `Skia.Data.fromBytes` is `SkData::MakeWithCopy(...)`
+ * (cpp/api/JsiSkDataFactory.h) — one copy — and `Skia.Image.MakeImage` is
+ * `SkImages::RasterFromData(info, data, bytesPerRow)`
+ * (cpp/api/JsiSkImageFactory.h), which SHARES that SkData rather than copying
+ * it again. Ingest therefore costs exactly ONE copy, and the backend's own
+ * buffer is collectable the moment JS drops its reference.
+ *
+ * WEB: `Skia.Data.fromBytes` only wraps the Uint8Array
+ * (skia/web/JsiSkDataFactory.ts -> `new JsiSkData(CanvasKit, bytes)`), and
+ * `CanvasKit.MakeImage` is the copy: "we will always make a copy of the pixel
+ * data, because of inconsistencies in behavior between GPU and CPU". Also one
+ * copy — but into the WASM heap, which grows ONE WAY. Emscripten never returns
+ * pages to the OS, so it is PEAK simultaneous raster bytes, not average, that
+ * sets the tab's memory floor for the rest of the session.
+ *
+ * That is why BOTH layers are tiled — base and detail alike — to
+ * `RasterPolicy.maxPieceDimension`: a grid of small overlapping pieces holds the
+ * same RESIDENT total as one big raster but has a far smaller in-flight peak,
+ * and on web the peak is the part that is permanent. It is also why RETIRING is
+ * released on the next commit rather than kept "just in case".
+ *
+ * ------------------------------------------------------------------------
+ * WHITE FILL IS THE BACKEND'S JOB, and it is not optional.
+ * ------------------------------------------------------------------------
+ *
+ * Neither PDFium's FPDF_RenderPageBitmap nor Android's PdfRenderer.render
+ * clears the destination first, and a freshly allocated RGBA buffer is
+ * transparent black. Composited under the app's annotation layers that reads as
+ * a BLACK page, not a blank one. Every backend must fill the requested
+ * background before drawing. Ingest cannot repair it afterwards: it has no way
+ * to tell "the PDF painted black here" from "nothing painted here".
+ *
+ * ------------------------------------------------------------------------
+ * NOTHING HERE MAY NAME `Skia` AT MODULE SCOPE.
+ * ------------------------------------------------------------------------
+ *
+ * This file used to open with
+ * `import {AlphaType, ColorType, Skia} from '@shopify/react-native-skia'`, and
+ * that single line decided the fate of the whole package on web: it is a VALUE
+ * import of the bare specifier, whose barrel evaluates
+ * `Skia.web.js` = `JsiSkApi(global.CanvasKit)` — once, permanently, possibly
+ * before CanvasKit exists. See `../skia/skia-api.ts` for the full account.
+ *
+ * Two consequences that must both hold, and are asserted by
+ * `__tests__/module-ordering.test.ts`:
+ *
+ *  - `Skia` is reached through `skiaApi()`, called INSIDE `makeImage`. Not
+ *    stored in a module-level const, not read in `imageFromPixels`'s preamble.
+ *  - `AlphaType` / `ColorType` come from their own leaf modules under
+ *    `skia/types/Image/`, not from the barrel. They are plain numeric enum
+ *    objects with no imports of their own, but reaching them through
+ *    `@shopify/react-native-skia` would have dragged `Skia.web.js` in exactly as
+ *    the `Skia` import did — MEASURED by bundling, since nothing about the two
+ *    import statements looks different.
+ */
+import { ColorType } from '@shopify/react-native-skia/lib/module/skia/types/Image/ColorType.js';
+import { AlphaType } from '@shopify/react-native-skia/lib/module/skia/types/Image/ImageFactory.js';
+import type { SkImage } from '@shopify/react-native-skia';
+import type { AlphaEncoding, PdfRaster, PixelFormat, RasterPixels } from '../types.js';
+import type { RasterIngestMeta } from '../controller.js';
+export declare const BYTES_PER_PIXEL = 4;
+/**
+ * The two ColorType members that survive BOTH backends.
+ *
+ * RN Skia declares 19 ColorType members, and most of them throw on web:
+ * JsiSkImageFactory.MakeImage runs the value through
+ * `getEnum(CanvasKit, 'ColorType', v)`, which scans CanvasKit's embind enum for
+ * a matching numeric value and throws `Enum ColorType does not have value N`
+ * when it finds none. CanvasKit exposes only Alpha_8, RGB_565, RGBA_8888,
+ * BGRA_8888, RGBA_1010102, RGB_101010x, Gray_8, RGBA_F16 and RGBA_F32 — so
+ * Unknown, ARGB_4444, RGB_888x, BGRA_1010102 and every XR/F16Norm member is a
+ * declared-but-fatal option. `PixelFormat` deliberately reaches only the two
+ * 8888 members, and both are present in CanvasKit with matching numeric values
+ * (RN Skia's enum mirrors SkColorType's ordering).
+ */
+export declare const colorTypeFor: (format: PixelFormat) => ColorType;
+/**
+ * The backend's declared alpha encoding -> Skia's tag. NOT A CONSTANT.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THIS IS PER-RASTER AND NOT A MODULE-SCOPE `AlphaType.Premul`.
+ * ------------------------------------------------------------------------
+ *
+ * It was one, and it was wrong for two of the three engines this package knows
+ * about. MEASURED: an antialiased opaque-white edge over a transparent page
+ * reads `[255, 255, 255, 157]` from PDFium and `[255, 255, 255, 160]` from
+ * pdf.js — STRAIGHT alpha. Premultiplied would have been `~[157, 157, 157, 157]`.
+ * Android's `Bitmap` ARGB_8888 genuinely is premultiplied, so no single tag is
+ * right for all of them and `RasterPixels.alpha` carries the answer, exactly as
+ * `format` already carries the byte order.
+ *
+ * Tagging straight bytes Premul does not error — Skia takes the tag at its word
+ * and composites the un-scaled channels, so every partially-transparent pixel
+ * comes out too BRIGHT (and an impossible value, channel > alpha, is clamped in
+ * whatever way the backend feels like). Invisible under `background: 'white'`,
+ * where every pixel is opaque and the two encodings are byte-identical.
+ *
+ * ------------------------------------------------------------------------
+ * AND WHY NEITHER OPTION IS `AlphaType.Opaque`.
+ * ------------------------------------------------------------------------
+ *
+ * Skia treats an Opaque-tagged buffer as licence to ignore the alpha channel
+ * entirely, so a `background: 'transparent'` raster tagged Opaque paints its
+ * cleared area as opaque BLACK rather than letting the canvas beneath show
+ * through. That claim is pinned by a pixel test ('alpha type' in
+ * composition.test.ts) rather than left as a comment. A fully-opaque raster is a
+ * valid buffer under BOTH of the tags below, so nothing is gained by reaching
+ * for Opaque even when the backend happens to have filled every pixel.
+ *
+ * ------------------------------------------------------------------------
+ * WEB ENUM TRAP — both of these are safe, and it was checked, not assumed.
+ * ------------------------------------------------------------------------
+ *
+ * Same trap as `colorTypeFor`: web's `MakeImage` runs the value through
+ * `getEnum(CanvasKit, 'AlphaType', v)`, which throws when CanvasKit's embind
+ * enum has no member with that numeric value. VERIFIED against canvaskit-wasm
+ * 0.41.0 (the version pinned across the whole supported RN Skia range):
+ * `CanvasKit.AlphaType` exposes exactly `Opaque = 1`, `Premul = 2`,
+ * `Unpremul = 3`, and RN Skia declares `Unknown = 0, Opaque = 1, Premul = 2,
+ * Unpremul = 3` — so both members reached below have matching numeric values and
+ * neither throws. `AlphaType.Unknown` has no CanvasKit counterpart at all and is
+ * a declared-but-fatal option on web, which is the other reason this maps a
+ * closed two-member union rather than passing an `AlphaType` through.
+ */
+export declare const alphaTypeFor: (alpha: AlphaEncoding) => AlphaType;
+/**
+ * Device-memory footprint of a MOUNTED raster, for the cache budget — both
+ * copies (see `RESIDENT_COPIES`), not just the decoded pixels.
+ *
+ * `cacheBudgetBytes` is deliberately UNCHANGED, so its meaning tightens: the same
+ * 96 MiB now covers half as many pixels. That is the point — it was always
+ * covering half as many, it just did not know.
+ *
+ * THE ONE PLACE THE FACTOR IS WRITTEN. Every other site derives from this
+ * function — including the controller suite's `ingest` stub, which restated
+ * `* 4 * 2` by hand and could therefore agree with itself while disagreeing with
+ * production. The single independent statement of the number lives in
+ * `composition.test.ts` as a literal, which is what stops this from asserting
+ * `rasterByteLength === rasterByteLength`.
+ */
+export declare const rasterByteLength: (width: number, height: number) => number;
+/**
+ * Turn a backend's pixels into an SkImage, or throw a PdfError.
+ *
+ * Throws rather than returning null: a missing image at this point is a bug in
+ * a backend or an out-of-memory condition, and the caller (the epoch builder)
+ * wants it as a diagnostic against a raster key, not as a silently blank tile.
+ */
+export declare function imageFromPixels(pixels: RasterPixels): SkImage;
+/**
+ * The controller's `ingest` seam, implemented.
+ *
+ * `PdfControllerOptions.ingest` is injected precisely so the controller can run
+ * under plain node in vitest; this is the real one, and it is drop-in:
+ * `createPdfController({..., ingest: ingestRaster})`.
+ *
+ * `docRect` and `scale` are copied from the META, not re-derived from the
+ * pixels. That is THE ONE RULE in miniature — the bytes are whatever the
+ * backend produced, but the rect they are drawn at is the rect they were
+ * requested for, and rounding the pixel size must never move it.
+ *
+ * `bytes` is the RESIDENT footprint of the image (see `rasterByteLength`), not
+ * the source buffer's length: after ingest the source buffer is collectable and
+ * what the cache budget is accounting for is the image — both copies of it.
+ */
+export declare function ingestRaster(pixels: RasterPixels, meta: RasterIngestMeta): PdfRaster;

package/dist/rasterizer/ingest.js

@@ -0,0 +1,307 @@
+/**
+ * RasterPixels -> SkImage.
+ *
+ * This is the only module in the package that CALLS the Skia runtime — the
+ * planner, the cadence policy and the fake backend are all pure, which is what
+ * keeps them testable in vitest with no native modules loaded. The two resolver
+ * files under `../skia/` are the only others that name it at all, and neither
+ * calls anything: they hand this file a way to find it. All three are reachable
+ * only from the `./skia` subpath.
+ *
+ * ------------------------------------------------------------------------
+ * PLATFORM SPLIT — how many copies of the pixels exist once ingest returns.
+ * ------------------------------------------------------------------------
+ *
+ * NATIVE: `Skia.Data.fromBytes` is `SkData::MakeWithCopy(...)`
+ * (cpp/api/JsiSkDataFactory.h) — one copy — and `Skia.Image.MakeImage` is
+ * `SkImages::RasterFromData(info, data, bytesPerRow)`
+ * (cpp/api/JsiSkImageFactory.h), which SHARES that SkData rather than copying
+ * it again. Ingest therefore costs exactly ONE copy, and the backend's own
+ * buffer is collectable the moment JS drops its reference.
+ *
+ * WEB: `Skia.Data.fromBytes` only wraps the Uint8Array
+ * (skia/web/JsiSkDataFactory.ts -> `new JsiSkData(CanvasKit, bytes)`), and
+ * `CanvasKit.MakeImage` is the copy: "we will always make a copy of the pixel
+ * data, because of inconsistencies in behavior between GPU and CPU". Also one
+ * copy — but into the WASM heap, which grows ONE WAY. Emscripten never returns
+ * pages to the OS, so it is PEAK simultaneous raster bytes, not average, that
+ * sets the tab's memory floor for the rest of the session.
+ *
+ * That is why BOTH layers are tiled — base and detail alike — to
+ * `RasterPolicy.maxPieceDimension`: a grid of small overlapping pieces holds the
+ * same RESIDENT total as one big raster but has a far smaller in-flight peak,
+ * and on web the peak is the part that is permanent. It is also why RETIRING is
+ * released on the next commit rather than kept "just in case".
+ *
+ * ------------------------------------------------------------------------
+ * WHITE FILL IS THE BACKEND'S JOB, and it is not optional.
+ * ------------------------------------------------------------------------
+ *
+ * Neither PDFium's FPDF_RenderPageBitmap nor Android's PdfRenderer.render
+ * clears the destination first, and a freshly allocated RGBA buffer is
+ * transparent black. Composited under the app's annotation layers that reads as
+ * a BLACK page, not a blank one. Every backend must fill the requested
+ * background before drawing. Ingest cannot repair it afterwards: it has no way
+ * to tell "the PDF painted black here" from "nothing painted here".
+ *
+ * ------------------------------------------------------------------------
+ * NOTHING HERE MAY NAME `Skia` AT MODULE SCOPE.
+ * ------------------------------------------------------------------------
+ *
+ * This file used to open with
+ * `import {AlphaType, ColorType, Skia} from '@shopify/react-native-skia'`, and
+ * that single line decided the fate of the whole package on web: it is a VALUE
+ * import of the bare specifier, whose barrel evaluates
+ * `Skia.web.js` = `JsiSkApi(global.CanvasKit)` — once, permanently, possibly
+ * before CanvasKit exists. See `../skia/skia-api.ts` for the full account.
+ *
+ * Two consequences that must both hold, and are asserted by
+ * `__tests__/module-ordering.test.ts`:
+ *
+ *  - `Skia` is reached through `skiaApi()`, called INSIDE `makeImage`. Not
+ *    stored in a module-level const, not read in `imageFromPixels`'s preamble.
+ *  - `AlphaType` / `ColorType` come from their own leaf modules under
+ *    `skia/types/Image/`, not from the barrel. They are plain numeric enum
+ *    objects with no imports of their own, but reaching them through
+ *    `@shopify/react-native-skia` would have dragged `Skia.web.js` in exactly as
+ *    the `Skia` import did — MEASURED by bundling, since nothing about the two
+ *    import statements looks different.
+ */
+import { ColorType } from '@shopify/react-native-skia/lib/module/skia/types/Image/ColorType.js';
+import { AlphaType } from '@shopify/react-native-skia/lib/module/skia/types/Image/ImageFactory.js';
+import { isTightBuffer } from './buffer.js';
+import { skiaApi } from '../skia/skia-api.js';
+import { warnIfSkiaBelowFloor } from '../peer-check.js';
+import { PdfError } from '../types.js';
+export const BYTES_PER_PIXEL = 4;
+/**
+ * The two ColorType members that survive BOTH backends.
+ *
+ * RN Skia declares 19 ColorType members, and most of them throw on web:
+ * JsiSkImageFactory.MakeImage runs the value through
+ * `getEnum(CanvasKit, 'ColorType', v)`, which scans CanvasKit's embind enum for
+ * a matching numeric value and throws `Enum ColorType does not have value N`
+ * when it finds none. CanvasKit exposes only Alpha_8, RGB_565, RGBA_8888,
+ * BGRA_8888, RGBA_1010102, RGB_101010x, Gray_8, RGBA_F16 and RGBA_F32 — so
+ * Unknown, ARGB_4444, RGB_888x, BGRA_1010102 and every XR/F16Norm member is a
+ * declared-but-fatal option. `PixelFormat` deliberately reaches only the two
+ * 8888 members, and both are present in CanvasKit with matching numeric values
+ * (RN Skia's enum mirrors SkColorType's ordering).
+ */
+export const colorTypeFor = (format) => format === 'bgra8888' ? ColorType.BGRA_8888 : ColorType.RGBA_8888;
+/**
+ * The backend's declared alpha encoding -> Skia's tag. NOT A CONSTANT.
+ *
+ * ------------------------------------------------------------------------
+ * WHY THIS IS PER-RASTER AND NOT A MODULE-SCOPE `AlphaType.Premul`.
+ * ------------------------------------------------------------------------
+ *
+ * It was one, and it was wrong for two of the three engines this package knows
+ * about. MEASURED: an antialiased opaque-white edge over a transparent page
+ * reads `[255, 255, 255, 157]` from PDFium and `[255, 255, 255, 160]` from
+ * pdf.js — STRAIGHT alpha. Premultiplied would have been `~[157, 157, 157, 157]`.
+ * Android's `Bitmap` ARGB_8888 genuinely is premultiplied, so no single tag is
+ * right for all of them and `RasterPixels.alpha` carries the answer, exactly as
+ * `format` already carries the byte order.
+ *
+ * Tagging straight bytes Premul does not error — Skia takes the tag at its word
+ * and composites the un-scaled channels, so every partially-transparent pixel
+ * comes out too BRIGHT (and an impossible value, channel > alpha, is clamped in
+ * whatever way the backend feels like). Invisible under `background: 'white'`,
+ * where every pixel is opaque and the two encodings are byte-identical.
+ *
+ * ------------------------------------------------------------------------
+ * AND WHY NEITHER OPTION IS `AlphaType.Opaque`.
+ * ------------------------------------------------------------------------
+ *
+ * Skia treats an Opaque-tagged buffer as licence to ignore the alpha channel
+ * entirely, so a `background: 'transparent'` raster tagged Opaque paints its
+ * cleared area as opaque BLACK rather than letting the canvas beneath show
+ * through. That claim is pinned by a pixel test ('alpha type' in
+ * composition.test.ts) rather than left as a comment. A fully-opaque raster is a
+ * valid buffer under BOTH of the tags below, so nothing is gained by reaching
+ * for Opaque even when the backend happens to have filled every pixel.
+ *
+ * ------------------------------------------------------------------------
+ * WEB ENUM TRAP — both of these are safe, and it was checked, not assumed.
+ * ------------------------------------------------------------------------
+ *
+ * Same trap as `colorTypeFor`: web's `MakeImage` runs the value through
+ * `getEnum(CanvasKit, 'AlphaType', v)`, which throws when CanvasKit's embind
+ * enum has no member with that numeric value. VERIFIED against canvaskit-wasm
+ * 0.41.0 (the version pinned across the whole supported RN Skia range):
+ * `CanvasKit.AlphaType` exposes exactly `Opaque = 1`, `Premul = 2`,
+ * `Unpremul = 3`, and RN Skia declares `Unknown = 0, Opaque = 1, Premul = 2,
+ * Unpremul = 3` — so both members reached below have matching numeric values and
+ * neither throws. `AlphaType.Unknown` has no CanvasKit counterpart at all and is
+ * a declared-but-fatal option on web, which is the other reason this maps a
+ * closed two-member union rather than passing an `AlphaType` through.
+ */
+export const alphaTypeFor = (alpha) => alpha === 'straight' ? AlphaType.Unpremul : AlphaType.Premul;
+/**
+ * How many copies of the pixels a MOUNTED raster keeps resident.
+ *
+ * TWO, not one, and the cache was booking one:
+ *
+ *  1. The CPU copy. `Skia.Image.MakeImage` is
+ *     `SkImages::RasterFromData(info, data, rowBytes)`, which SHARES the SkData
+ *     rather than copying it — and sharing means RETAINING: the SkData stays
+ *     alive for the image's entire life, so the bytes `Skia.Data.fromBytes`
+ *     copied in are resident until the image is disposed.
+ *  2. The GPU copy. The first time that raster image is drawn on a GPU canvas,
+ *     Skia uploads it to a texture in its own resource cache and that texture is
+ *     BUDGETED — it is not freed when the draw ends, which is the whole point of
+ *     a resource cache.
+ *
+ * So a raster in the tree costs ~2x its pixels, and `ingest.ts` used to book
+ * `w * h * 4`: the cache believed it was at 26% of a 96 MiB budget when it was at
+ * 53%, and eviction was choosing victims on numbers wrong by a factor of two.
+ */
+const RESIDENT_COPIES = 2;
+/**
+ * Device-memory footprint of a MOUNTED raster, for the cache budget — both
+ * copies (see `RESIDENT_COPIES`), not just the decoded pixels.
+ *
+ * `cacheBudgetBytes` is deliberately UNCHANGED, so its meaning tightens: the same
+ * 96 MiB now covers half as many pixels. That is the point — it was always
+ * covering half as many, it just did not know.
+ *
+ * THE ONE PLACE THE FACTOR IS WRITTEN. Every other site derives from this
+ * function — including the controller suite's `ingest` stub, which restated
+ * `* 4 * 2` by hand and could therefore agree with itself while disagreeing with
+ * production. The single independent statement of the number lives in
+ * `composition.test.ts` as a literal, which is what stops this from asserting
+ * `rasterByteLength === rasterByteLength`.
+ */
+export const rasterByteLength = (width, height) => width * height * BYTES_PER_PIXEL * RESIDENT_COPIES;
+/**
+ * `Skia.Data.fromBytes` on native reads `bytes.buffer` and copies
+ * `buffer.data()` for `buffer.size()` bytes — the WHOLE ArrayBuffer, with
+ * byteOffset and byteLength IGNORED (JsiSkDataFactory.h). A Uint8Array that is
+ * a view into a larger buffer — anything carved out of a shared scratch
+ * allocation with `subarray()` — therefore ingests bytes shifted by its
+ * byteOffset, and the image shears or shows a neighbouring piece's pixels.
+ *
+ * Copying to a tight buffer is the fix. It costs nothing in the normal case,
+ * where the backend allocated exactly one buffer per raster.
+ */
+function tighten(bytes) {
+    return isTightBuffer(bytes)
+        ? { bytes, owned: false }
+        : { bytes: bytes.slice(), owned: true };
+}
+function makeImage(bytes, width, height, rowBytes, format, alpha) {
+    // CALL-TIME, once per process and cached inside the accessor. On web this is
+    // the line that must not run before CanvasKit is loaded — see the header.
+    const Skia = skiaApi();
+    const data = Skia.Data.fromBytes(bytes);
+    return Skia.Image.MakeImage({
+        width,
+        height,
+        colorType: colorTypeFor(format),
+        alphaType: alphaTypeFor(alpha),
+    }, data, rowBytes);
+}
+/** In-place B<->R swap. Only ever called on a buffer this module owns. */
+function swapRedBlue(bytes, width, height, rowBytes) {
+    for (let y = 0; y < height; y++) {
+        const row = y * rowBytes;
+        for (let x = 0; x < width; x++) {
+            const o = row + x * BYTES_PER_PIXEL;
+            // Guarded by the byteLength check in imageFromPixels; `?? 0` is only
+            // here to satisfy noUncheckedIndexedAccess on TypedArray indexing.
+            const b0 = bytes[o] ?? 0;
+            bytes[o] = bytes[o + 2] ?? 0;
+            bytes[o + 2] = b0;
+        }
+    }
+}
+/**
+ * Turn a backend's pixels into an SkImage, or throw a PdfError.
+ *
+ * Throws rather than returning null: a missing image at this point is a bug in
+ * a backend or an out-of-memory condition, and the caller (the epoch builder)
+ * wants it as a diagnostic against a raster key, not as a silently blank tile.
+ */
+export function imageFromPixels(pixels) {
+    // First-raster, dev-only, once per process, and it cannot throw. This is the
+    // only layer of the skia peer gate that catches a version drift no install
+    // ran — see `../peer-check.ts` for why it warns rather than throwing, and why
+    // it is not a module-scope side effect.
+    warnIfSkiaBelowFloor();
+    const { width, height, rowBytes, format, alpha } = pixels;
+    if (!Number.isInteger(width) || !Number.isInteger(height)) {
+        throw new PdfError('backend-failure', `Raster dimensions must be integers, got ${width}x${height}.`);
+    }
+    if (width <= 0 || height <= 0) {
+        throw new PdfError('backend-failure', `Raster has no pixels: ${width}x${height}.`);
+    }
+    if (!Number.isInteger(rowBytes) || rowBytes < width * BYTES_PER_PIXEL) {
+        throw new PdfError('backend-failure', `rowBytes ${rowBytes} is shorter than one ${width}px row ` +
+            `(${width * BYTES_PER_PIXEL} bytes). A wrong rowBytes shears the ` +
+            'image rather than failing, so it is rejected here.');
+    }
+    // Skia's own sizing rule (SkImageInfo::computeByteSize): every row but the
+    // last needs its full stride; the last needs only its pixels. Checking with
+    // the same formula avoids rejecting a legitimately tightly-packed final row.
+    const required = (height - 1) * rowBytes + width * BYTES_PER_PIXEL;
+    if (pixels.bytes.byteLength < required) {
+        throw new PdfError('backend-failure', `Raster buffer is ${pixels.bytes.byteLength} bytes, needs ${required} ` +
+            `for ${width}x${height} at rowBytes ${rowBytes}.`);
+    }
+    const tight = tighten(pixels.bytes);
+    const image = makeImage(tight.bytes, width, height, rowBytes, format, alpha);
+    if (image !== null) {
+        return image;
+    }
+    // MakeImage signals "cannot represent this configuration" by returning null
+    // on both backends rather than throwing. BGRA is the likelier of the two
+    // formats to be refused (Skia's CPU raster accepts it; a given GPU-backed
+    // CanvasKit build may not), so before giving up, swizzle once into RGBA —
+    // the configuration every backend accepts — and retry. One extra pass over
+    // the buffer on a path that would otherwise lose the page.
+    if (format === 'bgra8888') {
+        const rgba = tight.owned ? tight.bytes : tight.bytes.slice();
+        swapRedBlue(rgba, width, height, rowBytes);
+        const retried = makeImage(rgba, width, height, rowBytes, 'rgba8888', 
+        // The swizzle moves BYTES between channels; it does not change whether
+        // those channels are scaled by alpha. Carrying the declaration through is
+        // what keeps the retry a byte-order fallback and nothing else.
+        alpha);
+        if (retried !== null) {
+            return retried;
+        }
+    }
+    throw new PdfError('backend-failure', `Skia.Image.MakeImage returned null for a ${width}x${height} ${format} ` +
+        `${alpha}-alpha raster (rowBytes ${rowBytes}, ${required} bytes). This ` +
+        'is usually memory pressure, or a colour type the active Skia backend ' +
+        'refuses.');
+}
+/**
+ * The controller's `ingest` seam, implemented.
+ *
+ * `PdfControllerOptions.ingest` is injected precisely so the controller can run
+ * under plain node in vitest; this is the real one, and it is drop-in:
+ * `createPdfController({..., ingest: ingestRaster})`.
+ *
+ * `docRect` and `scale` are copied from the META, not re-derived from the
+ * pixels. That is THE ONE RULE in miniature — the bytes are whatever the
+ * backend produced, but the rect they are drawn at is the rect they were
+ * requested for, and rounding the pixel size must never move it.
+ *
+ * `bytes` is the RESIDENT footprint of the image (see `rasterByteLength`), not
+ * the source buffer's length: after ingest the source buffer is collectable and
+ * what the cache budget is accounting for is the image — both copies of it.
+ */
+export function ingestRaster(pixels, meta) {
+    return {
+        key: meta.key,
+        page: meta.page,
+        role: meta.role,
+        image: imageFromPixels(pixels),
+        docRect: meta.docRect,
+        scale: meta.scale,
+        epoch: meta.epoch,
+        bytes: rasterByteLength(pixels.width, pixels.height),
+    };
+}