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

package/dist/types.d.ts

@@ -0,0 +1,611 @@
+/**
+ * The type contract for @reekon-tools/react-native-pdf-canvas.
+ *
+ * THE ONE RULE: the transform decides WHEN to rasterize, never WHAT to draw.
+ *
+ * Every rect in this file is in DOC SPACE — PDF points, y-down, origin at the
+ * page's top-left. That is exactly what PDFium's CPDF_Page::GetDisplayMatrix()
+ * emits, so a PDFium backend is a pass-through and every other backend adapts
+ * to it. There is deliberately no `coordinateSystem` option: two conventions in
+ * one package is how device pixel ratio gets applied twice.
+ *
+ * Nothing here imports React, react-native, or reanimated. The only external
+ * type is SkImage, and it is type-only.
+ */
+import type { SkImage } from '@shopify/react-native-skia';
+/** A rect in doc space: PDF points, y-down, origin top-left. */
+export interface DocRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface DocSize {
+    width: number;
+    height: number;
+}
+/** Device-pixel size. Distinct from DocSize so the two cannot be swapped. */
+export interface PixelSize {
+    width: number;
+    height: number;
+}
+export type PageRotation = 0 | 90 | 180 | 270;
+/** A page's intrinsic geometry, in PDF points, already accounting for /Rotate. */
+export interface PageGeometry {
+    index: number;
+    /** CropBox width in points, after rotation is applied. */
+    width: number;
+    /** CropBox height in points, after rotation is applied. */
+    height: number;
+    rotation: PageRotation;
+}
+/**
+ * What the host tells us about where it is looking. Pushed at settle rate; the
+ * package never reads a shared value to obtain it.
+ *
+ * `scale` is DEVICE PIXELS PER PDF POINT — i.e. zoom * pixelRatio, already
+ * combined. The package never derives it, because a host may wrap the scene in
+ * a further transform the package cannot see.
+ */
+export interface ViewportSnapshot {
+    visibleDocRect: DocRect;
+    scale: number;
+}
+export type PdfSource = {
+    uri: string;
+    password?: string;
+} | {
+    data: Uint8Array;
+    password?: string;
+};
+export type PdfErrorCode = 'not-found' | 'password-required' | 'password-incorrect' | 'corrupt' | 'unsupported' | 'cancelled' | 'out-of-memory' | 'backend-failure';
+export declare class PdfError extends Error {
+    readonly code: PdfErrorCode;
+    constructor(code: PdfErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Byte order of a raster. The three backends produce different orderings and
+ * the descriptor travels with the bytes rather than being assumed:
+ * PDFium emits BGRA natively (or RGBA with FPDF_REVERSE_BYTE_ORDER), Android
+ * Bitmap ARGB_8888 is RGBA in memory, CGBitmapContext is configured explicitly.
+ */
+export type PixelFormat = 'rgba8888' | 'bgra8888';
+/**
+ * Whether a raster's colour channels have been multiplied by its alpha channel.
+ *
+ * SAME STANDING AS `PixelFormat`, and required for the same reason: the engines
+ * genuinely disagree, so the descriptor travels with the bytes rather than being
+ * assumed. Getting the byte order wrong swaps red and blue; getting this wrong
+ * darkens or brightens every partially-transparent pixel, which is subtler and
+ * therefore worse.
+ *
+ * `'premultiplied'` — each channel is already scaled by alpha, so a 62%-covered
+ * white edge is stored `[158, 158, 158, 158]`. Android's `Bitmap` ARGB_8888 is
+ * this by default (`isPremultiplied()` is true unless a caller opts out) and so
+ * is a `CGBitmapContext` created `kCGImageAlphaPremultipliedFirst`.
+ *
+ * `'straight'` — the channels carry the colour and alpha carries the coverage
+ * independently, so the same edge is stored `[255, 255, 255, 158]`. MEASURED:
+ * PDFium reads `[255, 255, 255, 157]` and pdf.js `[255, 255, 255, 160]` for an
+ * antialiased opaque-white edge over a transparent page; premultiplied would
+ * have been `~[157, 157, 157, 157]`. A canvas `getImageData` buffer is likewise
+ * straight (a 50% grey patch reads `[128, 128, 128, 128]`).
+ *
+ * NOT DEFAULTABLE, on purpose. Two of the three engines this package knows about
+ * emit `'straight'` and one emits `'premultiplied'`, so there is no default that
+ * is right more often than it is wrong — and a default is exactly how a global
+ * `AlphaType.Premul` constant survived in `ingest.ts` until the first backend
+ * that renders `background: 'transparent'` would have been silently wrong.
+ *
+ * INVISIBLE UNDER `background: 'white'`. A fully opaque pixel is byte-identical
+ * in both encodings, which is why this can be stated wrongly for a long time
+ * without anything going visibly bad. It only bites on a transparent
+ * background — which is in the `RasterRequest` contract.
+ */
+export type AlphaEncoding = 'premultiplied' | 'straight';
+/**
+ * How a backend's bytes reached JS.
+ *
+ * Not a capability in the "can it do X" sense — it is a fact about the build and
+ * the device, resolved at runtime, and the reason it is surfaced at all is that
+ * the difference between these two is ~85x on a tile. A silent fallback is how a
+ * transport rewrite ships as no change whatsoever, so both
+ * `RasterizerCapabilities.transport` and `RasterPhaseTimings.transport` carry it:
+ * the first says what was negotiated, the second says what each tile actually
+ * used.
+ *
+ * - `base64` — a string across the bridge, decoded in JS. Works everywhere.
+ * - `jsi-arraybuffer` — an ArrayBuffer wrapping native memory, no string and no
+ *   decode.
+ * - `direct` — the backend produced the bytes in JS already (the fake one).
+ */
+export type RasterTransport = 'base64' | 'jsi-arraybuffer' | 'direct';
+/**
+ * What a backend spent getting its pixels as far as `RasterPixels`.
+ *
+ * OPTIONAL AND PURELY OBSERVATIONAL. Nothing in the package reads these to make
+ * a decision; the controller copies them into a `raster-phases` diagnostic and
+ * that is all. A backend that reports nothing is not degraded in any way.
+ *
+ * It exists because the cost of a tile is split across two modules that never
+ * see each other: the BACKEND owns the transport (a bridge hop, a base64
+ * decode), and the CONTROLLER owns the ingest (`Skia.Data.fromBytes` +
+ * `Skia.Image.MakeImage`). Subtracting one total from another is how the
+ * three terms got conflated in the first place, and the difference matters
+ * enormously — a transport rewrite deletes the first two and cannot touch the
+ * third.
+ */
+export interface RasterPhaseTimings {
+    /**
+     * The transport round trip, INCLUDING whatever the backend did at the far end
+     * of it.
+     *
+     * On Android this is `await native.render(...)`: bridge marshalling in both
+     * directions plus the ~27.5 ms p50 of Java work (open, render, extract,
+     * base64-encode) that the instrumented `PdfCanvasPhaseTimingTest` measures
+     * separately. Subtracting the Java figure from this one is what isolates
+     * marshalling.
+     *
+     * CONTAMINATED BY CONCURRENCY, and unavoidably so: this is wall time across an
+     * `await`, so with more than one render lane it also contains whatever the JS
+     * thread did for the OTHER lanes in the meantime. `decodeMs` and `ingestMs`
+     * are synchronous blocks and carry no such contamination.
+     */
+    bridgeMs: number;
+    /** Decoding the transport payload into bytes. Zero for a backend with none. */
+    decodeMs: number;
+    /**
+     * Characters of transport payload — the base64 string's length on Android.
+     * Zero when a backend moves bytes without stringifying them, which is the
+     * whole point of measuring it.
+     */
+    payloadChars: number;
+    /**
+     * Whether `bytes` is already exactly its own ArrayBuffer.
+     *
+     * When false, ingest must copy the whole buffer before Skia sees it (see
+     * `isTightBuffer`). Reported rather than inferred so a transport change can be
+     * held to it.
+     */
+    tight: boolean;
+    /**
+     * Which transport produced these bytes.
+     *
+     * OPTIONAL, because it was added after the field shipped and a backend that
+     * has only ever had one transport has nothing to disambiguate. Present on
+     * Android, where two transports coexist and the negotiated one can differ from
+     * the one a given tile got — a store that failed mid-session falls the whole
+     * rasterizer back, and the tile that triggered it reports `base64` while the
+     * capability still says otherwise until the next negotiation.
+     */
+    transport?: RasterTransport;
+}
+export interface RasterPixels {
+    bytes: Uint8Array;
+    width: number;
+    height: number;
+    /** Required. Skia.Image.MakeImage needs it and a wrong value shears the image. */
+    rowBytes: number;
+    format: PixelFormat;
+    /**
+     * Required, and deliberately not optional — see `AlphaEncoding`. Every backend
+     * states what it produces so none can inherit a default that is wrong for it.
+     */
+    alpha: AlphaEncoding;
+    /**
+     * ADDITIVE AND OPTIONAL. `RasterPixels` is the shipped seam that the web
+     * backend and the fake rasterizer also implement, so this had to cost them
+     * nothing: omitting it is the documented normal case, and no consumer branches
+     * on its presence except the controller's diagnostic emit.
+     */
+    timings?: RasterPhaseTimings;
+}
+export interface RasterRequest {
+    page: number;
+    /** The doc-space rect to render. Backends render exactly this rect. */
+    docRect: DocRect;
+    /** Device pixels per PDF point. */
+    scale: number;
+    /**
+     * Whether PDF-embedded annotations are drawn into the raster.
+     *
+     * TRUE for file rasters (thumbnails, print) — that is what the outgoing
+     * react-native-pdf-thumbnail did via PDFKit, and the app depends on it.
+     * FALSE for tiles, because the Skia layer draws the app's own annotations and
+     * they would double-draw.
+     */
+    annotations: boolean;
+    background: 'white' | 'transparent';
+}
+export interface RasterizerCapabilities {
+    /** Can render PDF-embedded annotations into the raster. */
+    annotations: boolean;
+    /** Honours the abort signal mid-render, not merely between requests. */
+    interruptibleRender: boolean;
+    text: boolean;
+    search: boolean;
+    links: boolean;
+    /**
+     * How many `render` calls this backend can usefully have in flight at once.
+     *
+     * A PROPERTY OF THE BACKEND, never a constant in the controller. Android's
+     * ceiling is the `PdfRendererPool` size — each slot is one more `PdfRenderer`
+     * on its own dup'd file descriptor, and a request beyond that blocks on the
+     * pool's queue rather than doing anything. A backend with one document handle
+     * and no pool declares 1 and is scheduled exactly as it is today.
+     *
+     * OPTIONAL, DEFAULTING TO 1, and that default is the safe one: an unaware
+     * backend keeps the strictly-sequential behaviour it was written against. The
+     * controller reads it as `min(bound, plan.items.length)`.
+     *
+     * IT IS NOT A PROMISE OF SPEEDUP, AND ON ANDROID IT IS A PROMISE OF THE
+     * OPPOSITE. Measured on an LG V60 (Snapdragon 865, API 33): AOSP serialises
+     * `PdfRenderer` behind a process-wide PDFium lock, so `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.8x — and the lock CONVOYS, so
+     * contending for it makes each call slower rather than merely unparallel. The
+     * Android backend therefore declares 1. It used to declare 2 to PIPELINE its
+     * base64 decode against the next tile's native work; the JSI transport deleted
+     * that decode, and re-measuring on the JSI path put every lane count above 1
+     * behind it on real documents. See `AndroidRasterizerOptions.poolSize` for the
+     * numbers.
+     *
+     * A backend whose rasterizing genuinely parallelises should still declare it.
+     * The lane machinery is not Android-specific and the controller has no opinion;
+     * this field is where a backend states what it can actually do.
+     */
+    maxConcurrentRenders?: number;
+    /**
+     * How this backend moves pixels into JS, as NEGOTIATED — resolved once when
+     * the rasterizer is constructed, not per render.
+     *
+     * OPTIONAL and observational. Nothing in the package branches on it; it exists
+     * so a host can SEE which path is live, because the fallback is invisible from
+     * the outside and the two differ by roughly 85x per tile. A backend that omits
+     * it is not making any claim.
+     */
+    transport?: RasterTransport;
+}
+/**
+ * The backend seam. Three implementations: platform rasterizers on native, a
+ * PDFium worker on web, a deterministic fake for tests. Injected per document,
+ * defaulting to the platform module.
+ */
+export interface PageRasterizer {
+    /** Stable identifier, surfaced in diagnostics so a bug report names a backend. */
+    readonly id: string;
+    readonly capabilities: RasterizerCapabilities;
+    open(source: PdfSource): Promise<RasterizerHandle>;
+}
+export interface RasterizerHandle {
+    readonly pageCount: number;
+    /** Cheap: must not load a page. */
+    pageGeometry(index: number): PageGeometry;
+    render(request: RasterRequest, signal?: AbortSignal): Promise<RasterPixels>;
+    close(): void;
+}
+export type RasterRole = 'base' | 'detail';
+/**
+ * One rasterized piece, ready to draw.
+ *
+ * INVARIANT: `docRect` is exactly the rect the bytes were rendered for. It is
+ * never inset. Adjacent detail pieces OVERLAP rather than abut, because
+ * RN Skia's <Image> has no src-rect prop — both draw paths hardcode src to the
+ * whole image, so drawing an inset rect would squash the full bitmap into it
+ * and misregister every piece against the layers above.
+ */
+export interface PdfRaster {
+    readonly key: string;
+    readonly page: number;
+    readonly role: RasterRole;
+    readonly image: SkImage;
+    readonly docRect: DocRect;
+    /** Device pixels per PDF point this raster was rendered at. */
+    readonly scale: number;
+    readonly epoch: number;
+    /**
+     * What this raster costs while it is MOUNTED, which is ~2x its pixels.
+     *
+     * Two allocations, not one. `SkImages::RasterFromData(info, data, rowBytes)`
+     * — what `Skia.Image.MakeImage` calls — SHARES the `SkData` and keeps it alive
+     * for the image's whole life, and the first time that image is drawn on a GPU
+     * canvas Skia uploads a budgeted texture of the same dimensions. Both are
+     * resident for as long as the raster is in the tree.
+     *
+     * `rasterByteLength` books both copies. See its comment for what that does to
+     * the meaning of `cacheBudgetBytes`.
+     */
+    readonly bytes: number;
+}
+export interface PdfPageContent {
+    readonly page: number;
+    /** Where this page sits in doc space, per the layout function. */
+    readonly pageRect: DocRect;
+    /**
+     * The whole page at fit scale, as one or more pieces whose union is exactly
+     * `pageRect`.
+     *
+     * ANTI-BLANK INVARIANT: never EMPTIED once populated. It was "never nulled
+     * once rastered" while this was a single raster; tiling the base makes it a
+     * set, and the promise is the same one — for a page inside the live window
+     * there is always something drawable under the detail layer. (A page that
+     * leaves the window by more than the base radius is deliberately emptied; that
+     * is the promise being kept for the pages you are LOOKING at.)
+     *
+     * Usually length 1. It splits for the same reason detail does — see
+     * `RasterPolicy.maxPieceDimension`, which bounds the in-flight transient of a
+     * single raster, and `maxTextureDimension`, which a piece may never exceed.
+     */
+    readonly base: readonly PdfRaster[];
+    /** Sharp overlays for the current viewport. Usually length 1. */
+    readonly detail: readonly PdfRaster[];
+    /** Previous detail set, held across the swap and released next commit. */
+    readonly retiring: readonly PdfRaster[];
+}
+/**
+ * A NEW FROZEN OBJECT PER EPOCH. Identity change is the swap signal.
+ *
+ * A "referentially stable handle mutated in place" cannot work: RN Skia's
+ * shallowEq is reference equality on every key but children, and prepareUpdate
+ * returns null on equality — the new SkImages would never enter the Skia tree,
+ * the raster would complete, memory would be spent, and nothing on screen would
+ * change. That commit is the expensive thing the cadence policy exists to make
+ * rare.
+ */
+export interface PdfContent {
+    readonly pages: readonly PdfPageContent[];
+    readonly epoch: number;
+    /** True while any planned raster for the current viewport is still missing. */
+    readonly settling: boolean;
+}
+/** Where pages sit in doc space. The package has no opinion. */
+export type PdfPageLayout = (pages: readonly DocSize[]) => DocRect[];
+/**
+ * Every constant the cadence depends on. All of these are DERIVED, not
+ * measured — see docs. A consumer with letter-size text documents on a DPR-1
+ * display swaps two fields rather than forking the package.
+ */
+export interface RasterPolicy {
+    /**
+     * Multiplier on the fit-zoom display scale for the whole-page base raster.
+     *
+     * NOT a fixed max-edge cap. A 2048px cap is calibrated for Letter pages; on
+     * an ARCH-D sheet it yields 0.790 px/pt against a fit display scale of 0.677,
+     * so the base is drawn MINIFIED — the aliasing regime, and unfixable because
+     * ImageCmd::draw hardcodes kStrict_SrcRectConstraint, which disables mipmaps.
+     */
+    baseQuality: number;
+    /** Hard ceiling on base raster pixels, after baseQuality. */
+    baseMaxPixels: number;
+    /** Fraction of the visible rect added on each side of a detail raster. */
+    detailOverflow: number;
+    /**
+     * HARDWARE ceiling on a piece's pixel DIMENSION, in device px. A piece may
+     * never exceed it: past the limit the texture upload FAILS and the piece draws
+     * nothing. 4096 is the only near-universal value.
+     *
+     * Distinct from `maxPieceDimension` below, and the two must not be merged.
+     * This one is a property of the device; that one is a choice about memory.
+     */
+    maxTextureDimension: number;
+    /**
+     * MEMORY policy on a piece's pixel DIMENSION, in device px, applied to the
+     * base layer and the detail layer alike.
+     *
+     * Nothing breaks when a piece exceeds it — this is not a limit the hardware
+     * has an opinion about. It exists to bound the TRANSIENT: one piece's bytes
+     * exist simultaneously as a platform bitmap, a JS `Uint8Array` and an
+     * `SkData`, so the whole-flow peak scales with the largest SINGLE raster in
+     * flight, not with the epoch's total. Splitting the same total area into more,
+     * smaller pieces leaves the resident bytes unchanged and cuts that peak.
+     *
+     * The effective cap is `min(maxPieceDimension, maxTextureDimension)`.
+     */
+    maxPieceDimension: number;
+    /** Hard ceiling on a single raster request, in pixels. */
+    maxRasterPixels: number;
+    /**
+     * Re-raster when currentScale / epochScale leaves [1/band, band].
+     * 1.414 at >=200ppi effective; 1.2 on DPR-1, where pixels are visible before
+     * any magnification.
+     */
+    sharpnessBand: number;
+    /**
+     * pdf.js's MOVEMENT_THRESHOLD, adopted verbatim. Re-raster when the padding
+     * remaining AHEAD of the motion is less than this fraction of the padding
+     * behind it.
+     */
+    movementThreshold: number;
+    /** Quiet-timer delay after a scale change (continuous input only). */
+    quietZoomMs: number;
+    /** Quiet-timer delay after a pan-only change. */
+    quietPanMs: number;
+    /** Force one raster this long after the last committed one under continued input. */
+    maxStaleMs: number;
+    /**
+     * Floor between epochs, enforced on BOTH paths.
+     *
+     * 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. Without a floor a user pinch-nudging three times while reading a
+     * dimension never sees a detail raster at all — every render is superseded
+     * before it lands. Default to the measured p95 raster time.
+     */
+    minEpochIntervalMs: number;
+    /** Soft cap on cached raster bytes. NOT a memory budget — see docs. */
+    cacheBudgetBytes: number;
+    /** Keep the previous detail set mounted after its replacement paints. */
+    retainPreviousDetail: boolean;
+}
+/** One raster the planner wants to exist. */
+export interface RasterPlanItem {
+    key: string;
+    page: number;
+    role: RasterRole;
+    docRect: DocRect;
+    scale: number;
+    pixels: PixelSize;
+}
+export interface RasterPlan {
+    items: RasterPlanItem[];
+    /** Scale the detail items were planned at, for the sharpness predicate. */
+    detailScale: number;
+    /**
+     * Bounding rect of everything this plan INTENDS to cover — the detail items
+     * plus `baseCoveredDocRect`. Null when the plan covers nothing.
+     *
+     * It is what the plan wanted, not what a run of it achieved, so it is NOT what
+     * an epoch records: see `EpochState.coveredRects`.
+     */
+    coveredDocRect: DocRect | null;
+    /**
+     * The part of `coveredDocRect` that no detail ITEM accounts for: the pages
+     * whose base is already at least as dense as the detail would be, and which
+     * therefore get no detail raster at all (see `planRasters`).
+     *
+     * Reported separately because the controller rebuilds the epoch's coverage
+     * from the rasters it actually PRODUCED, and there is no produced raster to
+     * rebuild this half from — the base is standing in for the detail here. A hole
+     * in the base itself is caught by the controller's per-piece base check
+     * instead, which forces a 'layout' epoch.
+     */
+    baseCoveredDocRect: DocRect | null;
+}
+/** What the planner needs to know about the current epoch to decide. */
+export interface EpochState {
+    detailScale: number;
+    /**
+     * Where this epoch was RESPONSIBLE for coverage: the doc rect of every page it
+     * planned.
+     *
+     * Coverage is judged over these regions and nowhere else, because most of the
+     * doc plane is not page. `continuousVertical` leaves a 12pt gutter between
+     * pages and centres narrower ones, so a viewport that spans two pages — the
+     * ordinary reading posture — always has doc area in it that NO raster can ever
+     * cover. Judging the whole visible rect would report that as a hole and fire
+     * 'coverage' on every settle for the life of the document.
+     *
+     * It is also what answers "am I looking somewhere this epoch never planned":
+     * the pages BEYOND these rects are the ones a scroll reaches, and their bounds
+     * is the containment test that used to be made against the covered rect.
+     */
+    pageRects: readonly DocRect[];
+    /**
+     * EXACTLY the doc rects this epoch has detail-quality coverage of — one entry
+     * per raster that was produced, plus the plan's `baseCoveredDocRect` where a
+     * base is standing in for detail.
+     *
+     * A SET, not the bounding rect, and that is the whole point. A tiled epoch
+     * that loses one piece (backend error, budget refusal) keeps its bounding rect
+     * intact — remove any single cell of a 2x2 grid and the other three still span
+     * it — so a bounding-rect predicate reports full coverage over a hole and
+     * never re-fires for it. `rectsCover` is an exact union test and does not.
+     *
+     * Empty means nothing is covered, which fires 'coverage' unconditionally.
+     */
+    coveredRects: readonly DocRect[];
+    committedAtMs: number;
+}
+export interface PdfController {
+    /**
+     * Continuous input — wheel, trackpad, momentum. Restarts a quiet timer.
+     * Cheap and idempotent: an identical plan is a no-op, because any state
+     * change costs a full re-record of the CONSUMER'S entire scene.
+     */
+    hint(viewport: ViewportSnapshot): void;
+    /**
+     * Discrete end — gesture lift-off, or an animation's completion callback.
+     * Evaluates and dispatches immediately, subject to minEpochIntervalMs.
+     *
+     * This MUST be called by the host. Settle cannot be sniffed: a withDecay
+     * fling at 2000px/s animates for ~38 seconds at reanimated's default
+     * deceleration, changing the shared value every frame, and `_animation` is
+     * cleared only on interruption — never on natural completion.
+     */
+    settle(viewport: ViewportSnapshot): void;
+    /** Gesture begin. Suppresses the continuous path entirely. */
+    suppress(): void;
+    /** Gesture end. Does not itself dispatch; call settle() for that. */
+    resume(): void;
+}
+export type PdfDiagnostic = {
+    type: 'raster';
+    key: string;
+    ms: number;
+    pixels: number;
+    backend: string;
+}
+/**
+ * The same tile as `raster`, broken into the terms a transport change can and
+ * cannot remove. Emitted ONLY when the backend reported `RasterPixels.timings`
+ * — so the fake backend, and therefore the whole vitest suite, never sees it.
+ *
+ * Note that `raster.ms` is NOT `totalMs`: `raster` is emitted BEFORE ingest
+ * runs, so it covers bridge + decode and stops there. This one is the whole
+ * per-tile cost the JS thread can see.
+ */
+ | {
+    type: 'raster-phases';
+    key: string;
+    backend: string;
+    /** Transport round trip including the native work. See RasterPhaseTimings. */
+    bridgeMs: number;
+    /** The payload decode — a hand-rolled base64 loop on Android today. */
+    decodeMs: number;
+    /**
+     * The `ingest` call and nothing else — `Skia.Data.fromBytes` +
+     * `Skia.Image.MakeImage`. The cache put is deliberately outside it.
+     *
+     * THE TERM NO TRANSPORT CHANGE CAN DELETE. `fromBytes` is
+     * `SkData::MakeWithCopy` and the image retains that copy; both survive any
+     * rewrite of how the bytes reached JS.
+     */
+    ingestMs: number;
+    totalMs: number;
+    payloadChars: number;
+    /** Decoded raster bytes, i.e. what a zero-copy transport would move. */
+    byteLength: number;
+    /** False means ingest had to copy the buffer before Skia saw it. */
+    tight: boolean;
+} | {
+    type: 'cache-hit';
+    key: string;
+} | {
+    type: 'evict';
+    key: string;
+    bytes: number;
+    reason: 'budget' | 'page-window' | 'epoch';
+} | {
+    type: 'epoch';
+    epoch: number;
+    items: number;
+    reason: EpochReason;
+    /**
+     * Planned pieces this epoch did NOT mount — a backend failure or a budget
+     * refusal. The field probe could only see `settling`, which is one bit for
+     * three different situations; this is the number that says which.
+     */
+    missing: number;
+} | {
+    type: 'skip';
+    reason: 'min-interval' | 'identical-plan' | 'suppressed';
+}
+/**
+ * A re-evaluation the CONTROLLER armed for itself, because an epoch committed
+ * with a hole in it and no host input is guaranteed to arrive. See
+ * `commit`'s coverage note in `controller.ts`.
+ */
+ | {
+    type: 'repair';
+    missing: number;
+    inMs: number;
+    attempt: number;
+} | {
+    type: 'error';
+    key: string;
+    error: PdfError;
+};
+export type EpochReason = 'initial' | 'coverage' | 'sharpness' | 'look-ahead' | 'stale' | 'layout';
+export type Sampling = 'linear' | 'nearest' | 'cubic';

package/dist/types.js

@@ -0,0 +1,21 @@
+/**
+ * The type contract for @reekon-tools/react-native-pdf-canvas.
+ *
+ * THE ONE RULE: the transform decides WHEN to rasterize, never WHAT to draw.
+ *
+ * Every rect in this file is in DOC SPACE — PDF points, y-down, origin at the
+ * page's top-left. That is exactly what PDFium's CPDF_Page::GetDisplayMatrix()
+ * emits, so a PDFium backend is a pass-through and every other backend adapts
+ * to it. There is deliberately no `coordinateSystem` option: two conventions in
+ * one package is how device pixel ratio gets applied twice.
+ *
+ * Nothing here imports React, react-native, or reanimated. The only external
+ * type is SkImage, and it is type-only.
+ */
+export class PdfError extends Error {
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'PdfError';
+        this.code = code;
+    }
+}