react-native-skia-webgpu-video 0.0.0-stage → 0.1.0-beta.1

package/cpp/RNSVHostObject.cpp

@@ -0,0 +1,79 @@
+#include "RNSVHostObject.h"
+
+#include <utility>
+
+namespace RNSkiaVideo {
+
+RNSVHostObject::~RNSVHostObject() {
+  std::lock_guard<std::mutex> lock(cacheMutex);
+  for (auto& entry : caches) {
+    RuntimeLifecycleMonitor::removeListener(*entry.first, this);
+  }
+  caches.clear();
+}
+
+void RNSVHostObject::onRuntimeDestroyed(jsi::Runtime* runtime) {
+  // The runtime is going away: release its values now, while it is still
+  // able to invalidate them.
+  std::lock_guard<std::mutex> lock(cacheMutex);
+  caches.erase(runtime);
+}
+
+RNSVHostObject::RuntimeCache& RNSVHostObject::cacheFor(jsi::Runtime& runtime) {
+  auto entry = caches.find(&runtime);
+  if (entry == caches.end()) {
+    RuntimeLifecycleMonitor::addListener(runtime, shared_from_this());
+    entry = caches.emplace(&runtime, RuntimeCache{}).first;
+  }
+  return entry->second;
+}
+
+jsi::Value RNSVHostObject::getFunction(jsi::Runtime& runtime,
+                                       const std::string& name,
+                                       unsigned int paramCount,
+                                       jsi::HostFunctionType&& function) {
+  std::lock_guard<std::mutex> lock(cacheMutex);
+  auto& cache = cacheFor(runtime);
+  auto entry = cache.values.find(name);
+  if (entry == cache.values.end()) {
+    std::weak_ptr<RNSVHostObject> owner = shared_from_this();
+    auto jsFunction = jsi::Function::createFromHostFunction(
+        runtime, jsi::PropNameID::forAscii(runtime, name), paramCount,
+        [owner, function = std::move(function)](
+            jsi::Runtime& rt, const jsi::Value& self,
+            const jsi::Value* arguments, size_t count) {
+          // The function may have been extracted from its HostObject. Keep
+          // that owner alive through the call without creating a cache cycle.
+          auto retained = owner.lock();
+          if (!retained) throw jsi::JSError(rt, "Video resource is no longer alive");
+          return function(rt, self, arguments, count);
+        });
+    entry = cache.values.emplace(name, jsi::Value(runtime, jsFunction)).first;
+  }
+  return jsi::Value(runtime, entry->second);
+}
+
+jsi::Value RNSVHostObject::getVersionedObject(
+    jsi::Runtime& runtime, const std::string& key, double version,
+    const std::function<void(jsi::Object&)>& fill) {
+  std::lock_guard<std::mutex> lock(cacheMutex);
+  auto& cache = cacheFor(runtime);
+  auto entry = cache.values.find(key);
+  auto versionEntry = cache.versions.find(key);
+  if (entry == cache.values.end() || versionEntry == cache.versions.end() ||
+      versionEntry->second != version) {
+    // A fresh object for each version. Filled in place, the previous one kept
+    // the properties the new content no longer has: the frame of an item
+    // whose decoder had closed stayed in the frames object, with a texture
+    // deleted since, and drawing it after a seek back into the item threw
+    // from the frame callback (Android) or showed a stale picture (iOS).
+    jsi::Object object(runtime);
+    fill(object);
+    entry = cache.values.insert_or_assign(key, jsi::Value(runtime, object))
+                .first;
+    cache.versions[key] = version;
+  }
+  return jsi::Value(runtime, entry->second);
+}
+
+} // namespace RNSkiaVideo

package/cpp/RNSVHostObject.h

@@ -0,0 +1,67 @@
+#pragma once
+
+#include <functional>
+#include <jsi/jsi.h>
+#include <mutex>
+#include <string>
+#include <unordered_map>
+
+#include "RNSVRuntimeLifecycleMonitor.h"
+
+namespace RNSkiaVideo {
+using namespace facebook;
+
+/**
+ * jsi::HostObject that memoizes, per runtime, the JS objects it hands out.
+ *
+ * `jsi::Function::createFromHostFunction` allocates a JS function object and
+ * a native closure on every call. The frame loops of this library read
+ * `decodeNextFrame`, `decodeCompositionFrames`, `encodeFrame`… on the UI or
+ * export runtime at every vsync, so creating those functions on each property
+ * access adds a couple of garbage collected objects per frame for nothing.
+ * Subclasses create each function once per runtime through `getFunction`.
+ *
+ * Cached values are dropped when their runtime is torn down (dev reload), so
+ * no jsi::Value ever outlives its runtime.
+ */
+class RNSVHostObject : public jsi::HostObject, public RuntimeLifecycleListener,
+                       public std::enable_shared_from_this<RNSVHostObject> {
+public:
+  ~RNSVHostObject() override;
+  void onRuntimeDestroyed(jsi::Runtime* runtime) override;
+
+protected:
+  /**
+   * Returns the host function `name` of this object for `runtime`, creating
+   * it with `function` the first time only.
+   */
+  jsi::Value getFunction(jsi::Runtime& runtime, const std::string& name,
+                         unsigned int paramCount,
+                         jsi::HostFunctionType&& function);
+
+  /**
+   * Returns the object cached under `key` for `runtime`. A new object is made
+   * and filled through `fill` only when `version` differs from the version of
+   * the cached one, so it holds exactly what `fill` sets. Callers keep a
+   * monotonic version of the content they expose, so an unchanged content
+   * costs no allocation.
+   */
+  jsi::Value
+  getVersionedObject(jsi::Runtime& runtime, const std::string& key,
+                     double version,
+                     const std::function<void(jsi::Object&)>& fill);
+
+private:
+  struct RuntimeCache {
+    std::unordered_map<std::string, jsi::Value> values;
+    std::unordered_map<std::string, double> versions;
+  };
+  std::mutex cacheMutex;
+  std::unordered_map<jsi::Runtime*, RuntimeCache> caches;
+
+  // Must be called with cacheMutex held; registers the runtime listener on
+  // the first use of a runtime.
+  RuntimeCache& cacheFor(jsi::Runtime& runtime);
+};
+
+} // namespace RNSkiaVideo

package/cpp/RNSVMemoryBudget.cpp

@@ -0,0 +1,68 @@
+#include "RNSVMemoryBudget.h"
+#include "RNSVRuntimeLifecycleMonitor.h"
+#include <cmath>
+#include <jsi/jsi.h>
+
+namespace RNSkiaVideo {
+namespace {
+class BudgetRuntimeListener final : public RuntimeLifecycleListener {
+public:
+  void onRuntimeDestroyed(facebook::jsi::Runtime* runtime) override {
+    MemoryBudget::instance().releaseOwner(runtime);
+  }
+};
+const auto runtimeListener = std::make_shared<BudgetRuntimeListener>();
+uint64_t positiveInteger(facebook::jsi::Runtime& rt,
+                         const facebook::jsi::Value& value) {
+  if (!value.isNumber()) throw facebook::jsi::JSError(rt, "Expected an integer");
+  const auto number = value.asNumber();
+  if (!std::isfinite(number) || number < 1 ||
+      number > 9007199254740991.0 || std::floor(number) != number) {
+    throw facebook::jsi::JSError(rt, "Expected a positive safe integer");
+  }
+  return static_cast<uint64_t>(number);
+}
+}
+
+void MemoryBudget::install(facebook::jsi::Runtime& runtime,
+                           facebook::jsi::Object& module) {
+  namespace jsi = facebook::jsi;
+  RuntimeLifecycleMonitor::addListener(runtime, runtimeListener);
+  module.setProperty(runtime, "frameProtocolVersion", 1);
+  module.setProperty(runtime, "reserveMemory", jsi::Function::createFromHostFunction(
+      runtime, jsi::PropNameID::forAscii(runtime, "reserveMemory"), 2,
+      [](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) {
+        if (count < 1) throw jsi::JSError(rt, "Missing memory size");
+        RuntimeLifecycleMonitor::addListener(rt, runtimeListener);
+        const auto bytes = positiveInteger(rt, args[0]);
+        const auto label = count > 1 && args[1].isString()
+            ? args[1].asString(rt).utf8(rt) : "video resource";
+        return jsi::Value(static_cast<double>(instance().reserve(bytes, label, &rt)));
+      }));
+  module.setProperty(runtime, "releaseMemory", jsi::Function::createFromHostFunction(
+      runtime, jsi::PropNameID::forAscii(runtime, "releaseMemory"), 1,
+      [](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) {
+        if (count < 1) throw jsi::JSError(rt, "Missing reservation");
+        instance().release(positiveInteger(rt, args[0]));
+        return jsi::Value::undefined();
+      }));
+  module.setProperty(runtime, "configureMemoryBudget", jsi::Function::createFromHostFunction(
+      runtime, jsi::PropNameID::forAscii(runtime, "configureMemoryBudget"), 1,
+      [](jsi::Runtime& rt, const jsi::Value&, const jsi::Value* args, size_t count) {
+        if (count < 1) throw jsi::JSError(rt, "Missing memory limit");
+        instance().configure(positiveInteger(rt, args[0]));
+        return jsi::Value::undefined();
+      }));
+  module.setProperty(runtime, "getMemoryBudgetStats", jsi::Function::createFromHostFunction(
+      runtime, jsi::PropNameID::forAscii(runtime, "getMemoryBudgetStats"), 0,
+      [](jsi::Runtime& rt, const jsi::Value&, const jsi::Value*, size_t) {
+        const auto stats = instance().snapshot();
+        jsi::Object result(rt);
+        result.setProperty(rt, "currentBytes", static_cast<double>(stats.currentBytes));
+        result.setProperty(rt, "peakBytes", static_cast<double>(stats.peakBytes));
+        result.setProperty(rt, "allocations", static_cast<double>(stats.allocations));
+        result.setProperty(rt, "maxBytes", static_cast<double>(stats.maxBytes));
+        return jsi::Value(std::move(result));
+      }));
+}
+} // namespace RNSkiaVideo

package/cpp/RNSVMemoryBudget.h

@@ -0,0 +1,100 @@
+#pragma once
+
+#include <cstdint>
+#include <limits>
+#include <mutex>
+#include <stdexcept>
+#include <string>
+#include <unordered_map>
+
+namespace facebook::jsi { class Runtime; class Object; }
+
+namespace RNSkiaVideo {
+
+// Shared by all worklet runtimes. This accounts owned resources, not the
+// opaque caches allocated internally by the graphics driver or media codec.
+class MemoryBudget {
+public:
+  struct Snapshot {
+    uint64_t currentBytes, peakBytes, allocations, maxBytes;
+  };
+  static MemoryBudget& instance() {
+    static MemoryBudget budget;
+    return budget;
+  }
+  uint64_t reserve(uint64_t bytes, const std::string& label,
+                   const void* owner = nullptr) {
+    std::lock_guard<std::mutex> lock(mutex);
+    if (bytes == 0 || bytes > maxBytes || currentBytes > maxBytes - bytes) {
+      throw std::runtime_error("Video memory budget exceeded: " + label);
+    }
+    if (nextToken >= 9007199254740991ULL) {
+      throw std::runtime_error("Video memory reservation identifiers exhausted");
+    }
+    const auto token = nextToken++;
+    reservations.emplace(token, Reservation{bytes, owner});
+    currentBytes += bytes;
+    if (currentBytes > peakBytes) peakBytes = currentBytes;
+    return token;
+  }
+  void release(uint64_t token) {
+    std::lock_guard<std::mutex> lock(mutex);
+    const auto found = reservations.find(token);
+    if (found == reservations.end()) return;
+    currentBytes -= found->second.bytes;
+    reservations.erase(found);
+  }
+  void resize(uint64_t token, uint64_t bytes, const std::string& label) {
+    std::lock_guard<std::mutex> lock(mutex);
+    auto found = reservations.find(token);
+    if (found == reservations.end()) throw std::runtime_error("Unknown video memory reservation");
+    auto remaining = currentBytes - found->second.bytes;
+    if (bytes == 0 || bytes > maxBytes || remaining > maxBytes - bytes)
+      throw std::runtime_error("Video memory budget exceeded: " + label);
+    found->second.bytes = bytes;
+    currentBytes = remaining + bytes;
+    if (currentBytes > peakBytes) peakBytes = currentBytes;
+  }
+  void releaseOwner(const void* owner) {
+    std::lock_guard<std::mutex> lock(mutex);
+    for (auto it = reservations.begin(); it != reservations.end();) {
+      if (it->second.owner == owner) {
+        currentBytes -= it->second.bytes;
+        it = reservations.erase(it);
+      } else ++it;
+    }
+  }
+  void configure(uint64_t bytes) {
+    std::lock_guard<std::mutex> lock(mutex);
+    if (bytes == 0 || bytes < currentBytes) {
+      throw std::runtime_error("Video memory limit is below current reservations");
+    }
+    maxBytes = bytes;
+  }
+  Snapshot snapshot() {
+    std::lock_guard<std::mutex> lock(mutex);
+    return {currentBytes, peakBytes, reservations.size(), maxBytes};
+  }
+  static void install(facebook::jsi::Runtime&, facebook::jsi::Object&);
+
+private:
+  struct Reservation { uint64_t bytes; const void* owner; };
+  std::mutex mutex;
+  std::unordered_map<uint64_t, Reservation> reservations;
+  uint64_t nextToken = 1;
+  uint64_t currentBytes = 0, peakBytes = 0;
+  uint64_t maxBytes = 256ULL * 1024 * 1024;
+};
+
+// Use for C++ owned buffers. Reservations are returned even on exceptions.
+class MemoryReservation {
+public:
+  MemoryReservation(uint64_t bytes, const std::string& label)
+      : token(MemoryBudget::instance().reserve(bytes, label)) {}
+  ~MemoryReservation() { MemoryBudget::instance().release(token); }
+  MemoryReservation(const MemoryReservation&) = delete;
+  MemoryReservation& operator=(const MemoryReservation&) = delete;
+private:
+  uint64_t token;
+};
+} // namespace RNSkiaVideo

package/cpp/RNSVRuntimeLifecycleMonitor.cpp

@@ -0,0 +1,88 @@
+#include "RNSVRuntimeLifecycleMonitor.h"
+
+#include <algorithm>
+#include <memory>
+#include <mutex>
+#include <unordered_map>
+#include <vector>
+#include <utility>
+
+namespace RNSkiaVideo {
+
+struct ListenerRegistration {
+  RuntimeLifecycleListener* identity;
+  std::weak_ptr<RuntimeLifecycleListener> listener;
+};
+static std::unordered_map<jsi::Runtime*, std::vector<ListenerRegistration>> listeners;
+static std::mutex listenersMutex;
+
+struct RuntimeLifecycleMonitorObject : public jsi::HostObject {
+  jsi::Runtime* runtime;
+  explicit RuntimeLifecycleMonitorObject(jsi::Runtime* runtime)
+      : runtime(runtime) {}
+  ~RuntimeLifecycleMonitorObject() override {
+    std::vector<ListenerRegistration> registrations;
+    {
+      std::lock_guard<std::mutex> lock(listenersMutex);
+      auto entry = listeners.find(runtime);
+      if (entry != listeners.end()) {
+        registrations = std::move(entry->second);
+        listeners.erase(entry);
+      }
+    }
+    // A listener's final reference can unregister it. Release the registry
+    // mutex before locking or destroying those references.
+    for (const auto& registration : registrations) {
+      if (auto listener = registration.listener.lock()) {
+        listener->onRuntimeDestroyed(runtime);
+      }
+    }
+  }
+};
+
+void RuntimeLifecycleMonitor::addListener(jsi::Runtime& runtime,
+    const std::shared_ptr<RuntimeLifecycleListener>& listener) {
+  bool installMonitor = false;
+  {
+    std::lock_guard<std::mutex> lock(listenersMutex);
+    auto entry = listeners.find(&runtime);
+    if (entry == listeners.end()) {
+      listeners.emplace(&runtime, std::vector<ListenerRegistration>{
+                                      {listener.get(), listener}});
+      installMonitor = true;
+    } else {
+      const auto identity = listener.get();
+      auto& entries = entry->second;
+      entries.erase(std::remove_if(entries.begin(), entries.end(),
+                                   [](const auto& item) {
+                                     return item.listener.expired();
+                                   }), entries.end());
+      bool registered = false;
+      for (const auto& item : entries) registered |= item.identity == identity;
+      if (!registered) entries.push_back({identity, listener});
+    }
+  }
+  if (installMonitor) {
+    // The global object owns the monitor: when the runtime is torn down the
+    // monitor is destroyed with it and notifies the listeners.
+    runtime.global().setProperty(
+        runtime, "__rnskv_rt_lifecycle_monitor",
+        jsi::Object::createFromHostObject(
+            runtime, std::make_shared<RuntimeLifecycleMonitorObject>(&runtime)));
+  }
+}
+
+void RuntimeLifecycleMonitor::removeListener(
+    jsi::Runtime& runtime, RuntimeLifecycleListener* listener) {
+  std::lock_guard<std::mutex> lock(listenersMutex);
+  auto entry = listeners.find(&runtime);
+  if (entry != listeners.end()) {
+    auto& entries = entry->second;
+    entries.erase(std::remove_if(entries.begin(), entries.end(),
+                                 [listener](const auto& item) {
+                                   return item.identity == listener;
+                                 }), entries.end());
+  }
+}
+
+} // namespace RNSkiaVideo

package/cpp/RNSVRuntimeLifecycleMonitor.h

@@ -0,0 +1,33 @@
+#pragma once
+
+#include <jsi/jsi.h>
+#include <memory>
+
+namespace RNSkiaVideo {
+
+namespace jsi = facebook::jsi;
+
+/**
+ * Gets notified right before a jsi::Runtime is torn down. Anything that keeps
+ * jsi values of that runtime alive (see RNSVHostObject) has to drop them at
+ * that point: a jsi::Value destroyed after its runtime is undefined behaviour.
+ */
+struct RuntimeLifecycleListener {
+  virtual ~RuntimeLifecycleListener() {}
+  virtual void onRuntimeDestroyed(jsi::Runtime* runtime) = 0;
+};
+
+/**
+ * Runtime destruction is observed through a host object installed on the
+ * runtime's global object: its destructor runs while the runtime is being
+ * torn down. Listeners must be added from the runtime's own thread; they can
+ * be removed from any thread.
+ */
+struct RuntimeLifecycleMonitor {
+  static void addListener(jsi::Runtime& runtime,
+                          const std::shared_ptr<RuntimeLifecycleListener>& listener);
+  static void removeListener(jsi::Runtime& runtime,
+                             RuntimeLifecycleListener* listener);
+};
+
+} // namespace RNSkiaVideo

package/docs/ANDROID_DEVICE_306.md

@@ -0,0 +1,95 @@
+# Android physical-device diagnostics — Skia 3.0.6
+
+Latest follow-up (2026-10-08): the export-worklet fix passed two comparison workloads and four consecutive full montages on Pixel 8a. Two-montage idle PSS fell from 737.83 to 577.20 MiB; the fourth extended-run settled PSS decreased from 603.57 to 593.80 MiB. See [current memory results](NATIVE_MEMORY_INVESTIGATION_306.md). The frozen transport campaigns below retain their original binaries and results.
+
+The earlier AHardwareBuffer Release transport checkpoint passed all 24 focused physical-device attempts on a Google Pixel 8a (Android 17, API 37): three repetitions of eight playback/export scenarios, including H264/HEVC full 4K in copy and direct modes. Tracked owned bytes and resource reservations returned to zero after each strict two-second cleanup. The earlier CPU failures are preserved below. This qualifies these focused operations, not the full instrumentation suite or permanent leak absence.
+
+[Machine-readable evidence](../benchmark/android-device-306-verification.json) preserves per-attempt status, raw-file hashes, outstanding reservations and binary/source fingerprints. Raw reports stay local and ignored because they include device identifiers. This is a candidate-only diagnostic campaign, without a valid old-library A/B comparison or a cross-platform performance comparison.
+
+## Current AHardwareBuffer checkpoint
+
+Release APK SHA-256 `59afb795cfc9fe86d5bbbbaaa487cf0129130dd6538d0f5faf5d6bc11a6edbfa`; source snapshot `35c1f59a69c1a2d6cb04170fed083e3c6f81c51cd94efc35a490181cdd06ee43` over 123 preserved source files. The binary uses the same RN/Skia/WebGPU versions, fixtures, seed, original resolutions, 512 MiB quota, 720 × 720 physical-pixel preview and 640 × 360 exports as the diagnostic workload. The app was restarted for every attempt, producing 24 distinct processes. All 986 native samples reported nominal thermal state, normal power mode and active foreground lifecycle; zero samples were dropped. Before the additional repetitions, the phone was AC powered, at 100% battery and 31.1 °C.
+
+| Case | Strict passes | Median peak RSS (MiB) | Median peak PSS (MiB) |
+| --- | ---: | ---: | ---: |
+| H264 1080p copy | 3/3 | 337.676 | 308.423 |
+| H264 4K copy | 3/3 | 408.977 | 550.610 |
+| HEVC 4K copy | 3/3 | 408.812 | 541.787 |
+| H264 1080p direct | 3/3 | 337.691 | 307.981 |
+| H264 4K direct | 3/3 | 409.098 | 553.601 |
+| HEVC 4K direct | 3/3 | 408.762 | 511.776 |
+| H264 export copy | 3/3 | 309.879 | 226.266 |
+| H264 export direct | 3/3 | 309.641 | 226.619 |
+
+RSS/PSS peaks are sampled independently. Owned bytes and reservations were zero in every final settled sample; decoder-count and in-flight-frame collectors remain unavailable. Settled physical memory, per-attempt peaks and raw hashes remain in the machine-readable report. Returning owned reservations to zero does not establish zero driver caches or the absence of leaks during longer use.
+
+The 4K callback cadences were 45.442/s for H264 copy, 42.795/s for H264 direct, 44.578/s for HEVC copy and 43.352/s for HEVC direct. The 1080p values were 57.707/s and 58.088/s. All callback-duration p95 upper histogram bounds were ≤ 0.25 ms. These are CPU callback diagnostics, excluding preload/import and GPU completion; they are not decoded or presented FPS. Frame availability was present at every draw; decoder drops remain unknown.
+
+All six exports produced 60 decoded frames at 640 × 360, H264, 30 fps, with exact monotonic presentation timestamps from zero through 59/30 seconds and progress 60/60. Median full pipeline time (`encodeMs`) was 2354.867 ms in copy mode and 2227.471 ms in direct mode; stat/probe time was 386.236/370.346 ms, and pipeline plus probe/removal (`exportMs`) was 2819.146/2767.245 ms. Generic export pixel/audio validators remain unavailable.
+
+A separate functional CPU/AHB oracle passed 10/10 cases across padded dimensions, portrait, 90° rotation, H264 full 4K and HEVC full 4K, each in copy/direct mode. Two decoded timestamps per case compared 66,560 sampled RGBA channels with maximum error zero. The first raw frame remained readable and importable after later decode and producer teardown. Six targeted native AHB ownership, finish/abort, quota and read-validation tests passed with zero skips in 0.168 s; 43 JVM tests also passed. The oracle uses readback and is excluded from performance measurements. It validates sampled SDR patches, not whole-image fidelity, HDR or audio.
+
+Decode renders the codec texture into immutable AHardwareBuffer storage, completes the producer GL fence synchronously, and imports it through the shared WebGPU device before an owned GPU snapshot. Normal AHB rendering performs no RGBA CPU readback or full-frame CPU copy. Export continues through CPU RGBA upload. End-to-end zero-copy, complete GPU memory, a 256 MiB quota and long-duration stability have not been qualified. The one-attempt CPU scoped-copy reference uses a different binary and is insufficient for a controlled A/B improvement claim.
+
+## Current AHardwareBuffer lifecycle follow-up
+
+Four additional existing catalog cases each passed once on the same frozen Release APK, including their strict cleanup criterion: `paused-clock-and-resume`, `closed-item-leaves-frame-map`, `held-image-survives-seek`, and `4k-x8-lazy-direct`. Their 1267 native samples were all nominal/normal/active with zero samples dropped. The paused clock moved by zero during the 250 ms pause and advanced by 0.425587 s after resume; frame-map pruning removed clips 0/1 and retained only clip 2.
+
+The case named `held-image-survives-seek` performed a paused seek and 2.5 s wait followed by five seeks. It does not retain and compare an independent SkImage, and its immutability pixel validator remains unavailable. Its pass establishes operation completion and cleanup, while the separate CPU/AHB oracle above validates sampled pixels on a retained raw frame after producer teardown. Paused seeks use clock/visible-item-ID checks, with native presentation-timestamp identity unavailable.
+
+The lazy/direct montage used eight sequential full-resolution H264/HEVC 4K clips and completed play, 10 seeks, 81 scrub requests, loop, export, 25 churn cycles, a callback diagnostic and 40 remount cycles in 144.242 s. Its export contained 360 decoded 1080 × 1080 H264 frames at 30 fps over 12 s, with exact monotonic PTS from zero through 359/30 s and progress 360/360. Generic montage pixel/audio validators were not supplied.
+
+This montage had a substantially higher physical memory cost than the simple playback cases: peak RSS **800.250 MiB**, peak PSS **1037.908 MiB** and peak tracked owned bytes **257.080 MiB**. Final settled RSS remained **785.816 MiB**, although tracked owned bytes and reservations returned to zero. The physical retention is not attributed to a particular driver/cache/VM component. One completed set of 25 churn/40 remount cycles establishes neither a memory plateau nor endurance or leak absence. The 256 MiB quota and eager/concurrent pressure remain unqualified.
+
+Five existing JNI CPU-fallback ownership/refusal tests passed again on the current instrumentation artifact with zero skips in 0.896 s, separately from the six AHB tests. The benchmark app was force-stopped after testing to release KEEP_SCREEN_ON; no system settings were changed, and no owned test runner or sampler remains active.
+
+The subsequent [Android cache-retention investigation](ANDROID_MEMORY_RETENTION_306.md) separates process memory categories and measures Graphite caches with a diagnostic build. It identifies reclaimable cache retention and a separate upstream reference-count defect. These experiments do not change the production qualification above or establish that the remaining process memory is leak-free.
+
+The [export-cache follow-up](ANDROID_EXPORT_CACHE_306.md) records the later production changes and their own binary identity, pixel checks and repeated montage results. Keep those measurements separate from this original AHB checkpoint.
+
+## Historical CPU diagnostic checkpoint
+
+The prior CPU implementation completed all six 1080p and six export operations, but its twelve full-resolution 4K attempts failed controlled ART allocation; every attempt failed strict cleanup. Neither quota nor cleanup thresholds were relaxed.
+
+## Historical CPU workload and identity
+
+- React Native 0.86.2, Skia 3.0.6, WebGPU 0.12.1; arm64-v8a Release on a physical Pixel 8a.
+- Candidate APK SHA-256 `352f728d99ab6b69e75b732580c3cab12c8905bebe31f400f6afc8f399e7e08e`; bundle `fa577288aa58d4beecb8aa71ce8b51f14ceb1eee84f17942043461ea786d5c22`; source snapshot `82ef4f57aca124e1725649f314cdf7ee425442f261894ce54e89587c78cb9b97` (source bytes correspond to commit `2ab84c8`).
+- Catalog `2026-10-07.1`, identical seed, eight cases with three independent cold processes each. Each raw one-case execution has repetition zero; the external campaign records repetitions zero through two separately.
+- Preview: 720 × 720 physical pixels, four seconds, original uncapped 1080p or 4K H264/HEVC inputs, no seeks. Export: two seconds, 60 frames, 640 × 360 H264 at 30 fps and a requested 2 Mbit/s.
+- Library memory budget: 512 MiB. All 911 native samples reported nominal thermal state, normal power mode and active foreground lifecycle. No collection samples were dropped. The phone was AC powered; battery temperature before the campaign was 37.7 °C.
+
+Both requested copy and direct modes use the historical CPU RGBA readback/upload fallback. The label “direct” does not establish a zero-copy implementation. The Graphite import uses a reusable WebGPU texture and an owned GPU snapshot rather than creating a new cached raster upload for each frame.
+
+## Recorded results
+
+Peaks below are medians over three attempts. RSS and PSS are sampled independently, so their peak values must not be divided or interpreted as simultaneous memory categories.
+
+| Case | Completed operations | Strict passes | Peak RSS (MiB) | Peak PSS (MiB) |
+| --- | ---: | ---: | ---: | ---: |
+| H264 1080p copy | 3/3 | 0/3 | 612.336 | 563.594 |
+| H264 4K copy | 0/3 | 0/3 | 720.227 | 754.432 |
+| HEVC 4K copy | 0/3 | 0/3 | 724.922 | 780.497 |
+| H264 1080p direct | 3/3 | 0/3 | 607.219 | 567.692 |
+| H264 4K direct | 0/3 | 0/3 | 744.273 | 768.242 |
+| HEVC 4K direct | 0/3 | 0/3 | 744.051 | 754.546 |
+| H264 export copy | 3/3 | 0/3 | 365.293 | 280.858 |
+| H264 export direct | 3/3 | 0/3 | 363.887 | 279.066 |
+
+Completed 1080p operations recorded median callback cadences of 56.885/s (copy) and 55.820/s (direct), with the callback-duration p95 in the ≤ 0.25 ms histogram bucket. These are callback diagnostics, not decoded-video FPS, presented FPS or GPU duration. Callback duration excludes frame preload/upload. Zero missing-frame availability does not establish zero dropped decoder frames; decoder drops and complete GPU timing remain unavailable.
+
+All six exports produced 60 decoded frames at 640 × 360, H264, 30 fps, with exact monotonic presentation timestamps from zero through 59/30 seconds. Generic pixel and audio validation remain unavailable. Median full export pipeline time (`encodeMs`) was 2168.225 ms (copy) and 2100.074 ms (direct); the separate stat/probe time was 360.318/352.350 ms. Pipeline plus probe and output removal (`exportMs`) was 2612.350/2547.482 ms. `elapsedMs` additionally includes pre-export settling and is not an export-duration metric.
+
+Outstanding native backing reservations remain visible in every settled record. The two-second cleanup failure alone cannot distinguish deferred Java/Hermes collection from a permanent leak. Decoder-count and in-flight-frame collectors are unavailable and are not reported as zero. Android native-heap PSS is not allocator heap size; complete process GPU allocation and iOS-style physical footprint are unavailable.
+
+## Bounded allocation retry follow-up
+
+A separate APK (`a883499979179fa6c17ae4887a6eafd4d411043ac40a4a5a75f689f2e39d8924`) retries only the backing allocation once after draining already queued dead phantom references, with the same owner and reservation. It never forces GC, recycles live aliases, increases the quota or reduces the decode resolution.
+
+A single full-resolution H264 4K attempt still failed with a controlled allocation error after two attempts and failed strict cleanup. No repeated performance campaign was launched for that unsuccessful recovery. The corresponding 37 JVM tests and five physical JNI ownership/refusal tests passed. These unit results do not qualify 4K playback or whole-application cleanup.
+
+The subsequent scoped-copy APK (`789735e095937cc168865986a353613d29f065feeff40bca8676ab0895b2ef0a`, source snapshot `0a842f1f6f02ca4bb6f274050adcb15897b2cbc78aa76770b1aa94171ccfca3f`) completed one attempt for each of the same eight cases without OOM, including all four full-resolution 4K copy/direct cases and both exports. All eight still failed strict two-second cleanup. Five JNI ownership tests passed again (0.572 s). This establishes completion of these bounded operations; it is not a complete memory qualification or a repeated performance comparison. The extra CPU copy and per-attempt physical memory remain visible in the machine-readable follow-up. The later AHardwareBuffer result above is a separate binary and campaign; these historical CPU failures remain unchanged.
+
+## Native instrumentation scope
+
+The current inventory contains the original 40 named cases / 86 parameterized executions plus ownership additions, for 52 named cases / 102 planned executions. The full current suite has not passed. Six AHB ownership tests passed on the current AHB checkpoint. The five CPU ownership/refusal tests passed on the earlier scoped-copy checkpoint. Before the ART guard change, 15 focused decode/export tests passed; a separate earlier full-suite attempt completed two passes, failed one lazy-4K cadence assertion and crashed during one eager eight-4K allocation, leaving 90 executions unrun. The record preserves these different source checkpoints.

package/docs/ANDROID_EXPORT_CACHE_306.md

@@ -0,0 +1,48 @@
+# Export cache and provider ownership — Skia 3.0.6
+
+Historical cache/provider-fix checkpoint (2026-10-07). The additional native/VM growth described below was subsequently investigated and substantially reduced by the [export-worklet fix](NATIVE_MEMORY_INVESTIGATION_306.md), measured on both physical platforms on October 8. This report preserves the earlier measurements; its iPhone validation and unresolved-growth statements describe that earlier checkpoint.
+
+The library now adopts the initial reference of Skia's `ImageProvider` and releases unused resources from its dedicated export recorder when an export session closes. Public playback/export signatures are unchanged. Reapply the guarded Skia patch and rebuild the native application.
+
+## Scope of the change
+
+`ImageProvider::Make()` now uses `sk_make_sp<ImageProvider>()`. The original `sk_ref_sp(new ImageProvider)` increments the newly allocated object's initial reference and leaves it orphaned when its smart pointers close. The installed-factory ownership test uses the real Skia reference counter and verifies that an alias remains valid until its own final release.
+
+Export cleanup first drains drawing and any frame processor, closes decoder/encoder/image/canvas/surface consumers, then invokes the private Skia recorder cleanup on the dedicated export runtime. The native method checks recording insertion and synchronous submission, drops the temporary recording and frees unused resources from that recorder only. Reservation release and successful promise settlement follow. Failure retains the existing quarantine and blocks reuse of the runtime. An old native binary is rejected before export allocations.
+
+This policy does not trim the preview/UI recorder or the shared context, change their budgets, destroy the shared GPU device, force GC, or downscale video. It is not the broad experimental purge from the [earlier investigation](ANDROID_MEMORY_RETENTION_306.md). Preview, 3D and ML consumers can continue to retain their own resources; this is not a whole-process memory limit. Queue completion still uses the shared GPU queue, so this is not a promise of zero impact on concurrent GPU latency.
+
+## Physical Android results
+
+The [machine-readable evidence](../benchmark/android-memory-optimization-306.json) records binary/source fingerprints, raw-report hashes, sampled conditions, memory categories, export outputs, pixel comparisons and remount checkpoints. Reports are sanitized; raw device identifiers stay local.
+
+The production candidate APK is `fd4f6f277207d809fe40203439fcfa62b34e1bfcaffe42ad51adaf48db9f6254`. All workloads use the physical Pixel 8a, Android 17, arm64 Release, Skia 3.0.6 / WebGPU 0.12.1. The montage uses the same eight full-resolution sequential H264/HEVC 4K clips, 512 MiB owned quota, 720-square preview, 360-frame 1080-square export, 25 churn cycles and 40 remount cycles per case.
+
+One cold-process montage, total PSS after 60 seconds at rest:
+
+| Build | Total PSS (MiB) | GL mtrack (MiB) |
+| --- | ---: | ---: |
+| Original production AHB checkpoint | 702.78 | 397.46 |
+| Provider reference correction only | 692.97 | 397.40 |
+| Provider correction + export recorder cleanup | 584.62 | 289.32 |
+
+The combined candidate is 118.16 MiB below the original and 108.35 MiB below the provider-only run. These are observed differences from one run per build, not a statistical savings guarantee. The reference correction alone did not materially reduce the GL mtrack category. The process remains much larger than the roughly 164 MiB idle menu, and tracked owned resources returning to zero does not explain all retained memory.
+
+Within the final 40-remount operation, `/proc/self/status VmRSS` increased by approximately 13.19 MiB in the baseline run, 12.87 MiB with the provider correction alone and 13.27 MiB with both corrections. This specific growth is not resolved by the changes. These RSS measurements must not be mixed with `dumpsys TOTAL RSS` or interpreted as exact live allocation counts.
+
+Two successive montages were then run in one cold process for each binary, with the same protocol: 50 churn cycles, 80 remount cycles and two 360-frame exports per process. Both cases passed in both binaries. After the second montage and 60 seconds at rest, total PSS was **861.14 MiB for the original versus 737.83 MiB for the candidate**, an observed reduction of **123.31 MiB (14.32%)**.
+
+The candidate nevertheless grows substantially across the two montages. Native-heap PSS and the Unknown category finish at approximately 142/137 MiB in both binaries, versus approximately 92/74 MiB after a single montage. The change reduces retained graphics memory; it does not resolve that additional native/VM growth. These categories include the benchmark process and its instrumentation, and do not yet attribute outstanding allocations to the library, framework, driver or collector. Two montages do not establish a plateau.
+
+All seven montage cases represented in the evidence (including the earlier single baseline) passed, with nominal/normal/active conditions in every native sample, no dropped collection samples and zero owned bytes/resources in every settled sample. All seven exports decoded to 360 frames with exact monotonic PTS at 30 fps. The candidate's three montage cases and its pixel oracle passed. The corrected APK was restored on the Pixel after comparison, and the test application was stopped to release KEEP_SCREEN_ON.
+
+The final candidate also passed the CPU/AHB pixel oracle: ten cases covering padded dimensions, portrait, 90-degree rotation, H264/HEVC full 4K and copy/direct modes. The 66,560 compared RGBA channels had maximum error zero, including the retained raw frame after producer teardown. This separate functional readback is excluded from memory/performance measurements. It checks sampled SDR regions, not whole-image fidelity, HDR or audio.
+
+## Validation and limits
+
+- 195 JavaScript tests pass, including cleanup ordering, refusal to purge after a failed surface drain, missing-native-patch preflight and quarantine after a failed cache drain.
+- Five guarded-installer tests pass, including upgrade from the earlier canvas-only patch, repeat application and conflict refusal before mutation.
+- Portable native policy/ownership tests pass with AddressSanitizer and UndefinedBehaviorSanitizer, including the installed provider factory.
+- Android arm64 Release compilation, TypeScript, package build and strict package validation pass. The patched `JsiSkApi`/surface headers compile against the iOS simulator SDK; the new behavior has not been measured on a physical iPhone.
+
+The result establishes a narrower production memory improvement and correct completion of these bounded operations. It does not establish a memory plateau, leak absence, full native-suite coverage, a 256 MiB quota, or faster presented video FPS. Remaining growth needs allocation-stack attribution separating recorder caches, Dawn/driver allocations, native heap and VM backing stores. Preserve the same workload and collectors for that investigation; do not mask growth by increasing quotas or forcing collection.