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

package/dist/react/PdfContentView.js

@@ -0,0 +1,189 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The ONE component.
+ *
+ * It draws whatever `content` says, at the doc-space rects `content` carries, and
+ * it does nothing else. No gestures, no viewport, no shared values, no `<Canvas>`.
+ * It is meant to be mounted inside SOMEBODY ELSE'S `<Group transform={...}>`:
+ *
+ *   <Canvas>
+ *     <Group transform={worldTransform}>
+ *       <PdfContentView content={content} />
+ *       ...the host's own annotation layers...
+ *     </Group>
+ *   </Canvas>
+ *
+ * THE ONE RULE: the transform decides WHEN to rasterize, never WHAT to draw. Every
+ * number this component hands to Skia is a plain JS number read off a frozen
+ * `PdfContent`, so a pan or a zoom re-records the host's scene without this
+ * subtree changing at all.
+ */
+import { Children, isValidElement, useEffect, useMemo } from 'react';
+/*
+ * LEAF IMPORTS, NOT THE BARREL — and this is load-bearing, not fussiness.
+ *
+ * `import {Group, Image, Rect, Paint} from '@shopify/react-native-skia'` is a
+ * VALUE import of a package whose barrel is
+ * `export * from "./skia"` -> `export {Skia} from "./Skia"` -> on web,
+ * `export const Skia = JsiSkApi(global.CanvasKit)`. RN Skia declares no
+ * `sideEffects: false` and no `exports` map, so no bundler may drop that
+ * evaluation, and it is taken ONCE: reach it before `LoadSkiaWeb` resolves and
+ * the api is permanently broken (see `../skia/skia-api.ts`).
+ *
+ * That one line was the last thing keeping the package ROOT from being safe to
+ * evaluate during rock-desktop's SSR pass — `PdfContentView` is on the root
+ * barrel, so naming the package named `Skia.web.js`. MEASURED with a Vite build,
+ * not inferred: a bundle of this file used to contain
+ * `JsiSkApi(global.CanvasKit)` and now does not, while a bundle of the bare
+ * specifier still does.
+ *
+ * The five modules below are the leaves the barrel would have reached anyway.
+ * Each is a handful of lines that imports nothing but `react` (the components)
+ * or nothing at all (the enums), so this costs no bundle size on either
+ * platform, and on web the module instance is IDENTICAL to the barrel's —
+ * `lib/module/index.js` -> `renderer/index.js` -> `renderer/components/index.js`
+ * is the same file graph. Legal because RN Skia publishes `lib/**` and declares
+ * no `exports` map; same standing as boldr-utils' deep import of
+ * `@shopify/react-native-skia/lib/module/web/index.js` for `WithSkiaWeb`.
+ *
+ * `GroupProps` / `SamplingOptions` stay on the bare specifier because
+ * `import type` is erased entirely and reaches no module at runtime.
+ */
+import { Group } from '@shopify/react-native-skia/lib/module/renderer/components/Group.js';
+import { Paint } from '@shopify/react-native-skia/lib/module/renderer/components/Paint.js';
+import { Image } from '@shopify/react-native-skia/lib/module/renderer/components/image/Image.js';
+import { Rect } from '@shopify/react-native-skia/lib/module/renderer/components/shapes/Rect.js';
+import { FilterMode, MipmapMode, } from '@shopify/react-native-skia/lib/module/skia/types/Image/Image.js';
+/* ------------------------------------------------------------------ *
+ * Sampling
+ * ------------------------------------------------------------------ */
+/*
+ * One frozen object per variant, created ONCE at module scope.
+ *
+ * RN Skia's `shallowEq` is REFERENCE equality on every prop, and `prepareUpdate`
+ * returns null when the props compare equal. An inline `{filter: FilterMode.Linear}`
+ * is a fresh object on every render, so every single render of every single
+ * <Image> would be treated as a real prop change and re-enter the node's update
+ * path — the exact per-frame cost this package exists to avoid.
+ */
+const SAMPLING_LINEAR = Object.freeze({
+    filter: FilterMode.Linear,
+    // Explicitly None. See the `sampling` JSDoc: mipmaps are unreachable here.
+    mipmap: MipmapMode.None,
+});
+const SAMPLING_NEAREST = Object.freeze({
+    filter: FilterMode.Nearest,
+    mipmap: MipmapMode.None,
+});
+/** Mitchell (B=C=1/3) — the standard "photographic" cubic, and what Skia's own
+ * `MitchellCubicSampling` uses. Frozen locally so we never hand a mutable object
+ * owned by the Skia package into a memoised prop. */
+const SAMPLING_CUBIC = Object.freeze({ B: 1 / 3, C: 1 / 3 });
+const SAMPLING = Object.freeze({
+    linear: SAMPLING_LINEAR,
+    nearest: SAMPLING_NEAREST,
+    cubic: SAMPLING_CUBIC,
+});
+const IS_DEV = typeof __DEV__ !== 'undefined'
+    ? __DEV__ === true
+    : typeof process !== 'undefined' &&
+        process.env?.['NODE_ENV'] !== 'production';
+/**
+ * Is this child RN Skia's `<Paint>`? Identity first, NAME as a fallback.
+ *
+ * The fallback is the price of the leaf import above, and it is only owed on
+ * NATIVE: Metro resolves `@shopify/react-native-skia` through its `react-native`
+ * main field to `src/index.ts`, so a host's `<Paint>` comes from `src/renderer/`
+ * while this file's comes from `lib/module/renderer/`. Two different function
+ * objects for the same component, and `===` misses. On web (and under vitest,
+ * whose shim is backed by the same `lib/module` tree) both sides resolve to the
+ * one module and identity is exact.
+ *
+ * Both halves are cheap to be wrong about: this feeds a `__DEV__` console
+ * warning about a documented misuse, so a false negative loses a warning and a
+ * false positive (a host component of the host's own that happens to be named
+ * `Paint`) prints one that names exactly what it saw. Neither changes what is
+ * drawn. That is the whole reason a name check is acceptable here and would not
+ * be anywhere the render depends on it.
+ */
+function isPaintNode(type) {
+    if (type === Paint) {
+        return true;
+    }
+    return (typeof type === 'function' && type.name === 'Paint');
+}
+/* ------------------------------------------------------------------ *
+ * Component
+ * ------------------------------------------------------------------ */
+function rasterImage(raster, sampling) {
+    const { docRect } = raster;
+    return (_jsx(Image
+    // `raster.key` is the cache key: globally unique and stable for as long as
+    // the bytes live. Using it verbatim (rather than prefixing by role) means a
+    // raster demoted from `detail` to `retiring` keeps its Skia node instead of
+    // being destroyed and recreated on the swap commit.
+    , { image: raster.image, 
+        // The raster's docRect IS the rect the bytes were rendered for — never
+        // inset. See the PdfRaster invariant.
+        x: docRect.x, y: docRect.y, width: docRect.width, height: docRect.height, 
+        // fit="fill" ON EVERY IMAGE, ALWAYS. RN Skia's <Image> defaults to
+        // "contain", which letterboxes whenever the bitmap's aspect ratio differs
+        // from the destination rect by even a rounding error — silently shifting
+        // the page a fraction of a point and misregistering it against every
+        // annotation layer drawn above it. "fill" makes the destination rect
+        // authoritative, which is the whole premise of doc-space rects.
+        fit: "fill", sampling: sampling }, raster.key));
+}
+export function PdfContentView({ content, zIndex, sampling = 'linear', paperColor = null, opacity, blendMode, children, }) {
+    const samplingOptions = SAMPLING[sampling] ?? SAMPLING_LINEAR;
+    useEffect(() => {
+        if (!IS_DEV) {
+            return;
+        }
+        Children.forEach(children, child => {
+            if (isValidElement(child) && isPaintNode(child.type)) {
+                console.warn('[react-native-pdf-canvas] PdfContentView received a <Paint> child. A Paint ' +
+                    'child draws each node twice (once at the declared paint, once at the ' +
+                    'inherited one), and paintDeclarations.clear() runs on the first drawing — ' +
+                    'so it would apply to the base raster and to none of the detail rasters. ' +
+                    'Pass a ColorFilter / ImageFilter / Shader / PathEffect declaration instead, ' +
+                    'or wrap PdfContentView in your own <Group>.');
+            }
+        });
+    }, [children]);
+    // A single flat array so React keys are not namespaced by an outer array index —
+    // otherwise reordering pages (a layout change) would remount every image node
+    // even though the rasters themselves are unchanged.
+    const nodes = useMemo(() => {
+        const out = [];
+        if (paperColor != null) {
+            for (const page of content.pages) {
+                const { pageRect } = page;
+                out.push(_jsx(Rect, { x: pageRect.x, y: pageRect.y, width: pageRect.width, height: pageRect.height, color: paperColor }, `paper:${page.page}`));
+            }
+        }
+        for (const page of content.pages) {
+            // BASE first: the whole page at fit scale, in one or more pieces whose union
+            // is the page rect. It is never emptied once populated, and it is the entire
+            // anti-blank mechanism — everything above it is an optional sharpening pass
+            // over a page that is already fully painted. Within the set the order does
+            // not matter: the pieces overlap by a couple of device pixels and carry the
+            // same bytes there.
+            for (const raster of page.base) {
+                out.push(rasterImage(raster, samplingOptions));
+            }
+            // RETIRING before DETAIL. The previous detail set has to draw UNDER its
+            // replacement: it exists only to cover the region the new set has not
+            // finished painting, and drawing it over would show stale, wrongly-scaled
+            // pixels on top of correct ones.
+            for (const raster of page.retiring) {
+                out.push(rasterImage(raster, samplingOptions));
+            }
+            for (const raster of page.detail) {
+                out.push(rasterImage(raster, samplingOptions));
+            }
+        }
+        return out;
+    }, [content, paperColor, samplingOptions]);
+    return (_jsxs(Group, { zIndex: zIndex, opacity: opacity, blendMode: blendMode, children: [children, nodes] }));
+}

package/dist/react/index.d.ts

@@ -0,0 +1,6 @@
+export { PdfContentView } from './PdfContentView.js';
+export type { PdfContentViewProps, PdfBlendMode } from './PdfContentView.js';
+export { usePdfDocument, openPdfDocument, makeSkImageFromPixels, setDefaultRasterizer, getDefaultRasterizer, } from './usePdfDocument.js';
+export type { PdfDocument, PdfDocumentStatus, PdfPageRender, PdfRenderOptions, UsePdfDocumentOptions, UsePdfDocumentResult, } from './usePdfDocument.js';
+export { usePdfLayer, DEFAULT_PAGE_SELECTION } from './usePdfLayer.js';
+export type { PdfLayer, PdfOnScreenPages, PdfPageSelection, PdfPageWindow, UsePdfLayerOptions, } from './usePdfLayer.js';

package/dist/react/index.js

@@ -0,0 +1,3 @@
+export { PdfContentView } from './PdfContentView.js';
+export { usePdfDocument, openPdfDocument, makeSkImageFromPixels, setDefaultRasterizer, getDefaultRasterizer, } from './usePdfDocument.js';
+export { usePdfLayer, DEFAULT_PAGE_SELECTION } from './usePdfLayer.js';

package/dist/react/usePdfDocument.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Opening a PDF, and rendering one-off page rasters from it.
+ *
+ * The hook mirrors RN Skia's `useImage` contract — null until ready, never
+ * throws, mount-guarded, keyed on source identity — with ONE deliberate
+ * difference: it CLOSES the document on unmount. `useImage` can get away with
+ * leaving cleanup to the JSI finaliser because an SkImage is only bytes; a PDF
+ * handle is a file descriptor (PDFium's `FPDF_LoadDocument`, Android's
+ * `ParcelFileDescriptor`, PDFKit's mapped file). Leaking those is how a document
+ * browser dies at the fd limit after a few dozen opens.
+ *
+ * `renderPage` is what makes this package generically useful rather than shaped
+ * around one screen: thumbnail strips, a print preview, a static first-page hero
+ * all want a single raster at a chosen size and none of them want an epoch, a
+ * cadence policy, or a controller.
+ */
+import type { SkImage } from '@shopify/react-native-skia';
+import { PdfError } from '../types.js';
+import type { DocRect, DocSize, PageGeometry, PageRasterizer, PdfSource, PixelSize, RasterPixels, RasterizerCapabilities, RasterizerHandle } from '../types.js';
+/** Install the rasterizer used when `usePdfDocument` / `openPdfDocument` are not
+ * given one explicitly. Returns the previous value so a test can restore it. */
+export declare function setDefaultRasterizer(rasterizer: PageRasterizer | null): PageRasterizer | null;
+export declare function getDefaultRasterizer(): PageRasterizer | null;
+/** A single raster produced by `PdfDocument.renderPage`. */
+export interface PdfPageRender {
+    readonly page: number;
+    readonly image: SkImage;
+    /** Exactly the doc-space rect the bytes were rendered for. Never inset. */
+    readonly docRect: DocRect;
+    /** Device pixels per PDF point. */
+    readonly scale: number;
+    readonly pixels: PixelSize;
+    readonly bytes: number;
+    /**
+     * Drop the GPU/CPU image. EXPLICIT because the caller owns this raster — it is
+     * not in the layer cache and nothing else will ever free it.
+     */
+    release(): void;
+}
+export interface PdfRenderOptions {
+    /** Doc-space rect to render. Defaults to the whole page at the origin. */
+    docRect?: DocRect;
+    /** Device pixels per PDF point. Ignored when `widthPx` is given. */
+    scale?: number;
+    /** Target width in device pixels; derives `scale` from `docRect.width`. */
+    widthPx?: number;
+    /**
+     * Draw PDF-embedded annotations into the raster.
+     *
+     * Defaults to TRUE here — a file raster (thumbnail, print, hero) is expected to
+     * look like the document does in any other viewer. The layer path passes false,
+     * because the Skia scene draws the app's own annotations and they would
+     * double-draw. Silently downgraded to false if the backend cannot do it.
+     */
+    annotations?: boolean;
+    /**
+     * Not in the assignment's option list, but `RasterRequest.background` is
+     * required and defaulting it invisibly is exactly the "opaque white under a
+     * transparent PDF" bug that `paperColor` defaults to null to avoid. White is
+     * the right default for a file raster; transparent is available for callers
+     * compositing onto their own surface.
+     */
+    background?: 'white' | 'transparent';
+    signal?: AbortSignal;
+}
+export interface PdfDocument {
+    readonly pageCount: number;
+    /** Identifier of the backend that produced this document, for diagnostics. */
+    readonly rasterizerId: string;
+    readonly capabilities: RasterizerCapabilities;
+    /** Cheap: does not load a page. */
+    pageGeometry(index: number): PageGeometry;
+    /** Intrinsic sizes of every page, in the order a `PdfPageLayout` expects. */
+    pageSizes(): DocSize[];
+    renderPage(index: number, options?: PdfRenderOptions): Promise<PdfPageRender>;
+    /** True once `close()` has run. Every further call rejects with `cancelled`. */
+    readonly closed: boolean;
+    /**
+     * Release the underlying file handle. `usePdfDocument` owns this for documents
+     * it opened — do not call it on a hook-owned document. Public because
+     * `openPdfDocument` is usable outside React.
+     */
+    close(): void;
+    /**
+     * The open backend handle. Passed to `createPdfController`; not otherwise part
+     * of the supported surface.
+     */
+    readonly handle: RasterizerHandle;
+}
+/**
+ * ONE conversion for the whole package, delegated to the ingest seam.
+ *
+ * This used to be a second, simpler implementation of `imageFromPixels`, and the
+ * two disagreed on the things that are easy to get wrong and impossible to debug
+ * from a screenshot:
+ *
+ *  - `RasterPixels.format` travels with the bytes rather than being assumed,
+ *    because the backends genuinely differ (PDFium is BGRA unless asked
+ *    otherwise, Android `ARGB_8888` is RGBA in memory, CGBitmapContext is
+ *    whatever it was configured as). Getting it wrong swaps red and blue.
+ *  - `Skia.Data.fromBytes` IGNORES byteOffset/byteLength on native
+ *    (JsiSkDataFactory.h copies the whole ArrayBuffer), so a `subarray()` view
+ *    into a shared scratch buffer ingests shifted bytes and shears. Ingest
+ *    copies to a tight buffer; this function did not.
+ *  - A `MakeImage` that returns null for BGRA is retried once as RGBA there,
+ *    rather than losing the page.
+ *
+ * Kept as an export because it is the documented name for "pixels to SkImage"
+ * on the document surface, and `renderPage` below is its main caller.
+ */
+export declare function makeSkImageFromPixels(pixels: RasterPixels): SkImage;
+/**
+ * Open a document outside React. The caller owns `close()`.
+ */
+export declare function openPdfDocument(source: PdfSource, rasterizer?: PageRasterizer): Promise<PdfDocument>;
+export type PdfDocumentStatus = 'idle' | 'loading' | 'ready' | 'error';
+export interface UsePdfDocumentResult {
+    document: PdfDocument | null;
+    status: PdfDocumentStatus;
+    error: PdfError | null;
+}
+export interface UsePdfDocumentOptions {
+    rasterizer?: PageRasterizer;
+}
+/**
+ * Open `source` and keep it open for the life of the component.
+ *
+ * KEYED ON SOURCE IDENTITY, exactly like `useImage`: the effect re-runs when the
+ * `source` REFERENCE changes, so an inline `{uri}` object literal reopens the file
+ * on every render. Memoise it, or hoist it to a module constant.
+ *
+ * Never throws. A failure lands in `error` with a `PdfErrorCode` on it.
+ */
+export declare function usePdfDocument(source: PdfSource | null | undefined, options?: UsePdfDocumentOptions): UsePdfDocumentResult;

package/dist/react/usePdfDocument.js

@@ -0,0 +1,275 @@
+/**
+ * Opening a PDF, and rendering one-off page rasters from it.
+ *
+ * The hook mirrors RN Skia's `useImage` contract — null until ready, never
+ * throws, mount-guarded, keyed on source identity — with ONE deliberate
+ * difference: it CLOSES the document on unmount. `useImage` can get away with
+ * leaving cleanup to the JSI finaliser because an SkImage is only bytes; a PDF
+ * handle is a file descriptor (PDFium's `FPDF_LoadDocument`, Android's
+ * `ParcelFileDescriptor`, PDFKit's mapped file). Leaking those is how a document
+ * browser dies at the fd limit after a few dozen opens.
+ *
+ * `renderPage` is what makes this package generically useful rather than shaped
+ * around one screen: thumbnail strips, a print preview, a static first-page hero
+ * all want a single raster at a chosen size and none of them want an epoch, a
+ * cadence policy, or a controller.
+ */
+import { useEffect, useState } from 'react';
+// Through the `./skia` barrel — see the note in `usePdfLayer.ts`.
+import { imageFromPixels } from '../skia/index.js';
+import { PdfError } from '../types.js';
+/* ------------------------------------------------------------------ *
+ * Default rasterizer registry
+ * ------------------------------------------------------------------ *
+ *
+ * CONTRACT GAP, flagged rather than papered over: `PageRasterizer` is documented
+ * as "injected per document, defaulting to the platform module", but the package
+ * entry points are platform-agnostic one-line re-exports (see index.native.ts),
+ * so there is no entry-point seam to hang a platform default on, and importing a
+ * guessed module path from here would couple this file to a file it does not own.
+ *
+ * Instead the default is a settable module-level slot. The platform module (or
+ * the app, or a test) installs it once; `usePdfDocument` falls back to it when no
+ * rasterizer is passed. If a platform module later wants to register itself on
+ * import, it calls `setDefaultRasterizer` at module scope and nothing here
+ * changes.
+ */
+let defaultRasterizer = null;
+/** Install the rasterizer used when `usePdfDocument` / `openPdfDocument` are not
+ * given one explicitly. Returns the previous value so a test can restore it. */
+export function setDefaultRasterizer(rasterizer) {
+    const previous = defaultRasterizer;
+    defaultRasterizer = rasterizer;
+    return previous;
+}
+export function getDefaultRasterizer() {
+    return defaultRasterizer;
+}
+/* ------------------------------------------------------------------ *
+ * Pixels -> SkImage
+ * ------------------------------------------------------------------ */
+/**
+ * ONE conversion for the whole package, delegated to the ingest seam.
+ *
+ * This used to be a second, simpler implementation of `imageFromPixels`, and the
+ * two disagreed on the things that are easy to get wrong and impossible to debug
+ * from a screenshot:
+ *
+ *  - `RasterPixels.format` travels with the bytes rather than being assumed,
+ *    because the backends genuinely differ (PDFium is BGRA unless asked
+ *    otherwise, Android `ARGB_8888` is RGBA in memory, CGBitmapContext is
+ *    whatever it was configured as). Getting it wrong swaps red and blue.
+ *  - `Skia.Data.fromBytes` IGNORES byteOffset/byteLength on native
+ *    (JsiSkDataFactory.h copies the whole ArrayBuffer), so a `subarray()` view
+ *    into a shared scratch buffer ingests shifted bytes and shears. Ingest
+ *    copies to a tight buffer; this function did not.
+ *  - A `MakeImage` that returns null for BGRA is retried once as RGBA there,
+ *    rather than losing the page.
+ *
+ * Kept as an export because it is the documented name for "pixels to SkImage"
+ * on the document surface, and `renderPage` below is its main caller.
+ */
+export function makeSkImageFromPixels(pixels) {
+    return imageFromPixels(pixels);
+}
+/* ------------------------------------------------------------------ *
+ * openPdfDocument
+ * ------------------------------------------------------------------ */
+/**
+ * Read the abort flag THROUGH A CALL, on both sides of the render.
+ *
+ * `if (signal.aborted === true)` narrows `signal.aborted` to `false | undefined`
+ * for the rest of the function, and TypeScript keeps that narrowing across an
+ * `await` — it has no way to know that an AbortController on the other side of
+ * the boundary can flip the flag while the render is in flight. The post-render
+ * check would therefore be reported as dead code (TS2367) while being the one
+ * that actually matters: it is what stops a raster landing for a viewport, or a
+ * component, that is already gone. A function call produces no narrowing, so both
+ * checks stay honest.
+ */
+function isAborted(signal) {
+    return signal?.aborted === true;
+}
+function toPdfError(cause, fallback) {
+    if (cause instanceof PdfError) {
+        return cause;
+    }
+    const message = cause instanceof Error ? cause.message : String(cause);
+    return new PdfError('backend-failure', `${fallback}: ${message}`, { cause });
+}
+/**
+ * Open a document outside React. The caller owns `close()`.
+ */
+export async function openPdfDocument(source, rasterizer) {
+    const backend = rasterizer ?? defaultRasterizer;
+    if (backend === null || backend === undefined) {
+        throw new PdfError('unsupported', 'No PageRasterizer available. Pass one explicitly, or install a platform default with setDefaultRasterizer().');
+    }
+    let handle;
+    try {
+        handle = await backend.open(source);
+    }
+    catch (cause) {
+        throw toPdfError(cause, 'Failed to open PDF');
+    }
+    let closed = false;
+    const doc = {
+        handle,
+        pageCount: handle.pageCount,
+        rasterizerId: backend.id,
+        capabilities: backend.capabilities,
+        get closed() {
+            return closed;
+        },
+        pageGeometry(index) {
+            return handle.pageGeometry(index);
+        },
+        pageSizes() {
+            const sizes = [];
+            for (let i = 0; i < handle.pageCount; i++) {
+                const geometry = handle.pageGeometry(i);
+                sizes.push({ width: geometry.width, height: geometry.height });
+            }
+            return sizes;
+        },
+        async renderPage(index, options) {
+            if (closed) {
+                throw new PdfError('cancelled', 'renderPage called on a closed PdfDocument');
+            }
+            if (!Number.isInteger(index) || index < 0 || index >= handle.pageCount) {
+                // No 'invalid-argument' code exists in PdfErrorCode; 'backend-failure' is
+                // the closest honest bucket. Flagged in the report.
+                throw new PdfError('backend-failure', `page index ${index} is out of range (pageCount ${handle.pageCount})`);
+            }
+            if (isAborted(options?.signal)) {
+                throw new PdfError('cancelled', 'renderPage aborted before it started');
+            }
+            const geometry = handle.pageGeometry(index);
+            const docRect = options?.docRect ?? {
+                x: 0,
+                y: 0,
+                width: geometry.width,
+                height: geometry.height,
+            };
+            if (!(docRect.width > 0) || !(docRect.height > 0)) {
+                throw new PdfError('backend-failure', `renderPage needs a positive docRect, got ${docRect.width}x${docRect.height}`);
+            }
+            const widthPx = options?.widthPx;
+            const scale = widthPx !== undefined && widthPx > 0
+                ? widthPx / docRect.width
+                : (options?.scale ?? 1);
+            if (!(scale > 0) || !Number.isFinite(scale)) {
+                throw new PdfError('backend-failure', `renderPage needs a positive scale, got ${scale}`);
+            }
+            let pixels;
+            try {
+                pixels = await handle.render({
+                    page: index,
+                    docRect,
+                    scale,
+                    // A backend that cannot draw annotations would otherwise silently
+                    // ignore the flag; downgrading here keeps the request honest.
+                    annotations: (options?.annotations ?? true) &&
+                        backend.capabilities.annotations,
+                    background: options?.background ?? 'white',
+                }, options?.signal);
+            }
+            catch (cause) {
+                throw toPdfError(cause, `Failed to render page ${index}`);
+            }
+            // The handle may have been closed while the render was in flight; the image
+            // itself is fine (the bytes are already copied out) but the caller almost
+            // certainly no longer wants it.
+            if (isAborted(options?.signal)) {
+                throw new PdfError('cancelled', 'renderPage aborted');
+            }
+            const image = makeSkImageFromPixels(pixels);
+            let released = false;
+            return {
+                page: index,
+                image,
+                docRect,
+                scale,
+                pixels: { width: pixels.width, height: pixels.height },
+                bytes: pixels.rowBytes * pixels.height,
+                release() {
+                    if (released) {
+                        return;
+                    }
+                    released = true;
+                    image.dispose();
+                },
+            };
+        },
+        close() {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            handle.close();
+        },
+    };
+    return doc;
+}
+const IDLE = Object.freeze({
+    document: null,
+    status: 'idle',
+    error: null,
+});
+const LOADING = Object.freeze({
+    document: null,
+    status: 'loading',
+    error: null,
+});
+/**
+ * Open `source` and keep it open for the life of the component.
+ *
+ * KEYED ON SOURCE IDENTITY, exactly like `useImage`: the effect re-runs when the
+ * `source` REFERENCE changes, so an inline `{uri}` object literal reopens the file
+ * on every render. Memoise it, or hoist it to a module constant.
+ *
+ * Never throws. A failure lands in `error` with a `PdfErrorCode` on it.
+ */
+export function usePdfDocument(source, options) {
+    const rasterizer = options?.rasterizer;
+    const [state, setState] = useState(IDLE);
+    useEffect(() => {
+        if (source === null || source === undefined) {
+            setState(IDLE);
+            return;
+        }
+        // Mount guard: `cancelled` covers both unmount and a source change landing
+        // before the open resolves. Without it a slow open on a discarded source
+        // overwrites the state of the current one.
+        let cancelled = false;
+        let opened = null;
+        setState(LOADING);
+        openPdfDocument(source, rasterizer).then(document => {
+            if (cancelled) {
+                // We own this handle and nobody will ever see it — close it here or the
+                // fd leaks for the lifetime of the process.
+                document.close();
+                return;
+            }
+            opened = document;
+            setState({ document, status: 'ready', error: null });
+        }, (cause) => {
+            if (cancelled) {
+                return;
+            }
+            setState({
+                document: null,
+                status: 'error',
+                error: toPdfError(cause, 'Failed to open PDF'),
+            });
+        });
+        return () => {
+            cancelled = true;
+            // THE DIFFERENCE FROM useImage: a PDF handle is a file descriptor, not just
+            // bytes, so unmount has to close it rather than leaving it to the finaliser.
+            opened?.close();
+            opened = null;
+        };
+    }, [source, rasterizer]);
+    return state;
+}