@reekon-tools/react-native-pdf-canvas 0.1.1 → 0.2.1

package/native/.clangd

@@ -0,0 +1,5 @@
+# Points clangd at the host build's compile_commands.json so the editor sees the
+# same include paths and -std the real build uses. Generated by
+# `cmake -S native -B native/build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`.
+CompileFlags:
+  CompilationDatabase: build

package/native/CMakeLists.txt

@@ -0,0 +1,89 @@
+# THE LAPTOP PROOF OF THE C++ CORE.
+#
+# Builds `native/core` against the pinned PDFium release for whatever machine
+# this is — Windows, macOS or Linux — and runs `native/tests` against it. No
+# device, no emulator, no simulator, no React Native, no Xcode, no Gradle: the
+# same sources the Android library and the CocoaPods build compile, proven here
+# with real PDFium in a few seconds. It replaces the Swift suite (`swift test`)
+# and the instrumented Android suite as the place rendering is proven, because
+# both platforms now share this one engine.
+#
+#   yarn pdfium:fetch host                 # once; downloads + verifies PDFium
+#   cmake -S native -B native/build -G Ninja
+#   cmake --build native/build
+#   ctest --test-dir native/build --output-on-failure
+#
+# (`yarn native:test` does all four.) On Windows use the MinGW g++ or an LLVM
+# clang that targets the GNU ABI — PDFium's DLL exports a plain C surface, so
+# any toolchain that can link a DLL works.
+
+cmake_minimum_required(VERSION 3.20)
+project(pdfcanvas_native CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+# Where `scripts/fetch-pdfium.mjs host` put the release. Overridable so a
+# vendored copy can be pointed at.
+set(PDFCANVAS_PDFIUM_DIR "${CMAKE_CURRENT_SOURCE_DIR}/.pdfium/host"
+    CACHE PATH "Extracted pdfium-<host>.tgz (include/, lib/, bin/)")
+if(NOT EXISTS "${PDFCANVAS_PDFIUM_DIR}/include/fpdfview.h")
+  message(FATAL_ERROR
+    "No PDFium at ${PDFCANVAS_PDFIUM_DIR}. Run `node scripts/fetch-pdfium.mjs host` "
+    "from the package root first (or set PDFCANVAS_PDFIUM_DIR).")
+endif()
+
+# ---------------------------------------------------------------- PDFium
+add_library(pdfium SHARED IMPORTED)
+if(WIN32)
+  set_target_properties(pdfium PROPERTIES
+    IMPORTED_LOCATION "${PDFCANVAS_PDFIUM_DIR}/bin/pdfium.dll"
+    IMPORTED_IMPLIB   "${PDFCANVAS_PDFIUM_DIR}/lib/pdfium.dll.lib")
+elseif(APPLE)
+  set_target_properties(pdfium PROPERTIES
+    IMPORTED_LOCATION "${PDFCANVAS_PDFIUM_DIR}/lib/libpdfium.dylib")
+else()
+  set_target_properties(pdfium PROPERTIES
+    IMPORTED_LOCATION "${PDFCANVAS_PDFIUM_DIR}/lib/libpdfium.so")
+endif()
+target_include_directories(pdfium INTERFACE "${PDFCANVAS_PDFIUM_DIR}/include")
+
+# ---------------------------------------------------------------- core
+include(core/pdfcanvas-core.cmake)
+add_library(pdfcanvas_core STATIC ${PDFCANVAS_CORE_SOURCES})
+target_include_directories(pdfcanvas_core PUBLIC "${PDFCANVAS_CORE_INCLUDE_DIR}")
+target_link_libraries(pdfcanvas_core PUBLIC pdfium)
+target_compile_options(pdfcanvas_core PRIVATE
+  $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-Wall -Wextra -Werror>)
+
+# ---------------------------------------------------------------- tests
+file(GLOB PDFCANVAS_TEST_SOURCES CONFIGURE_DEPENDS "tests/*.cpp")
+add_executable(pdfcanvas_tests ${PDFCANVAS_TEST_SOURCES})
+target_link_libraries(pdfcanvas_tests PRIVATE pdfcanvas_core)
+target_compile_options(pdfcanvas_tests PRIVATE
+  $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-Wall -Wextra -Werror>)
+if(WIN32)
+  # The DLL has to sit next to the executable; there is no rpath on Windows.
+  add_custom_command(TARGET pdfcanvas_tests POST_BUILD
+    COMMAND ${CMAKE_COMMAND} -E copy_if_different
+      "${PDFCANVAS_PDFIUM_DIR}/bin/pdfium.dll" "$<TARGET_FILE_DIR:pdfcanvas_tests>")
+  if(MINGW)
+    # Static C++ runtime, so the test binary runs from ctest without the MinGW
+    # bin directory on PATH (a missing libstdc++-6.dll exits silently with
+    # 0xC0000135 and no output — which reads as "the suite printed nothing").
+    target_link_options(pdfcanvas_tests PRIVATE -static-libstdc++ -static-libgcc -static)
+  endif()
+elseif(APPLE)
+  set_target_properties(pdfcanvas_tests PROPERTIES
+    BUILD_RPATH "${PDFCANVAS_PDFIUM_DIR}/lib")
+else()
+  set_target_properties(pdfcanvas_tests PROPERTIES
+    BUILD_RPATH "${PDFCANVAS_PDFIUM_DIR}/lib")
+endif()
+
+enable_testing()
+add_test(NAME pdfcanvas_tests COMMAND pdfcanvas_tests)

package/native/core/include/pdfcanvas/document.h

@@ -0,0 +1,90 @@
+// One open PDF, rendered by PDFium.
+//
+// THE SAME ENGINE ON EVERY PLATFORM. Android's `PdfRenderer` was PDFium behind
+// a Java wrapper that exposed no annotation switch, no cancel, no password and
+// a process-wide lock that convoyed; iOS was CoreGraphics, which antialiases a
+// 0.25pt CAD line at fit zoom into 10% grey where PDFium clamps every stroke to
+// a device pixel. This class replaces both with the engine the web backend
+// already used, so a tile is byte-identical across all three platforms rather
+// than merely similar, and `annotations` means the same thing everywhere.
+//
+// THREADING. PDFium is not thread-safe — not across documents, not across
+// threads, not at all — so every entry point below takes the process-wide
+// library lock. That is not a regression on either platform: Android declared
+// one render lane because AOSP's lock convoyed, and iOS declared one because a
+// second was never measured to help. Cancellation is what makes one lane
+// cheap: a superseded tile stops MID-RENDER (see `Cancellation`), so a stale
+// render never holds the lock for longer than one progressive pause.
+#pragma once
+
+#include <memory>
+#include <vector>
+
+#include "pdfcanvas/error.h"
+#include "pdfcanvas/pixels.h"
+#include "pdfcanvas/types.h"
+
+namespace pdfcanvas {
+
+class Document {
+ public:
+  /// Refuse absurd rasters instead of dying on an allocation failure. 64 Mpx
+  /// is 256 MB at 4 bytes per pixel — past what a device hands out in one
+  /// allocation — so anything above it is a planner bug, and a named error
+  /// against a raster key beats a jetsam kill with no key attached. The TS
+  /// policy has its own, much lower, ceilings (`maxRasterPixels`).
+  static constexpr long long kMaxRasterPixels = 64'000'000;
+
+  /// How many parsed pages one document keeps. An epoch is several tiles of
+  /// the same page, and a continuous layout keeps two or three pages live, so
+  /// alternating between them must not re-parse a dense drawing every tile.
+  static constexpr int kPageCacheCapacity = 3;
+
+  /// Opens a document. Throws `PdfError` with `not-found` (no such file, or
+  /// unreadable), `corrupt` (empty, not a PDF, unparseable page tree),
+  /// `password-required` / `password-incorrect` (decided by whether the caller
+  /// supplied one — PDFium reports the same code for both), `unsupported` (an
+  /// encryption scheme this build cannot handle) or `backend-failure`.
+  static std::unique_ptr<Document> open(const Source& source);
+
+  ~Document();
+  Document(const Document&) = delete;
+  Document& operator=(const Document&) = delete;
+
+  int pageCount() const noexcept { return static_cast<int>(pages_.size()); }
+
+  /// Every page's geometry, measured once at open from the page dictionary —
+  /// no content stream is parsed, so this is proportional to the page tree and
+  /// not to what is drawn on it, which is what keeps `pageGeometry` cheap.
+  const std::vector<PageGeometry>& pages() const noexcept { return pages_; }
+
+  /// Throws `not-found` for an index the document does not have.
+  const PageGeometry& geometry(int index) const;
+
+  /// Renders one raster.
+  ///
+  /// `signal` may be null. It is observed before the lock, after it, before
+  /// the draw, DURING the draw (PDFium's progressive API pauses and asks), and
+  /// after it — the last one only stops a superseded raster being handed back.
+  ///
+  /// `sink` may be null, which means the heap. A non-null sink may REFUSE its
+  /// reservation, in which case the render falls through to the heap and the
+  /// result is heap-backed — check `RasterPixels::inSlot()` rather than
+  /// assuming. A cancellation observed after the draw abandons the sink itself.
+  RasterPixels render(const RasterRequest& request, Cancellation* signal,
+                      PixelSink* sink);
+
+  /// Releases every PDFium object. Blocks until an in-flight render on this
+  /// document finishes (it holds the library lock), and is therefore free of
+  /// the use-after-free window the Android pool's close had. Idempotent.
+  void close();
+  bool isClosed() const noexcept;
+
+ private:
+  struct Impl;
+  explicit Document(std::unique_ptr<Impl> impl);
+  std::unique_ptr<Impl> impl_;
+  std::vector<PageGeometry> pages_;
+};
+
+}  // namespace pdfcanvas

package/native/core/include/pdfcanvas/error.h

@@ -0,0 +1,47 @@
+// The eight failure kinds, mirroring `PdfErrorCode` in `src/types.ts`.
+//
+// THE WIRE STRINGS ARE THE TYPESCRIPT UNION MEMBERS VERBATIM. Both bindings
+// reject a promise with `wireName(code)` and `native-bridge.ts` reconstructs a
+// `PdfError` from it with no translation table in between. There used to be
+// three copies of this list (Java, Objective-C, TypeScript); there are now two,
+// and this is the native one.
+#pragma once
+
+#include <exception>
+#include <string>
+
+namespace pdfcanvas {
+
+enum class ErrorCode {
+  NotFound,
+  PasswordRequired,
+  PasswordIncorrect,
+  Corrupt,
+  Unsupported,
+  Cancelled,
+  OutOfMemory,
+  BackendFailure,
+};
+
+/// The TypeScript union member for a code. Never null.
+const char* wireName(ErrorCode code);
+
+/// The one exception type the core throws. Bindings catch it at the JNI /
+/// Objective-C boundary and turn it into a promise rejection; nothing else may
+/// escape the core, because a C++ exception unwinding into ART or ARC is a
+/// process abort rather than an error anyone can read.
+class PdfError : public std::exception {
+ public:
+  PdfError(ErrorCode code, std::string message)
+      : code_(code), message_(std::move(message)) {}
+
+  ErrorCode code() const noexcept { return code_; }
+  const char* what() const noexcept override { return message_.c_str(); }
+  const std::string& message() const noexcept { return message_; }
+
+ private:
+  ErrorCode code_;
+  std::string message_;
+};
+
+}  // namespace pdfcanvas

package/native/core/include/pdfcanvas/jsi.h

@@ -0,0 +1,18 @@
+// The one JSI touch point: installing `globalThis.__pdfCanvasTakePixels`.
+#pragma once
+
+namespace pdfcanvas {
+
+/// Installs the host function into a `facebook::jsi::Runtime`.
+///
+/// MUST be called on the JS thread with a live runtime pointer. Returns false —
+/// never throws — when the pointer is null, when this build has no JSI
+/// (`PDFCANVAS_HAS_JSI == 0`), or when the runtime refuses the host function.
+/// The JS side then falls back to base64: rendering correctly is worth more
+/// than rendering fast.
+///
+/// Takes `void*` so the declaration is includable from plain C++, Objective-C++
+/// and JNI code alike without dragging `<jsi/jsi.h>` into every consumer.
+bool installTakePixels(void* runtimePointer);
+
+}  // namespace pdfcanvas

package/native/core/include/pdfcanvas/jsi_config.h

@@ -0,0 +1,30 @@
+// Whether this translation unit is being built where `<jsi/jsi.h>` exists.
+//
+// TWO BUILDS, ONE CORE, decided here and nowhere else:
+//
+//   PDFCANVAS_HAS_JSI == 1   the autolinked Android library (ReactAndroid's
+//                            prefab publishes jsi/jsi.h and libjsi.so) and the
+//                            CocoaPods build (React-jsi is a dependency). The
+//                            slot buffer IS a `jsi::MutableBuffer` and
+//                            `installTakePixels` puts the host function on the
+//                            JS global.
+//   PDFCANVAS_HAS_JSI == 0   the host test suite and the standalone Android
+//                            library. No React Native anywhere; the storage
+//                            compiles against a restated interface and
+//                            `installTakePixels` honestly reports false.
+//
+// Every TU in one target must agree, which they do: the include path is a
+// property of the target, and the explicit define is passed target-wide.
+#pragma once
+
+#if defined(PDFCANVAS_WITH_JSI)
+#define PDFCANVAS_HAS_JSI 1
+#elif defined(__has_include)
+#if __has_include(<jsi/jsi.h>)
+#define PDFCANVAS_HAS_JSI 1
+#else
+#define PDFCANVAS_HAS_JSI 0
+#endif
+#else
+#define PDFCANVAS_HAS_JSI 0
+#endif

package/native/core/include/pdfcanvas/library.h

@@ -0,0 +1,28 @@
+// PDFium's process-wide state: one initialisation, one lock.
+#pragma once
+
+#include <mutex>
+
+namespace pdfcanvas {
+
+class Library {
+ public:
+  /// The lock every PDFium call is made under. PDFium keeps global state
+  /// (`CPDF_ModuleMgr`, the font cache, the AGG rasterizer's scratch buffers)
+  /// and is documented not thread-safe across documents or threads, so the
+  /// only correct shape is one mutex around the whole library. Held for the
+  /// duration of a render — which is why the render polls for cancellation
+  /// while it holds it.
+  static std::mutex& mutex();
+
+  /// Initialises PDFium exactly once. Callers hold `mutex()` when they call
+  /// this; it is cheap after the first time.
+  static void ensureInitialized();
+
+  /// Font directories handed to `FPDF_InitLibraryWithConfig`. Platform-specific
+  /// and null-terminated; may be ignored by platforms whose font mapper does
+  /// its own scanning (Android's does — `/system/fonts` is built in).
+  static const char** userFontPaths();
+};
+
+}  // namespace pdfcanvas

package/native/core/include/pdfcanvas/pixels.h

@@ -0,0 +1,92 @@
+// Where a raster's bytes go, and what comes back.
+//
+// THE SINK IS WHY THE TRANSPORT COSTS ZERO COPIES ON BOTH PLATFORMS NOW.
+// `FPDFBitmap_CreateEx` takes the destination pointer as an argument, so PDFium
+// writes the tile straight into the buffer that becomes the JS `ArrayBuffer`.
+// The iOS CoreGraphics core had this property; the Android `PdfRenderer` core
+// could not (a `Bitmap` owns its own pixels and had to be copied out), and that
+// asymmetry is gone.
+//
+// RESERVE, FILL, PUBLISH — in that order, and the order is the safety property.
+// A buffer reachable from the process-wide slot map BEFORE it is filled can be
+// freed by `slots::releaseAll()` — which runs on another thread on every Fast
+// Refresh — while PDFium is still writing into it. So a reserved buffer is
+// owned by the sink object alone, on the rendering thread's stack, and becomes
+// reachable only at `publish()`.
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+namespace pdfcanvas {
+
+class PixelSink {
+ public:
+  virtual ~PixelSink() = default;
+
+  /// Reserve `length` bytes, ZEROED, and return them — or nullptr to refuse.
+  /// Called at most once per sink, before anything is drawn. Zeroed is part of
+  /// the contract: it is what makes `Background::Transparent` a fill of zeros
+  /// over zeros, and it is the invariant that stops a published buffer ever
+  /// handing out memory nobody wrote.
+  virtual uint8_t* reserve(size_t length) = 0;
+
+  /// Publish the reserved buffer and return the id a caller redeems it with,
+  /// or 0 for a sink with no id (the heap). Must not fail: every reason a
+  /// publish could be refused is decided at `reserve()`, before the raster
+  /// exists.
+  virtual int64_t publish() = 0;
+
+  /// Drop the buffer, published or not. Idempotent. Called on every path that
+  /// abandons a raster after reserving for it.
+  virtual void abandon() = 0;
+};
+
+/// The default destination: an owned, zero-initialised vector. What every
+/// pixel-reading caller — the host test suite, the base64 fallback — uses.
+class HeapSink final : public PixelSink {
+ public:
+  uint8_t* reserve(size_t length) override;
+  int64_t publish() override { return 0; }
+  void abandon() override { bytes_.clear(); bytes_.shrink_to_fit(); }
+
+  /// Moves the bytes out. Valid once per sink, after `publish()`.
+  std::vector<uint8_t> takeBytes() { return std::move(bytes_); }
+
+ private:
+  std::vector<uint8_t> bytes_;
+  bool reserved_ = false;
+};
+
+/// A finished raster, mirroring `RasterPixels` in `src/types.ts`.
+///
+/// The pixels are in ONE OF TWO PLACES, and `slot` tells you which:
+///   - `slot == 0`: on the heap, in `bytes`.
+///   - `slot != 0`: in the process-wide slot store, waiting to become a JS
+///     `ArrayBuffer` through `__pdfCanvasTakePixels`; `bytes` is empty.
+///
+/// Format is always RGBA8888 with STRAIGHT (un-premultiplied) alpha —
+/// `FPDF_REVERSE_BYTE_ORDER` on a `FPDFBitmap_BGRA` bitmap — which the TS
+/// adapter declares as `format: 'rgba8888', alpha: 'straight'`. Measured in the
+/// web backend: an antialiased opaque-white edge over a transparent page reads
+/// `[255, 255, 255, a]`, not `[a, a, a, a]`.
+struct RasterPixels {
+  int width = 0;
+  int height = 0;
+  /// Always `width * 4` here — this core chooses the stride it hands PDFium —
+  /// and still carried explicitly, because a consumer that assumed it would
+  /// shear the image rather than fail the day it changed.
+  int rowBytes = 0;
+  int64_t slot = 0;
+  std::vector<uint8_t> bytes;
+
+  bool inSlot() const noexcept { return slot != 0; }
+
+  /// One channel of one pixel as 0..255. Heap-backed rasters only.
+  int channel(int x, int y, int c) const {
+    return bytes[static_cast<size_t>(y) * rowBytes + static_cast<size_t>(x) * 4 + c];
+  }
+};
+
+}  // namespace pdfcanvas

package/native/core/include/pdfcanvas/service.h

@@ -0,0 +1,87 @@
+// Everything a React Native binding needs that is not marshalling.
+//
+// Both bindings used to carry their own handle map, their own (handle, token)
+// cancellation registry, their own "read the transport flag once" dance and
+// their own invalidate ordering, in two languages, with the same long comments
+// twice. This class is that logic once, in the language both bindings can call.
+// `PdfCanvasModule.java` and `PdfCanvasModule.mm` are now what their headers
+// always claimed: type conversion, URI resolution, a worker queue, and promises.
+//
+// THREAD-SAFE. Bindings call `open`/`render` from a worker and `cancel`/`close`
+// /`invalidate` from the bridge or JS thread. Rendering itself is serialised by
+// the library lock inside `Document`; this class only guards its own maps, and
+// never holds its mutex across a render.
+#pragma once
+
+#include <cstdint>
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+#include <vector>
+
+#include "pdfcanvas/document.h"
+#include "pdfcanvas/pixels.h"
+#include "pdfcanvas/types.h"
+
+namespace pdfcanvas {
+
+class Service {
+ public:
+  struct Opened {
+    int handle = 0;
+    std::vector<PageGeometry> pages;
+  };
+
+  Service() = default;
+  Service(const Service&) = delete;
+  Service& operator=(const Service&) = delete;
+
+  /// Opens a document and returns its handle plus every page's geometry.
+  /// Throws `PdfError`; after `invalidate()` it throws `backend-failure`.
+  Opened open(const Source& source);
+
+  /// Registers a cancellation signal for (handle, token) BEFORE the render is
+  /// dispatched to a worker. That ordering is what lets `cancel()` be a pure
+  /// lookup: a cancel cannot arrive for a token that was never issued, so a
+  /// missing entry means the render already finished and was cleaned up.
+  void registerCancellation(int handle, int64_t token);
+
+  /// Renders one raster on the calling thread. The (handle, token) signal is
+  /// consumed and unregistered on every path out, success or throw.
+  ///
+  /// `useSlot` asks for the zero-copy transport; the result may still be
+  /// heap-backed if the store refused, so bindings branch on
+  /// `RasterPixels::inSlot()` and not on what they asked for.
+  RasterPixels render(int handle, const RasterRequest& request, int64_t token,
+                      bool useSlot);
+
+  /// Best-effort, and genuinely mid-render: sets the signal a render polls.
+  void cancel(int handle, int64_t token);
+
+  /// Closes one document. Blocks until its in-flight render finishes.
+  void close(int handle);
+
+  /// Closes every document and drains every parked slot. Called from a
+  /// binding's invalidate hook — a reload drops the JS side without ever
+  /// calling `close`, so this is what stops file descriptors and parsed pages
+  /// leaking across dozens of Fast Refreshes a day. Further calls fail with
+  /// `backend-failure` rather than reopening anything.
+  void invalidate();
+
+  bool isInvalidated() const;
+
+  /// Open documents, for diagnostics and tests.
+  size_t openCount() const;
+
+ private:
+  static int64_t signalKey(int handle, int64_t token) noexcept;
+  std::shared_ptr<Document> documentFor(int handle);
+
+  mutable std::mutex mutex_;
+  std::unordered_map<int, std::shared_ptr<Document>> documents_;
+  std::unordered_map<int64_t, std::shared_ptr<Cancellation>> signals_;
+  int nextHandle_ = 1;
+  bool invalidated_ = false;
+};
+
+}  // namespace pdfcanvas

package/native/core/include/pdfcanvas/slots.h

@@ -0,0 +1,113 @@
+// The raster transport's storage: PDFium writes a tile, and JS gets an
+// `ArrayBuffer` over those exact bytes with no base64 and no copy anywhere.
+//
+// ONE STORE FOR BOTH PLATFORMS. `android/src/jsi/cpp/pdfcanvas-jsi.cpp` and
+// `ios/Sources/PdfCanvasSlots/PdfCanvasSlots.mm` used to be two near-identical
+// files with two sets of notes about the same hazards; this is the one that
+// replaced them. The JSI half — installing `__pdfCanvasTakePixels` into a
+// runtime — lives in `jsi.h` and is compiled only where `<jsi/jsi.h>` exists.
+//
+// WHY THE FALLBACK IS BASE64. Neither the legacy bridge nor new-architecture
+// codegen has a binary type (measured: RN's `convertObjCObjectToJSIValue`
+// handles NSString, NSNumber, NSDictionary, NSArray and nothing else, and a
+// `WritableMap` has no bytes either). So a raster crosses as a slot NUMBER that
+// JS redeems once, synchronously, for an `ArrayBuffer` wrapping this memory —
+// or, when the transport could not be negotiated, as a base64 string, which on
+// an LG V60 cost 1005 ms of Hermes decode per 1024x1024 tile.
+//
+// WHO FREES A SLOT. The map drops its reference the instant a take succeeds, so
+// from that moment the only owner is the JS `ArrayBuffer` and the buffer dies
+// when Hermes collects it. A slot that is stored and never taken — a teardown
+// between the promise resolving and its continuation running — is freed by
+// `releaseAll()`, which both bindings call from their invalidate hook.
+#pragma once
+
+#include <array>
+#include <cstddef>
+#include <cstdint>
+#include <memory>
+#include <vector>
+
+#include "pdfcanvas/jsi_config.h"
+#include "pdfcanvas/pixels.h"
+
+#if PDFCANVAS_HAS_JSI
+#include <jsi/jsi.h>
+#endif
+
+namespace pdfcanvas {
+
+#if PDFCANVAS_HAS_JSI
+using SlotBufferBase = facebook::jsi::MutableBuffer;
+#else
+/// The two methods `jsi::MutableBuffer` declares, restated so a build with no
+/// JSI header (the host test suite, the standalone Android library) compiles
+/// the identical storage code. If these ever drift from jsi.h the JSI builds
+/// stop compiling, which is the failure mode worth having.
+struct SlotBufferBase {
+  virtual ~SlotBufferBase() = default;
+  virtual size_t size() const = 0;
+  virtual uint8_t* data() = 0;
+};
+#endif
+
+/// One raster's bytes, owned outright, shaped so Hermes can wrap it.
+///
+/// `std::vector<uint8_t> bytes_(size)` VALUE-initialises, so constructing this
+/// zeroes the raster. That is the sink contract (`PixelSink::reserve`) and not
+/// an accident of the implementation: it is what makes `Background::Transparent`
+/// free and what stops a published buffer ever handing out somebody else's heap.
+class SlotBuffer final : public SlotBufferBase {
+ public:
+  explicit SlotBuffer(size_t size) : bytes_(size) {}
+  size_t size() const override { return bytes_.size(); }
+  uint8_t* data() override { return bytes_.data(); }
+
+ private:
+  std::vector<uint8_t> bytes_;
+};
+
+namespace slots {
+
+/// The self-test payload, mirroring `TRANSPORT_PROBE_BYTES` in
+/// `src/rasterizer/native-bridge.ts`. Restated there rather than derived: the
+/// two lists are the only place the transport's byte fidelity is asserted, and
+/// a mismatch has to make the probe FAIL and the platform fall back to base64.
+const std::array<uint8_t, 8>& probeBytes();
+
+/// Parks the probe bytes in a fresh slot and returns its id.
+int64_t storeProbe();
+
+/// Takes a slot out of the store. nullptr if it is not there. Exactly-once.
+std::shared_ptr<SlotBuffer> take(int64_t slot);
+
+/// Drops one slot if it is still there. Returns whether it was. Idempotent.
+bool release(int64_t slot);
+
+/// Drops every slot. Called from the bindings' invalidate hooks.
+void releaseAll();
+
+/// Slots currently waiting to be taken. For assertions and diagnostics.
+size_t count();
+
+}  // namespace slots
+
+/// A `PixelSink` that reserves store-owned memory and publishes it under a
+/// fresh, process-wide, monotonic id — so a collision at publish is
+/// unrepresentable and `publish()` cannot fail. (The retired Android store had
+/// to REFUSE colliding ids because Java allocated them; allocating next to the
+/// map removes that whole failure class.)
+class SlotSink final : public PixelSink {
+ public:
+  uint8_t* reserve(size_t length) override;
+  int64_t publish() override;
+  void abandon() override;
+
+ private:
+  std::shared_ptr<SlotBuffer> buffer_;
+  int64_t slot_ = 0;
+  bool reserved_ = false;
+  bool published_ = false;
+};
+
+}  // namespace pdfcanvas