@pictor-sdk/video-android 0.1.0

package/android/src/main/cpp/pictor_videosurface.cpp

@@ -0,0 +1,735 @@
+/**
+ * The persistent presentation surface: one external texture, one SurfaceTexture.
+ *
+ * Everything that touches GL runs on the UI runtime, because that is where
+ * Skia's context is current — established by the earlier context probe, which
+ * found the same EGL context handle before and after a Skia GPU call on that
+ * thread. A `SurfaceTexture` binds to the calling thread's current context, so
+ * it is built from here rather than from Kotlin on some other thread.
+ *
+ * The host object holds a global ref to the Java objects and nothing else. Its
+ * destructor is trivial: teardown is an explicit call, in order, on this
+ * thread. A finalizer running on a GC thread would issue `glDeleteTextures`
+ * against whatever context happened to be current there, which is how this
+ * project has crashed before.
+ */
+#include <EGL/egl.h>
+#include <GLES2/gl2.h>
+#include <GLES2/gl2ext.h>
+#include <atomic>
+#include <jni.h>
+#include <mutex>
+#include <jsi/jsi.h>
+
+#include <ctime>
+#include <memory>
+
+namespace jsi = facebook::jsi;
+
+namespace pictor {
+namespace {
+
+/**
+ * How many host objects have been constructed, ever.
+ *
+ * A façade is cheap and cloning one is harmless, but *constructing* one is a new
+ * backing state unless the state lives elsewhere. This counter is what
+ * distinguishes the two, and it is reported by the probe rather than inferred.
+ */
+std::atomic<int> g_factoryCount{0};
+
+/** Monotonic stamp for the last mutation, so two readers can be ordered. */
+std::atomic<long> g_mutationSeq{0};
+/** Thread id of that mutation, as a small stable number. */
+std::atomic<long> g_mutationThread{0};
+
+long threadTag() {
+  static std::atomic<long> next{1};
+  thread_local long tag = next.fetch_add(1);
+  return tag;
+}
+
+JavaVM *g_vm = nullptr;
+
+/** The UI thread is a Java thread already; this only fetches its env. */
+JNIEnv *env() {
+  if (g_vm == nullptr) return nullptr;
+  JNIEnv *e = nullptr;
+  if (g_vm->GetEnv(reinterpret_cast<void **>(&e), JNI_VERSION_1_6) != JNI_OK) {
+    return nullptr;
+  }
+  return e;
+}
+
+class SurfaceHostObject : public jsi::HostObject {
+public:
+  ~SurfaceHostObject() override = default; // trivial, deliberately
+
+  jsi::Value get(jsi::Runtime &rt, const jsi::PropNameID &name) override {
+    const auto prop = name.utf8(rt);
+    auto self = this;
+
+    if (prop == "create") {
+      return jsi::Function::createFromHostFunction(
+          rt, name, 2,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *args,
+                 size_t count) -> jsi::Value {
+            const int width = count > 0 ? (int)args[0].asNumber() : 256;
+            const int height = count > 1 ? (int)args[1].asNumber() : 256;
+            jsi::Object out(rt);
+            out.setProperty(rt, "textureId", 0.0);
+            out.setProperty(rt, "ok", false);
+
+            if (eglGetCurrentContext() == EGL_NO_CONTEXT) {
+              out.setProperty(rt, "error",
+                              jsi::String::createFromUtf8(
+                                  rt, "no EGL context current on this thread"));
+              return jsi::Value(std::move(out));
+            }
+            JNIEnv *e = env();
+            if (e == nullptr) {
+              out.setProperty(
+                  rt, "error",
+                  jsi::String::createFromUtf8(rt, "no JNIEnv on this thread"));
+              return jsi::Value(std::move(out));
+            }
+
+            /*
+              Retire whatever this slot already holds, before making more.
+
+              `create` used to overwrite `texture_`, `surfaceTexture_`,
+              `surface_`, `flag_` and `cls_` in place. Every field it
+              overwrote was the only reference to a live object: a GL external
+              texture, a SurfaceTexture and its buffer, a Surface, a listener
+              still watching the old texture, and four JNI global refs. None of
+              it was reachable afterwards and none of it was freed.
+
+              Measured on a Pixel 7 across eight mount cycles of the production
+              stack — no CompositionPlayer, no ring — graphics memory rose from
+              77.3 MB to 141.4 MB in steps of exactly 8,312 KB. A constant
+              increment is one object per cycle, not bloat, and 8,312 KB is a
+              1080x1920 buffer.
+
+              Explicit, on this thread, which has both an EGL context and an
+              attached JNIEnv. Not a destructor: the JSI object outlives the GL
+              thread and a GC-time free would run where neither is available.
+            */
+            retire(self, e, true);
+            self->creates_++;
+
+            while (glGetError() != GL_NO_ERROR) {
+            }
+            glGenTextures(1, &self->texture_);
+            glBindTexture(GL_TEXTURE_EXTERNAL_OES, self->texture_);
+            glTexParameteri(GL_TEXTURE_EXTERNAL_OES, GL_TEXTURE_MIN_FILTER,
+                            GL_LINEAR);
+            glTexParameteri(GL_TEXTURE_EXTERNAL_OES, GL_TEXTURE_MAG_FILTER,
+                            GL_LINEAR);
+            glTexParameteri(GL_TEXTURE_EXTERNAL_OES, GL_TEXTURE_WRAP_S,
+                            GL_CLAMP_TO_EDGE);
+            glTexParameteri(GL_TEXTURE_EXTERNAL_OES, GL_TEXTURE_WRAP_T,
+                            GL_CLAMP_TO_EDGE);
+            const GLenum error = glGetError();
+
+            jclass cls = e->FindClass("dev/pictor/video/VideoSurface");
+            jmethodID create = e->GetStaticMethodID(
+                cls, "create", "(III)Landroid/graphics/SurfaceTexture;");
+            jobject texture = e->CallStaticObjectMethod(
+                cls, create, (jint)self->texture_, (jint)width, (jint)height);
+            jmethodID surfaceOf = e->GetStaticMethodID(
+                cls, "surfaceOf",
+                "(Landroid/graphics/SurfaceTexture;)Landroid/view/Surface;");
+            jobject surface = e->CallStaticObjectMethod(cls, surfaceOf, texture);
+
+            self->surfaceTexture_ = e->NewGlobalRef(texture);
+            self->surface_ = e->NewGlobalRef(surface);
+            self->cls_ = (jclass)e->NewGlobalRef(cls);
+
+            // Published so a player can render into it, and watched so frames
+            // raise a flag instead of doing work on the producer's thread.
+            // Returns the generation this surface was registered under. Kept
+            // so teardown can prove it is retiring its own surface: a screen's
+            // cleanup routinely runs after the next screen's setup.
+            jmethodID reg = e->GetStaticMethodID(cls, "register",
+                                                 "(Landroid/view/Surface;)I");
+            self->generation_.store(e->CallStaticIntMethod(cls, reg, surface));
+            g_mutationSeq.fetch_add(1);
+            g_mutationThread.store(threadTag());
+            jclass boolCls = e->FindClass("java/util/concurrent/atomic/AtomicBoolean");
+            jobject flag = e->NewObject(
+                boolCls, e->GetMethodID(boolCls, "<init>", "(Z)V"), JNI_FALSE);
+            self->flag_ = e->NewGlobalRef(flag);
+            jmethodID watch = e->GetStaticMethodID(
+                cls, "watch",
+                "(Landroid/graphics/SurfaceTexture;Ljava/util/concurrent/atomic/AtomicBoolean;)V");
+            e->CallStaticVoidMethod(cls, watch, texture, flag);
+
+            out.setProperty(rt, "textureId", (double)self->texture_);
+            out.setProperty(rt, "glError", (double)error);
+            out.setProperty(rt, "ok", self->surfaceTexture_ != nullptr);
+            // Reported so readiness can be generation-aware. A caller that only
+            // knows "a surface exists" cannot tell the one it prepared against
+            // from the one that replaced it while the picker was open.
+            out.setProperty(rt, "generation", (double)self->generation_.load());
+            out.setProperty(rt, "error", jsi::String::createFromUtf8(rt, ""));
+            return jsi::Value(std::move(out));
+          });
+    }
+
+    if (prop == "surfaceCounters") {
+      /*
+        Creates, retires, and the difference.
+
+        The regression this exists for: `create` used to overwrite a live
+        surface without retiring it, so `live` climbed by one per call and each
+        step was a 1080x1920 buffer nothing could reach. It is exposed rather
+        than inferred from graphics memory, which settles on its own schedule
+        and cannot say whose bytes it is holding.
+
+        `live` must never exceed one, and must return to zero after a release.
+      */
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            jsi::Object out(rt);
+            out.setProperty(rt, "creates", (double)self->creates_);
+            out.setProperty(rt, "retires", (double)self->retires_);
+            out.setProperty(rt, "live", (double)(self->creates_ - self->retires_));
+            out.setProperty(rt, "generation", (double)self->generation_.load());
+            return jsi::Value(std::move(out));
+          });
+    }
+
+    if (prop == "pending") {
+      // Whether a frame is waiting, asked of the *same* `FramePending` instance
+      // the listener updates. Deliberately a call across JNI on every tick
+      // rather than a value mirrored into JS: a mirror is a copy, a copy is
+      // stale between updates, and the whole failure being fixed here was a
+      // consumer acting on its own idea of availability rather than the
+      // producer's.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            JNIEnv *e = env();
+            if (e == nullptr || self->cls_ == nullptr) return jsi::Value(false);
+            jmethodID has = e->GetStaticMethodID(self->cls_, "hasPendingFrame",
+                                                 "(I)Z");
+            return jsi::Value(e->CallStaticBooleanMethod(
+                                  self->cls_, has, self->generation_.load()) == JNI_TRUE);
+          });
+    }
+
+    if (prop == "identity") {
+      // Who this object is, and who it is talking to.
+      //
+      // `self` is the host object the consumer captured; `controllerId` and
+      // `pendingId` are the producer's. A consumer holding a stale object is
+      // invisible in the values — a captured `undefined` surface and a live one
+      // both report "nothing pending" — so identity is the only thing that can
+      // tell them apart, and it is recorded from inside the worklet rather than
+      // sampled from JS, which would only prove what JS can see.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            jsi::Object out(rt);
+            // The façade: this host object. May legitimately differ between
+            // runtimes — a clone is harmless.
+            out.setProperty(
+                rt, "facadeId",
+                (double)(reinterpret_cast<uintptr_t>(self) & 0x7fffffff));
+            // The backing state the façade resolves through. **Must** match
+            // across runtimes: if it does not, two independent states exist and
+            // every value read from them is separately plausible and jointly
+            // wrong.
+            out.setProperty(
+                rt, "backingId",
+                (double)(reinterpret_cast<uintptr_t>(&self->generation_) & 0x7fffffff));
+            out.setProperty(rt, "factoryCount",
+                            (double)g_factoryCount.load());
+            out.setProperty(rt, "mutationSeq", (double)g_mutationSeq.load());
+            out.setProperty(rt, "mutationThread",
+                            (double)g_mutationThread.load());
+            out.setProperty(rt, "readThread", (double)threadTag());
+            out.setProperty(
+                rt, "surfaceId",
+                (double)(reinterpret_cast<uintptr_t>(self) & 0x7fffffff));
+            out.setProperty(rt, "controllerId", 0.0);
+            out.setProperty(rt, "pendingId", 0.0);
+            out.setProperty(rt, "generation", (double)self->generation_.load());
+            JNIEnv *e = env();
+            if (e == nullptr || self->cls_ == nullptr) {
+              return jsi::Value(std::move(out));
+            }
+            jmethodID controller =
+                e->GetStaticMethodID(self->cls_, "getControllerId", "()I");
+            jmethodID pending =
+                e->GetStaticMethodID(self->cls_, "getPendingId", "()I");
+            if (controller != nullptr) {
+              out.setProperty(rt, "controllerId",
+                              (double)e->CallStaticIntMethod(self->cls_, controller));
+            }
+            if (pending != nullptr) {
+              out.setProperty(rt, "pendingId",
+                              (double)e->CallStaticIntMethod(self->cls_, pending));
+            }
+            e->ExceptionClear();
+            return jsi::Value(std::move(out));
+          });
+    }
+
+    if (prop == "pendingSnapshot") {
+      // One reading of three facts. Asking separately means asking at three
+      // different instants, and a frame arriving between two of them makes the
+      // consumer look like it disagrees with the producer when both answers were
+      // true when given.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            JNIEnv *e = env();
+            if (e == nullptr || self->cls_ == nullptr) return jsi::Value(0.0);
+            jmethodID snap =
+                e->GetStaticMethodID(self->cls_, "pendingSnapshot", "(I)J");
+            if (snap == nullptr) {
+              e->ExceptionClear();
+              return jsi::Value(0.0);
+            }
+            return jsi::Value(static_cast<double>(e->CallStaticLongMethod(
+                self->cls_, snap, self->generation_.load())));
+          });
+    }
+
+    if (prop == "pendingDueNs") {
+      // The time the pending frame was asked to be presented at, so the
+      // consumer can honour it rather than latching the instant a buffer is
+      // queued. Measured, the latch ran about 34 ms ahead of it.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            JNIEnv *e = env();
+            if (e == nullptr || self->cls_ == nullptr) return jsi::Value(0.0);
+            jmethodID due = e->GetStaticMethodID(self->cls_, "pendingDueNs", "()J");
+            if (due == nullptr) {
+              e->ExceptionClear();
+              return jsi::Value(0.0);
+            }
+            return jsi::Value(
+                static_cast<double>(e->CallStaticLongMethod(self->cls_, due)));
+          });
+    }
+
+    if (prop == "pendingDepth") {
+      // How many frames are outstanding, from the producer's own counters.
+      // Needed for the strengthened invariant: depth above zero for the
+      // consumer's generation must make the consumer's own query return true,
+      // and if it does not, the two are holding different objects.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            JNIEnv *e = env();
+            if (e == nullptr || self->cls_ == nullptr) return jsi::Value(0.0);
+            jmethodID getter =
+                e->GetStaticMethodID(self->cls_, "getPendingDepth", "()J");
+            if (getter == nullptr) {
+              e->ExceptionClear();
+              return jsi::Value(0.0);
+            }
+            return jsi::Value(
+                static_cast<double>(e->CallStaticLongMethod(self->cls_, getter)));
+          });
+    }
+
+    if (prop == "pendingGeneration") {
+      // Which generation the counters are keeping for. Pending for 2 while the
+      // worklet asks about 3 is a different fault from nothing having arrived.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            JNIEnv *e = env();
+            if (e == nullptr || self->cls_ == nullptr) return jsi::Value(0.0);
+            jmethodID getter = e->GetStaticMethodID(
+                self->cls_, "getPendingGeneration", "()I");
+            if (getter == nullptr) {
+              e->ExceptionClear();
+              return jsi::Value(0.0);
+            }
+            return jsi::Value(static_cast<double>(
+                e->CallStaticIntMethod(self->cls_, getter)));
+          });
+    }
+
+    if (prop == "generation") {
+      // The generation this instance registered under, or 0 before `create`.
+      // Read-only: nothing here decides anything, it only lets a caller say
+      // which surface it means.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            return jsi::Value(static_cast<double>(self->generation_.load()));
+          });
+    }
+
+    if (prop == "alive") {
+      // Whether this instance still holds a SurfaceTexture. False before
+      // `create` and after `release`, which is what lets a host reuse a live
+      // surface instead of building a second one on every foreground.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            return jsi::Value(self->surfaceTexture_ != nullptr);
+          });
+    }
+
+    if (prop == "textureId") {
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            return jsi::Value(static_cast<double>(self->texture_));
+          });
+    }
+
+    if (prop == "update") {
+      // The whole per-frame path. Returns the frame's presentation time in
+      // microseconds, or -1 when nothing new has arrived — the caller then
+      // holds what is already shown rather than rewrapping for no reason.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            JNIEnv *e = env();
+            if (e == nullptr || self->surfaceTexture_ == nullptr) {
+              return jsi::Value(-1.0);
+            }
+            // Asked as a level, not read as an edge.
+            //
+            // The old path did `getAndSet(false)` on a Java AtomicBoolean: it
+            // *consumed* the signal to test it, so a tick that then failed to
+            // latch had to put it back by hand, and a consumer that was disarmed
+            // when the edge arrived never saw it at all. A frame that turned up
+            // while the app was in the system picker was therefore announced to
+            // nobody, and a paused player produces no second announcement — the
+            // preview stayed black with every producer counter healthy.
+            //
+            // `hasPendingFrame` compares two monotonic counters, so asking does
+            // not consume, and the answer is the same however long ago the frame
+            // arrived or who was listening. `VideoSurface.update` advances the
+            // consumed counter itself, and only on a latch that really happened.
+            jmethodID hasPending = e->GetStaticMethodID(self->cls_,
+                                                        "hasPendingFrame", "(I)Z");
+            if (e->CallStaticBooleanMethod(self->cls_, hasPending,
+                                           self->generation_.load()) == JNI_FALSE) {
+              return jsi::Value(-1.0);
+            }
+
+            jmethodID update = e->GetStaticMethodID(
+                self->cls_, "update", "(Landroid/graphics/SurfaceTexture;I)Z");
+            const jboolean latched = e->CallStaticBooleanMethod(
+                self->cls_, update, self->surfaceTexture_, self->generation_.load());
+            if (e->ExceptionCheck()) {
+              e->ExceptionClear();
+              return jsi::Value(-1.0);
+            }
+            if (latched == JNI_FALSE) {
+              // Nothing to put back: a failed latch consumed nothing, so the
+              // level is still raised and the next tick retries by itself.
+              return jsi::Value(-1.0);
+            }
+
+            jmethodID transform = e->GetStaticMethodID(
+                self->cls_, "transform",
+                "(Landroid/graphics/SurfaceTexture;)[F");
+            auto array = (jfloatArray)e->CallStaticObjectMethod(
+                self->cls_, transform, self->surfaceTexture_);
+            jfloat values[16];
+            e->GetFloatArrayRegion(array, 0, 16, values);
+            self->sx_ = values[0];
+            self->sy_ = values[5];
+            self->tx_ = values[12];
+            self->ty_ = values[13];
+            // The whole matrix, not just the axis-aligned terms. A rotated
+            // source puts its rotation in [1] and [4] and leaves [0] and [5]
+            // at zero, so a transform reading only the diagonal cannot tell a
+            // rotation from an identity — and silently renders the wrong thing.
+            for (int i = 0; i < 16; i++) self->matrix_[i] = values[i];
+            e->DeleteLocalRef(array);
+
+            // One canonical sample, completed where the frame is consumed.
+            // Nothing here recomputes anything: the readout and the
+            // percentiles both read these fields, matched by sample id.
+            struct timespec now;
+            clock_gettime(CLOCK_MONOTONIC, &now);
+            const int64_t consumedNs =
+                static_cast<int64_t>(now.tv_sec) * 1000000000LL + now.tv_nsec;
+
+            /*
+              What the texture actually holds, read after the acquisition.
+
+              The metadata deque is coalesced to its newest entry on every
+              availability callback, so "the sample we kept" and "the buffer
+              `updateTexImage` took" are only assumed to be the same frame.
+              `getTimestamp` is the acquired buffer's own presentation time and
+              is the one thing that can check it.
+            */
+            jmethodID stamp = e->GetStaticMethodID(
+                self->cls_, "timestamp", "(Landroid/graphics/SurfaceTexture;)J");
+            const jlong texturePtsNs =
+                stamp == nullptr
+                    ? 0
+                    : e->CallStaticLongMethod(self->cls_, stamp, self->surfaceTexture_);
+            if (e->ExceptionCheck()) e->ExceptionClear();
+
+            jclass clock = e->FindClass("dev/pictor/video/FrameClock");
+            jmethodID take = e->GetStaticMethodID(clock, "take", "(JJ)[J");
+            auto paired = (jlongArray)e->CallStaticObjectMethod(
+                clock, take, (jlong)consumedNs, texturePtsNs);
+            if (paired == nullptr) {
+              self->ptsUs_ = -1;
+              return jsi::Value(-1.0);
+            }
+            e->GetLongArrayRegion(paired, 0, 17, self->sample_);
+            e->DeleteLocalRef(paired);
+            self->ptsUs_ = self->sample_[2];
+            return jsi::Value(static_cast<double>(self->ptsUs_));
+          });
+    }
+
+    // One accessor over the canonical sample. Field indices mirror
+    // FrameClock.Field; nothing is derived here, so a reader cannot disagree
+    // with the percentiles about what a frame's timing was.
+    if (prop == "field") {
+      return jsi::Function::createFromHostFunction(
+          rt, name, 1,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *args,
+                 size_t count) -> jsi::Value {
+            if (count == 0) return jsi::Value(0.0);
+            const int index = static_cast<int>(args[0].asNumber());
+            if (index < 0 || index >= 17) return jsi::Value(0.0);
+            return jsi::Value(static_cast<double>(self->sample_[index]));
+          });
+    }
+
+    if (prop == "matrix") {
+      // The full 4x4, for diagnosing orientation. Diagnostics only: the render
+      // path reads the individual terms and never allocates per frame.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            jsi::Array out(rt, 16);
+            for (size_t i = 0; i < 16; i++) {
+              out.setValueAtIndex(rt, i, jsi::Value(static_cast<double>(self->matrix_[i])));
+            }
+            return out;
+          });
+    }
+
+    // `rx`/`ry` are the off-diagonal terms, m[1] and m[4]. A quarter turn puts
+    // the whole rotation there and leaves the diagonal at zero, so a renderer
+    // that reads only sx/sy/tx/ty cannot see it and silently draws unrotated.
+    if (prop == "sx" || prop == "sy" || prop == "tx" || prop == "ty" ||
+        prop == "rx" || prop == "ry") {
+      const char axis = prop[0];
+      const char which = prop[1];
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self, axis, which](jsi::Runtime &rt, const jsi::Value &,
+                              const jsi::Value *, size_t) -> jsi::Value {
+            const float value =
+                axis == 'r' ? (which == 'x' ? self->matrix_[1] : self->matrix_[4])
+                : axis == 's' ? (which == 'x' ? self->sx_ : self->sy_)
+                              : (which == 'x' ? self->tx_ : self->ty_);
+            return jsi::Value(static_cast<double>(value));
+          });
+    }
+
+    if (prop == "releaseGeneration") {
+      // Release, but only if this instance still holds the generation named.
+      //
+      // A superseded create that succeeded has to free what it made, and by the
+      // time it can it may no longer be the current surface — releasing "the
+      // current one" would then tear down its replacement. Naming the
+      // generation makes that impossible: a late attempt either frees its own
+      // surface or does nothing.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 1,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *args,
+                 size_t count) -> jsi::Value {
+            const int wanted = count > 0 ? (int)args[0].asNumber() : 0;
+            if (wanted == 0 || wanted != (int)self->generation_.load()) {
+              return jsi::Value(false);
+            }
+            JNIEnv *e = env();
+            if (e == nullptr || self->surfaceTexture_ == nullptr) {
+              return jsi::Value(false);
+            }
+            // The same teardown the other two paths run. Three copies of this
+            // is how `create` came to be missing it. The class ref stays: this
+            // host object is still in use after a superseded surface retires.
+            retire(self, e, false);
+            return jsi::Value(true);
+          });
+    }
+
+    if (prop == "release") {
+      // Order matters and is explicit: Surface, SurfaceTexture, then the GL
+      // texture, on the thread whose context owns it. The same teardown
+      // `create` runs before it allocates, so a replaced surface and a released
+      // one free exactly the same things.
+      return jsi::Function::createFromHostFunction(
+          rt, name, 0,
+          [self](jsi::Runtime &rt, const jsi::Value &, const jsi::Value *,
+                 size_t) -> jsi::Value {
+            JNIEnv *e = env();
+            const bool deleted = retire(self, e, true);
+            if (e != nullptr && self->clockCls_ != nullptr) {
+              e->DeleteGlobalRef(self->clockCls_);
+              self->clockCls_ = nullptr;
+              self->take_ = nullptr;
+            }
+            return jsi::Value(deleted);
+          });
+    }
+
+    return jsi::Value::undefined();
+  }
+
+private:
+  /**
+   * Free everything one surface generation owns, in order.
+   *
+   * The Surface and SurfaceTexture first, then the GL texture, then the class
+   * ref that was needed to make the call — each on the thread that owns it,
+   * with an attached JNIEnv and a current EGL context. Shared by `release` and
+   * by `create`, so replacing a surface and releasing one free exactly the same
+   * set; they diverged once, and the half `create` skipped was all of it.
+   *
+   * Safe to call on an empty slot: every field is checked and cleared, so a
+   * second call frees nothing rather than freeing twice.
+   *
+   * Returns whether a GL texture was actually deleted.
+   */
+  static bool retire(SurfaceHostObject *self, JNIEnv *e, bool dropClass) {
+    if (e != nullptr && self->surfaceTexture_ != nullptr) {
+      jmethodID release = e->GetStaticMethodID(
+          self->cls_, "release",
+          "(Landroid/graphics/SurfaceTexture;Landroid/view/Surface;I)V");
+      e->CallStaticVoidMethod(self->cls_, release, self->surfaceTexture_,
+                              self->surface_, self->generation_.load());
+      e->DeleteGlobalRef(self->surfaceTexture_);
+      e->DeleteGlobalRef(self->surface_);
+      self->surfaceTexture_ = nullptr;
+      self->surface_ = nullptr;
+      // Counted only when something was actually freed, so `live` is a true count
+      // rather than a count of calls. A no-op retire must not read as a free.
+      self->retires_++;
+    }
+    if (e != nullptr && self->flag_ != nullptr) {
+      // The listener watching the retired SurfaceTexture goes with it; leaving
+      // the ref alive kept a callback pointed at a texture nobody could read.
+      e->DeleteGlobalRef(self->flag_);
+      self->flag_ = nullptr;
+    }
+    bool deleted = false;
+    if (self->texture_ != 0 && eglGetCurrentContext() != EGL_NO_CONTEXT) {
+      glDeleteTextures(1, &self->texture_);
+      deleted = glGetError() == GL_NO_ERROR;
+      self->texture_ = 0;
+    }
+    /*
+      The class ref goes only when nothing will ask for it again.
+
+      `create` replaces it on the next line and `release` is the end of the
+      object, so both drop it. `releaseGeneration` retires a superseded surface
+      while the host object stays in use, and every other query on it guards on
+      a null class by returning a default — dropping it there would turn a
+      surface swap into a stretch of silent zeroes.
+    */
+    if (dropClass && e != nullptr && self->cls_ != nullptr) {
+      e->DeleteGlobalRef(self->cls_);
+      self->cls_ = nullptr;
+    }
+    self->generation_.store(0);
+    return deleted;
+  }
+
+  /**
+   * The slot's mutable target, guarded because two runtimes read it.
+   *
+   * This object is created once, at install, **before any surface exists** and
+   * before anything captures it. `create` fills the fields in place; retirement
+   * clears them, and only for its own generation. So a consumer captures this
+   * object once and every call resolves through whatever the slot is pointing at
+   * now — there is nothing replaceable to capture, which is the whole point.
+   *
+   * `generation_` is atomic because the JS thread reads it (`generation()`)
+   * while the UI runtime writes it (`create`, `releaseGeneration`). The JNI
+   * handles beside it are only ever touched on the UI runtime, where the GL
+   * context lives.
+   */
+  std::mutex slot_;
+  GLuint texture_ = 0;
+  /** Surfaces made, and surfaces actually freed. @see surfaceCounters */
+  long creates_ = 0;
+  long retires_ = 0;
+  /** Raised by the frame listener, cleared when the UI runtime consumes it. */
+  jobject flag_ = nullptr;
+  float sx_ = 1.f, sy_ = 1.f, tx_ = 0.f, ty_ = 0.f;
+  /** Clip time of the frame on screen, and how late it got there. */
+  int64_t ptsUs_ = -1;
+  /** The canonical sample for the frame on screen. See FrameClock.Field. */
+  jlong sample_[17] = {0};
+  jfloat matrix_[16] = {0};
+  /** The surface generation this instance registered under. */
+  std::atomic<jint> generation_{0};
+  jobject surfaceTexture_ = nullptr;
+  jobject surface_ = nullptr;
+  jclass cls_ = nullptr;
+  /** Held across frames so the per-frame path never calls `FindClass`. */
+  jclass clockCls_ = nullptr;
+  jmethodID take_ = nullptr;
+};
+
+} // namespace
+} // namespace pictor
+
+extern "C" JNIEXPORT jboolean JNICALL
+Java_dev_pictor_video_PictorVideoModule_nativeInstallVideoSurface(
+    JNIEnv *e, jclass, jlong runtimePtr) {
+  auto *runtime = reinterpret_cast<jsi::Runtime *>(runtimePtr);
+  if (runtime == nullptr) return JNI_FALSE;
+  e->GetJavaVM(&pictor::g_vm);
+
+  // Idempotent, and that is the whole point.
+  //
+  // This used to construct a new `SurfaceHostObject` on every call and
+  // overwrite the global with it. A caller that installed once during render
+  // and again from an effect — which is exactly what the hook did — ended up
+  // with two objects: the consumer captured the first, `create` ran on the
+  // second, and the two reported different generations forever. Neither was
+  // wrong about itself. Reinstalling is not a way to obtain the slot; asking
+  // for it is.
+  auto existing =
+      runtime->global().getProperty(*runtime, "__pictorVideoSurface");
+  if (existing.isObject()) return JNI_TRUE;
+
+  pictor::g_factoryCount.fetch_add(1);
+  runtime->global().setProperty(
+      *runtime, "__pictorVideoSurface",
+      jsi::Object::createFromHostObject(
+          *runtime, std::make_shared<pictor::SurfaceHostObject>()));
+  // Installed once and never replaced. A consumer that captures this object at
+  // any point — including before a surface has ever been created — holds a
+  // stable slot, not a snapshot, so its calls resolve through whatever target
+  // the slot has *now*. Replacing this object on surface creation is what would
+  // put a consumer back in the position of holding something stale.
+  return JNI_TRUE;
+}