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

package/android/tools/compile-gate.sh

@@ -0,0 +1,289 @@
+#!/bin/bash
+#
+# The Android compile gate: type- and syntax-check every Android source in this
+# package WITHOUT gradle, an emulator, or a device. Runs in seconds.
+#
+# WHY THIS EXISTS. A cold gradle build of a consuming app is ~45 minutes here and
+# does not reliably produce a runnable app, so the practical alternative to this
+# script is "change JNI and find out on an EAS build". Two of the four things it
+# checks cannot be caught any other way short of a device:
+#
+#   * src/reactnative/PdfCanvasModule.java is not compiled by the standalone
+#     build at all. Its own header used to say "nothing in this file has ever
+#     been compiled or run"; this is what changed that.
+#   * A JNI signature that drifts from its Java `native` declaration compiles
+#     clean on BOTH sides and fails only as an UnsatisfiedLinkError at runtime.
+#     Section 5 makes javac derive the expected prototypes and has clang compare
+#     them against the definitions, in both directions.
+#
+# HOW FAR THE C++ HALF GOES. Not a syntax check — it compiles and LINKS the real
+# shared library, in both configurations, with `-Wl,--no-undefined`, against the
+# NDK's own libjnigraphics and the react-android AAR's own libjsi.so. So a missing
+# `target_link_libraries` entry, a platform function that does not exist at the
+# minSdk, or a jsi symbol the app's React Native version does not export all fail
+# HERE. It then checks that the built .so exports every JNI symbol Java expects.
+# What is skipped versus a real build is gradle and cmake orchestration only.
+#
+# WHAT IT IS NOT. It runs no Java, no C++ and no test. Correctness of the
+# rasterizer and of the raster transport is proven by
+# `cd android && ./gradlew connectedDebugAndroidTest` on a device, and nothing
+# here substitutes for that.
+#
+# Usage:  bash android/tools/compile-gate.sh
+#
+# Paths are discovered, with env overrides for a machine that keeps them
+# elsewhere:  ANDROID_SDK_ROOT, ANDROID_NDK_HOME, JAVA_HOME, RN_ROOT.
+
+set -u
+here=$(cd "$(dirname "$0")/.." && pwd)   # <repo>/android
+PKG=$here
+fail=0
+skipped=0
+
+say_skip() { echo "SKIP  $1"; echo "        $2"; skipped=1; }
+
+run() {
+  local name="$1"; shift
+  local out; out=$("$@" 2>&1); local rc=$?
+  out=$(echo "$out" | grep -v "^Note: ")
+  if [ $rc -eq 0 ]; then echo "PASS  $name"
+  else echo "FAIL  $name (exit $rc)"; echo "$out" | head -30; fail=1; fi
+}
+
+# ---------------------------------------------------------------- discovery
+SDK=${ANDROID_SDK_ROOT:-${ANDROID_HOME:-$HOME/AppData/Local/Android/Sdk}}
+[ -d "$SDK" ] || SDK=$HOME/Library/Android/sdk
+[ -d "$SDK" ] || SDK=$HOME/Android/Sdk
+
+# Newest installed NDK, unless one is pinned.
+NDK=${ANDROID_NDK_HOME:-}
+if [ -z "$NDK" ]; then
+  NDK=$(ls -d "$SDK"/ndk/* 2>/dev/null | sort -V | tail -1)
+fi
+CLANG=""
+for host in windows-x86_64 darwin-x86_64 linux-x86_64; do
+  for ext in ".exe" ""; do
+    c="$NDK/toolchains/llvm/prebuilt/$host/bin/clang++$ext"
+    [ -x "$c" ] && CLANG="$c" && break 2
+  done
+done
+
+# Newest platform android.jar. -bootclasspath needs a Windows-style path on
+# Windows because javac is a native binary; `cygpath -m` is a no-op elsewhere.
+winpath() { if command -v cygpath >/dev/null 2>&1; then cygpath -m "$1"; else echo "$1"; fi; }
+AJAR=$(ls -d "$SDK"/platforms/android-*/android.jar 2>/dev/null | sort -V | tail -1)
+[ -n "$AJAR" ] && AJAR=$(winpath "$AJAR")
+
+# javac 17: the module targets VERSION_17. A JDK 8 javac cannot compile it.
+JAVAC=""
+for cand in "${JAVA_HOME:-}/bin/javac" \
+            "/c/Program Files/Android/Android Studio/jbr/bin/javac.exe" \
+            "$(command -v javac 2>/dev/null)"; do
+  [ -n "$cand" ] && [ -x "$cand" ] || continue
+  v=$("$cand" -version 2>&1 | sed 's/javac //;s/\..*//')
+  [ "${v:-0}" -ge 11 ] 2>/dev/null && JAVAC="$cand" && break
+done
+
+# jsi/jsi.h and the react-android classes.jar come from a consuming app's
+# node_modules. RN_ROOT can point straight at one.
+RN=${RN_ROOT:-}
+if [ -z "$RN" ]; then
+  for cand in "$here/../node_modules/react-native" \
+              "$here/../../BOLDR/node_modules/react-native" \
+              "$here/../example/node_modules/react-native"; do
+    [ -f "$cand/ReactCommon/jsi/jsi/jsi.h" ] && RN=$(cd "$cand" && pwd) && break
+  done
+fi
+JSI="$RN/ReactCommon/jsi"
+
+OUT=${TMPDIR:-/tmp}/pdfcanvas-gate
+rm -rf "$OUT"; mkdir -p "$OUT"/{standalone,autolinked,androidtest,h,classes,rn}
+
+# react-android's classes.jar is inside an AAR in the gradle cache. Needed only
+# for section 3.
+# Extracted WHOLE rather than with a `jni/*` member filter: MSYS unzip extracts
+# nothing for that pattern, which silently loses libjsi.so and turns the
+# WITH_JSI link into a skip. The AAR is a couple of megabytes; just unpack it.
+RNJAR=""
+aar=$(ls -t "$HOME"/.gradle/caches/modules-2/files-2.1/com.facebook.react/react-android/*/*/*-release.aar 2>/dev/null | head -1)
+[ -z "$aar" ] && aar=$(ls -t "$HOME"/.gradle/caches/modules-2/files-2.1/com.facebook.react/react-android/*/*/*-debug.aar 2>/dev/null | head -1)
+if [ -n "$aar" ] && command -v unzip >/dev/null 2>&1; then
+  (cd "$OUT/rn" && unzip -o -q "$aar")
+  [ -f "$OUT/rn/classes.jar" ] && RNJAR=$(winpath "$OUT/rn/classes.jar")
+fi
+
+NM=""
+for host in windows-x86_64 darwin-x86_64 linux-x86_64; do
+  for ext in ".exe" ""; do
+    c="$NDK/toolchains/llvm/prebuilt/$host/bin/llvm-nm$ext"
+    [ -x "$c" ] && NM="$c" && break 2
+  done
+done
+
+# libjsi.so ships inside the same AAR, one copy per ABI, already unpacked above.
+JSILIB=""
+[ -f "$OUT/rn/jni/arm64-v8a/libjsi.so" ] && JSILIB="$OUT/rn/jni"
+
+echo "SDK   $SDK"
+echo "NDK   ${NDK:-<none>}"
+echo "javac ${JAVAC:-<none>}"
+echo "RN    ${RN:-<none>}"
+echo
+
+# ---------------------------------------------------------------- 1. C++
+# Both #if configurations, both pointer widths. 32-bit is not redundant: it is
+# what catches a size_t/jsize/uint64 width slip that arm64 hides.
+abi_dir() { case "$1" in aarch64*) echo arm64-v8a;; armv7a*) echo armeabi-v7a;; esac; }
+
+if [ -n "$CLANG" ]; then
+  for abi in aarch64-linux-android24 armv7a-linux-androideabi24; do
+    # --no-undefined is the point of linking rather than syntax-checking: it
+    # fails on any symbol the platform will not supply at runtime, which is
+    # exactly the class of mistake a -fsyntax-only pass waves through and a
+    # device then reports as a dlopen failure and a silent base64 fallback.
+    run "cpp+link standalone    $abi" "$CLANG" --target=$abi -std=c++17 -O2 \
+        -Wall -Wextra -Werror -shared -fPIC -o "$OUT/lib-$abi.so" \
+        "$PKG/src/jsi/cpp/pdfcanvas-jsi.cpp" -ljnigraphics -Wl,--no-undefined
+
+    if [ -f "$JSI/jsi/jsi.h" ] && [ -n "$JSILIB" ] && [ -d "$JSILIB/$(abi_dir "$abi")" ]; then
+      run "cpp+link WITH_JSI      $abi" "$CLANG" --target=$abi -std=c++17 -O2 \
+          -Wall -Wextra -Werror -frtti -fexceptions -shared -fPIC \
+          -DPDFCANVAS_WITH_JSI=1 -I"$JSI" -o "$OUT/lib-jsi-$abi.so" \
+          "$PKG/src/jsi/cpp/pdfcanvas-jsi.cpp" -ljnigraphics \
+          -L"$JSILIB/$(abi_dir "$abi")" -ljsi -Wl,--no-undefined
+    elif [ ! -f "$JSI/jsi/jsi.h" ]; then
+      say_skip "cpp+link WITH_JSI      $abi" \
+        "no jsi/jsi.h; set RN_ROOT to a react-native install"
+    else
+      say_skip "cpp+link WITH_JSI      $abi" \
+        "no libjsi.so for this ABI in the react-android AAR"
+    fi
+  done
+
+  # The gate links with an explicit -l list, so it would keep passing if the
+  # equivalent line were dropped from CMakeLists.txt — the real build would then
+  # fail, loudly, but only on a machine running gradle. Assert the two agree.
+  cml="$PKG/src/jsi/cpp/CMakeLists.txt"
+  missing_link=""
+  for lib in jnigraphics; do
+    grep -q "target_link_libraries.*[ (]$lib[ )]" "$cml" || missing_link="$missing_link $lib"
+  done
+  if [ -z "$missing_link" ]; then
+    echo "PASS  CMakeLists links what this gate links"
+  else
+    echo "FAIL  this gate links$missing_link but CMakeLists.txt does not"
+    fail=1
+  fi
+
+  # The built library must actually EXPORT what Java will look up. A visibility
+  # flag or a namespace slip hides a symbol without failing any compile.
+  if [ -n "$NM" ] && [ -f "$OUT/lib-aarch64-linux-android24.so" ]; then
+    exported=$("$NM" -D --defined-only "$OUT/lib-aarch64-linux-android24.so" 2>/dev/null \
+      | grep -c 'Java_tools_reekon_pdfcanvas')
+    if [ "${exported:-0}" -ge 7 ]; then
+      echo "PASS  the linked .so exports $exported Java_tools_reekon_* symbols"
+    else
+      echo "FAIL  the linked .so exports only ${exported:-0} JNI symbols (expected >= 7)"
+      fail=1
+    fi
+  else
+    say_skip "exported JNI symbols" "no llvm-nm, or nothing linked"
+  fi
+else
+  say_skip "cpp (all)" "no NDK clang++ found; set ANDROID_NDK_HOME"
+fi
+
+# ---------------------------------------------------------------- 2/3/4. Java
+if [ -n "$JAVAC" ] && [ -n "$AJAR" ]; then
+  # Standalone build: main + jsi, no React anywhere, against the strict Android
+  # API surface. -Werror here because this half is meant to stay clean.
+  run "javac standalone (main+jsi)" \
+    "$JAVAC" -proc:none -nowarn -Werror -d "$OUT/standalone" -bootclasspath "$AJAR" \
+    -source 8 -target 8 \
+    "$PKG"/src/main/java/tools/reekon/pdfcanvas/*.java \
+    "$PKG"/src/jsi/java/tools/reekon/pdfcanvas/jsi/*.java
+
+  # Autolinked build: adds src/reactnative. Its lambdas need a real java.base,
+  # so android.jar moves from -bootclasspath to -cp.
+  if [ -n "$RNJAR" ]; then
+    run "javac autolinked (+reactnative)" \
+      "$JAVAC" -proc:none -nowarn -d "$OUT/autolinked" -cp "$AJAR;$RNJAR" \
+      "$PKG"/src/main/java/tools/reekon/pdfcanvas/*.java \
+      "$PKG"/src/jsi/java/tools/reekon/pdfcanvas/jsi/*.java \
+      "$PKG"/src/reactnative/java/tools/reekon/pdfcanvas/rn/*.java
+  else
+    say_skip "javac autolinked (+reactnative)" \
+      "no react-android AAR in the gradle cache; build a consuming app once to populate it"
+  fi
+
+  # The instrumented suite, against the standalone classes it tests. Compiling
+  # it is how a change to the rasterizer's API is caught before a device run.
+  TESTCP=""
+  for a in androidx.test/core androidx.test/monitor androidx.test/runner androidx.test.ext/junit; do
+    aa=$(ls -t "$HOME"/.gradle/caches/modules-2/files-2.1/$a/*/*/*.aar 2>/dev/null | head -1)
+    [ -z "$aa" ] && continue
+    d="$OUT/$(basename "$a")"; mkdir -p "$d"
+    (cd "$d" && unzip -o -q "$aa" classes.jar) && TESTCP="$TESTCP;$(winpath "$d/classes.jar")"
+  done
+  for j in junit/junit org.hamcrest/hamcrest-core; do
+    jj=$(ls -t "$HOME"/.gradle/caches/modules-2/files-2.1/$j/*/*/*.jar 2>/dev/null | grep -v sources | head -1)
+    [ -n "$jj" ] && TESTCP="$TESTCP;$(winpath "$jj")"
+  done
+  if [ -n "$TESTCP" ]; then
+    run "javac androidTest suite" \
+      "$JAVAC" -proc:none -nowarn -d "$OUT/androidtest" \
+      -cp "$AJAR$TESTCP;$(winpath "$OUT/standalone")" \
+      "$PKG"/src/androidTest/java/tools/reekon/pdfcanvas/*.java
+  else
+    say_skip "javac androidTest suite" "no androidx.test jars in the gradle cache"
+  fi
+else
+  say_skip "javac (all)" "need a JDK 11+ javac and an SDK platform android.jar"
+fi
+
+# ---------------------------------------------------------------- 5. JNI
+# THE SECTION THAT EARNS THIS SCRIPT. javac -h derives the expected C prototypes
+# from the Java `native` declarations; force-including that header makes clang
+# compare every definition against its declaration, so a drifted parameter list
+# or return type is a compile error instead of an UnsatisfiedLinkError on a
+# device. The loop then checks the reverse: a method declared `native` in Java
+# with no C++ definition compiles clean everywhere and fails only at runtime.
+if [ -n "$JAVAC" ] && [ -n "$AJAR" ] && [ -n "$CLANG" ] && [ -f "$JSI/jsi/jsi.h" ]; then
+  if "$JAVAC" -proc:none -nowarn -d "$OUT/classes" -h "$OUT/h" -bootclasspath "$AJAR" \
+       -source 8 -target 8 \
+       "$PKG"/src/main/java/tools/reekon/pdfcanvas/*.java \
+       "$PKG"/src/jsi/java/tools/reekon/pdfcanvas/jsi/*.java >/dev/null 2>&1; then
+    for abi in aarch64-linux-android24 armv7a-linux-androideabi24; do
+      # -fsyntax-only here on purpose: this pass exists to compare declarations,
+      # and the link is already covered by section 1.
+      run "jni prototypes match   $abi" "$CLANG" --target=$abi -std=c++17 -fsyntax-only \
+          -Wall -Wextra -Werror -frtti -fexceptions -DPDFCANVAS_WITH_JSI=1 -I"$JSI" \
+          -I"$OUT/h" -include tools_reekon_pdfcanvas_jsi_PdfCanvasPixelBridge.h \
+          "$PKG/src/jsi/cpp/pdfcanvas-jsi.cpp"
+    done
+    declared=$(grep -o 'Java_[A-Za-z0-9_]*' "$OUT"/h/*.h | sed 's/.*://' | sort -u)
+    n=0; missing=""
+    for m in $declared; do
+      n=$((n + 1))
+      grep -q "^${m}($" "$PKG/src/jsi/cpp/pdfcanvas-jsi.cpp" || missing="$missing $m"
+    done
+    # A floor, because an extraction that silently finds nothing would make this
+    # check pass forever while testing nothing.
+    if [ "$n" -lt 7 ]; then
+      echo "FAIL  the JNI gate found only $n declared native methods (expected >= 7)"; fail=1
+    elif [ -n "$missing" ]; then
+      echo "FAIL  declared native in Java, undefined in C++:$missing"; fail=1
+    else
+      echo "PASS  all $n declared native methods are defined"
+    fi
+  else
+    echo "FAIL  could not generate JNI headers"; fail=1
+  fi
+else
+  say_skip "jni signature gate" "needs javac, android.jar, NDK clang++ and jsi/jsi.h together"
+fi
+
+echo "---"
+if [ $fail -ne 0 ]; then echo "GATE: FAILURES"; exit 1; fi
+if [ $skipped -ne 0 ]; then echo "GATE: PASS (with skips — see SKIP lines)"; exit 0; fi
+echo "GATE: ALL PASS"

package/dist/cache.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Refcounted, byte-budgeted raster cache.
+ *
+ * Two things make this different from a plain LRU:
+ *
+ * 1. REFCOUNTS, NOT LIVENESS GUESSES. A raster is drawable exactly while some
+ *    PdfContent slot references it. `acquire`/`release` count those slots, so a
+ *    raster held by both the live detail set and the retiring set has refs 2 and
+ *    survives until both are gone. Nothing referenced is ever evicted.
+ *
+ * 2. THE RETIRE QUEUE. A refcount reaching zero does NOT dispose. The entry goes
+ *    to a queue that the controller flushes at a point that already causes a
+ *    React commit, because freeing an SkImage that is still in a mounted Skia
+ *    node draws a corpse. Retirement must never own a timer or a commit of its
+ *    own — see `flushRetired`.
+ *
+ * 3. THE DISPOSAL FENCE, which is what makes point 2 actually true.
+ *
+ *    MEASURED: releasing and flushing in the SAME turn — which is what the
+ *    controller's commit did — is a delay of zero. The entry left `content` and
+ *    was freed before React had even been notified, let alone re-rendered, so
+ *    every Skia node still holding it was holding a deleted object. In a browser
+ *    that is `BindingError: Cannot pass deleted object as a pointer of type
+ *    Image const*`, thrown out of RN Skia's own `drawImage -> Image.width` while
+ *    it RE-RECORDS the picture from the mounted tree: 16 occurrences over six
+ *    high-zoom pans, 3-4 ms after an epoch commit, every time.
+ *
+ *    So the queue is fenced, and the fence is a CLOCK the cache is told about
+ *    rather than one it assumes:
+ *
+ *      release(key, contentEpoch)  tags the entry with the epoch of the content
+ *                                  object that stopped referencing it.
+ *      flushRetired(contentEpoch)  frees only entries tagged STRICTLY OLDER than
+ *                                  `contentEpoch` — i.e. one whole epoch of
+ *                                  grace, which is the commit clock and is a
+ *                                  heuristic: it assumes the renderer mounted
+ *                                  epoch N before the controller published N+1.
+ *      notePresented(epoch)        the SOUND clock, IF a caller can honestly
+ *                                  supply one: everything tagged `epoch` or older
+ *                                  is treated as provably unreferenced and freed
+ *                                  at once — sooner than the commit clock would.
+ *
+ *    "PRESENTED" MEANS DRAWN, NOT MOUNTED, AND THE DIFFERENCE IS MEASURED. Wiring
+ *    this to React — a `PdfContentView` prop reporting `content.epoch` from a
+ *    PASSIVE effect, which is the latest signal a component can produce —
+ *    REINTRODUCES the corpse it exists to prevent. Controlled A/B in rock-desktop's
+ *    probe, 14 high-zoom pans per arm, twice each:
+ *
+ *      onPresented wired    2, 2  `BindingError: ... Image const*`
+ *      commit clock only    0, 0
+ *
+ *    The reason is that the images are held by the RECORDED PICTURE, not by the
+ *    React tree. RN Skia re-records on its own rAF, so after React has committed
+ *    epoch N there is still a picture in hand that references epoch N-1's images,
+ *    and `play()` -> `drawImage` -> `Image.width` reads one that has just been
+ *    freed. Every stack in that A/B was exactly that. A commit is therefore NOT a
+ *    presentation, and no React-reachable signal on web is late enough to be one.
+ *
+ *    So this is NOT wired, deliberately, and must not be wired from an effect. It
+ *    stays for a caller driving `createPdfController` against a renderer that has
+ *    a genuine post-paint callback. Absent that, the commit clock is the correct
+ *    answer and its only cost is holding one epoch's dropped rasters while the
+ *    viewport is at rest.
+ *
+ *    An UNTAGGED release (no epoch) means "nothing of mine is mounted any more",
+ *    and so does a `flushRetired()` with no epoch: both are the teardown path,
+ *    where immediate disposal is the correct answer and the original behaviour.
+ *
+ * The budget is a SOFT cap. Running out never throws and never blanks a page:
+ * the last resort is to refuse the newcomer and keep drawing the base we already
+ * have. Degrade, never crash.
+ */
+import type { PdfRaster } from './types.js';
+/** Mirrors the `reason` field of the `evict` diagnostic in types.ts. */
+export type EvictionReason = 'budget' | 'page-window' | 'epoch';
+export interface RasterCacheOptions {
+    /** Soft cap on cached bytes. A single raster larger than this is refused outright. */
+    budgetBytes: number;
+    /**
+     * Frees the backing SkImage. Called at most once per raster: on web,
+     * double-dispose THROWS where native tolerates it.
+     */
+    dispose: (raster: PdfRaster) => void;
+    /**
+     * How many pages either side of the live window keep their whole-page base.
+     * Bases inside this radius are the anti-blank mechanism and are evicted last;
+     * a base for page 300 while you read page 4 is just garbage.
+     */
+    baseRetentionRadius?: number;
+}
+export interface RasterCacheStats {
+    bytes: number;
+    entries: number;
+    /** Entries sitting in the retire queue, awaiting the next flush. */
+    retired: number;
+    /** Entries with at least one live reference. */
+    referenced: number;
+}
+export interface RasterCache {
+    /** Returns the cached raster and marks it recently used. */
+    get(key: string): PdfRaster | undefined;
+    has(key: string): boolean;
+    /**
+     * Inserts a raster, evicting as needed to stay under budget.
+     *
+     * TAKES OWNERSHIP. On `false` the raster has ALREADY been disposed and must
+     * not be drawn — the caller keeps drawing whatever it had.
+     *
+     * On `true` the caller must read the cache's copy back with `acquire`/`get`
+     * rather than reusing its own reference: an entry with this key may already
+     * have existed, in which case the incumbent stands and the newcomer is freed.
+     */
+    put(raster: PdfRaster): boolean;
+    /** Takes a reference. Un-retires the entry if it was queued for disposal. */
+    acquire(key: string): PdfRaster | undefined;
+    /**
+     * Drops a reference. At zero the entry joins the retire queue, NOT dispose.
+     *
+     * `contentEpoch` is the epoch of the content object that has just STOPPED
+     * referencing this raster — i.e. the epoch being published by the commit doing
+     * the releasing. It is what the disposal fence is measured against, so passing
+     * it is how a caller says "a renderer may still be holding this". Omit it only
+     * when nothing of yours is mounted at all (teardown), which is what the
+     * original unfenced behaviour was.
+     */
+    release(key: string, contentEpoch?: number): void;
+    refCount(key: string): number;
+    /**
+     * Disposes retired entries the renderer can no longer be holding.
+     *
+     * Pass the epoch of the content object you have just published: entries tagged
+     * with an OLDER epoch go, entries tagged with this one wait for the next commit
+     * (or for `notePresented`, which frees them as soon as it is provable). Call it
+     * only from a path that is already producing a React commit — retirement owns
+     * no timer and no commit of its own.
+     *
+     * With NO epoch it frees every retired entry outright. That is the teardown
+     * call: nothing of this cache's is mounted, so there is nothing to fence
+     * against.
+     */
+    flushRetired(contentEpoch?: number): void;
+    /**
+     * The renderer has mounted content epoch `epoch` — so every raster the content
+     * objects up to and including it stopped referencing is provably unreferenced,
+     * whatever the commit clock would have guessed, and is freed now.
+     *
+     * OPTIONAL, and the first call ARMS it: until a renderer reports, the fence
+     * falls back to the commit clock (see `flushRetired`). A host that reports once
+     * and then stops holds retired bytes until the budget evicts them or the cache
+     * is cleared, which is the correct failure — late is safe, early draws a corpse.
+     */
+    notePresented?(epoch: number): void;
+    /** The pages currently on screen. Drives both eviction categories below. */
+    setLiveWindow(pages: readonly number[]): void;
+    /** Disposes every entry, referenced or not. Teardown only. */
+    clear(): void;
+    stats(): RasterCacheStats;
+    /** Optional so a hand-written fake cache need not implement it. */
+    subscribeEvictions?(listener: (raster: PdfRaster, reason: EvictionReason) => void): () => void;
+}
+export declare function createRasterCache(options: RasterCacheOptions): RasterCache;