react-native-image-stitcher 0.8.0 → 0.10.0

package/cpp/stitcher_worklet_registry.hpp

@@ -123,6 +123,16 @@ class StitcherWorkletRegistry {
   /// exposed through the JSI surface.
   void _resetForTests();
 
+  /// Test-only — install a pre-constructed entry directly, bypassing
+  /// the JSI runtime path.  Mirrors `install` but accepts an already-
+  /// constructed (or null) `WorkletInvoker` so tests can exercise
+  /// `count`/`snapshot`/`uninstall`/thread-safety without standing
+  /// up a full JSI runtime + worklets-core stack.  Tests typically
+  /// pass `nullptr` — the registry never dereferences the pointer.
+  /// Not exposed through the JSI surface.
+  std::string _installEntryForTests(
+      std::shared_ptr<RNWorklet::WorkletInvoker> invoker);
+
  private:
   StitcherWorkletRegistry() = default;
   StitcherWorkletRegistry(const StitcherWorkletRegistry&) = delete;

package/cpp/tests/CMakeLists.txt

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# cpp/tests/CMakeLists.txt — v0.10.0 audit #9A
+#
+# Standalone Google Test runner for the shared C++ port under `cpp/`.
+# Build + run via:
+#
+#     cmake -S cpp/tests -B build/cpp-tests
+#     cmake --build build/cpp-tests
+#     (cd build/cpp-tests && ctest --output-on-failure)
+#
+# Or, from the repo root: `scripts/run-cpp-tests.sh`.
+#
+# What this DOES test (v0.10.0 scope):
+#   - Pure-C++ types in cpp/: `Pose`, `PlaneTransform`,
+#     `StitcherFrameData`, `PixelBufferReader` interface contract.
+#   - `StitcherWorkletRegistry` lifecycle (count, snapshot, uninstall,
+#     thread-safety) — compiled against JSI/worklets-core stubs under
+#     `cpp/tests/stubs/`.  See `stubs/jsi/jsi.h` for the strategy.
+#
+# What this DOES NOT test yet (deferred to v0.11.0+):
+#   - `KeyframeGate` — depends on OpenCV.  Will need an OpenCV-aware
+#     CMake config (link the same opencv_world the prod build uses).
+#   - JSI host-object dispatch — needs a real Hermes runtime.
+#   - Anything in `stitcher.cpp` (uses OpenCV stitching pipeline).
+
+cmake_minimum_required(VERSION 3.20)
+project(stitcher_cpp_tests CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+# Must precede `gtest_discover_tests` — without this the discovered
+# cases aren't registered into a CTestTestfile.cmake at this directory
+# level, and `ctest` reports "No tests were found".
+enable_testing()
+
+# Fetch GoogleTest pinned to v1.14.0.  Pin matches what the AOSP /
+# Android NDK test ecosystem uses today; bumps should be deliberate.
+include(FetchContent)
+FetchContent_Declare(
+  googletest
+  GIT_REPOSITORY https://github.com/google/googletest.git
+  GIT_TAG        v1.14.0
+)
+# Prevent GoogleTest from overriding our compiler/linker options
+# (Windows-only quirk; harmless on macOS/Linux).
+set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+FetchContent_MakeAvailable(googletest)
+
+# ─────────────────────────────────────────────────────────────────────
+# Include paths
+# ─────────────────────────────────────────────────────────────────────
+# Order matters: stubs/ comes FIRST so `#include <jsi/jsi.h>` and
+# `#include <react-native-worklets-core/WKTJsiWorklet.h>` resolve to
+# the test-only stubs before any system header.  The production cpp/
+# directory comes after so retailens:: headers (e.g. ar_frame_pose.h,
+# stitcher_frame_data.hpp) are found as the production code expects.
+include_directories(
+  ${CMAKE_CURRENT_SOURCE_DIR}/stubs
+  ${CMAKE_CURRENT_SOURCE_DIR}/..
+)
+
+# ─────────────────────────────────────────────────────────────────────
+# Test executable
+# ─────────────────────────────────────────────────────────────────────
+add_executable(stitcher_cpp_tests
+  # Production sources under test (only those whose deps we can satisfy
+  # without OpenCV / a real JSI runtime).
+  ${CMAKE_CURRENT_SOURCE_DIR}/../stitcher_worklet_registry.cpp
+
+  # Test sources.
+  ${CMAKE_CURRENT_SOURCE_DIR}/pose_test.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/stitcher_frame_data_test.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/stitcher_worklet_registry_test.cpp
+)
+
+target_link_libraries(stitcher_cpp_tests
+  PRIVATE
+    GTest::gtest_main
+)
+
+# Treat warnings as errors in the test build to catch the kind of
+# silent regressions (unused variables, signed/unsigned comparisons,
+# narrowing conversions) that production cross-compilation flags would
+# otherwise suppress.
+if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
+  target_compile_options(stitcher_cpp_tests PRIVATE
+    -Wall -Wextra -Wpedantic -Werror
+  )
+endif()
+
+# Register with CTest so `ctest --output-on-failure` picks up the
+# individual TEST() cases (gtest_discover_tests scans the binary at
+# build time, no manual ADD_TEST per case).
+include(GoogleTest)
+gtest_discover_tests(stitcher_cpp_tests)

package/cpp/tests/README.md

@@ -0,0 +1,86 @@
+# `cpp/tests/` — shared C++ unit test suite
+
+v0.10.0 audit `#9A` introduced this directory to give the cross-platform
+shared C++ code under `cpp/` a Google Test harness that runs on the
+developer's host machine (not on a device or emulator).  Pairs with the
+Android-side JUnit suite added in `#11A` (see
+`android/src/test/java/io/imagestitcher/rn/`).
+
+## Run
+
+```sh
+scripts/run-cpp-tests.sh           # configure + build + ctest
+scripts/run-cpp-tests.sh --clean   # nuke build/cpp-tests/ first
+```
+
+Requires `cmake ≥ 3.20` and a C++17 toolchain (the macOS AppleClang
+shipped with Xcode 14+ is fine; Linux GCC 9+ / Clang 10+ also work).
+
+Build artefacts land under `build/cpp-tests/` (gitignored).  Google
+Test is fetched at configure time via CMake `FetchContent` pinned to
+`v1.14.0`; no system-wide install required.
+
+## Scope (v0.10.0)
+
+Covered:
+
+- `Pose`, `PlaneTransform` (POD layout / size / field offsets — pinned
+  to the cross-platform marshalling contract documented in
+  `cpp/ar_frame_pose.h`).
+- `StitcherFrameData` (default-construction invariants the JSI host
+  object's `get()` dispatch relies on).
+- `PixelBufferReader` interface contract (clipping behaviour of
+  `copyTo` — validated via the `FakePixelBufferReader` test helper).
+- `StitcherWorkletRegistry` storage lifecycle: shared-instance,
+  install/uninstall/count/snapshot, snapshot independence, concurrent
+  installs yield unique IDs (16 threads × 32 installs).
+
+Not yet covered (intentional deferrals):
+
+- `KeyframeGate` (`cpp/keyframe_gate.cpp`) — depends on OpenCV
+  (`opencv2/imgproc.hpp`, `opencv2/video.hpp` for `calcOpticalFlowPyrLK`).
+  Linking the production OpenCV xcframework / Android SDK into the
+  host-side test target would balloon CI time and disk usage; the
+  alternative is to land a stripped-down `libopencv-core` host build
+  just for tests.  Deferred — comes with the v0.11.0 cross-platform
+  parity suite (`#2C`).
+- `stitcher.cpp` — uses the full OpenCV stitching pipeline; same
+  reason as above.
+- JSI host-object dispatch (`stitcher_frame_jsi.cpp`,
+  `stitcher_proxy_jsi.cpp`, `stitcher_worklet_dispatch.cpp`) — needs
+  a real Hermes runtime.  The `StitcherWorkletRegistry` tests sidestep
+  this via the `_installEntryForTests` seam + JSI stubs under
+  `stubs/`; the JSI dispatch paths can't be similarly stubbed because
+  they actively call into the runtime.
+
+## How the JSI-dependent registry tests work without a real JSI
+
+`stitcher_worklet_registry.cpp` `#include`s
+`<jsi/jsi.h>` and `<react-native-worklets-core/WKTJsiWorklet.h>` to
+construct `WorkletInvoker` instances from a real JS runtime.  The test
+target sidesteps both by:
+
+1. Putting `cpp/tests/stubs/` first on the compiler's include path so
+   `#include <jsi/jsi.h>` resolves to `stubs/jsi/jsi.h` (which declares
+   `facebook::jsi::Runtime` / `Value` as empty classes — enough for
+   the registry's reference-only usage), and
+   `#include <react-native-worklets-core/WKTJsiWorklet.h>` resolves to
+   `stubs/react-native-worklets-core/WKTJsiWorklet.h` (which declares
+   `RNWorklet::WorkletInvoker` with a no-op constructor).
+2. Calling `_installEntryForTests(nullptr)` instead of the production
+   `install(runtime, value)` path.  The registry stores the
+   `shared_ptr<WorkletInvoker>` but never dereferences it (it only
+   hands it back via `snapshot`), so `nullptr` is safe.
+
+The stubs live exclusively under `cpp/tests/stubs/`; production
+builds never see them.  See `stubs/jsi/jsi.h`'s docstring for the
+guard-rails.
+
+## When NOT to add a test here
+
+- If the test needs a real JSI runtime, real OpenCV operations, or
+  real-device sensor data, it belongs in `android/src/androidTest/`
+  (instrumented), the iOS Swift test target, or the v0.11.0 parity
+  harness — NOT here.
+- If the test verifies TypeScript/JS-side behaviour, it belongs under
+  `src/**/__tests__/` (Jest).

package/cpp/tests/pose_test.cpp

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// pose_test.cpp — v0.10.0 audit #9A
+//
+// Layout / size invariants for the cross-platform POD structs that
+// marshal AR-frame pose data between Swift/Kotlin and shared C++.
+// The Pose / PlaneTransform structs MUST stay binary-compatible
+// across iOS (Swift → C++) and Android (Kotlin → JNI → C++) — any
+// silent field reorder, padding shift, or size change would diverge
+// gate decisions between platforms.
+//
+// These are pinned to the contract in `cpp/ar_frame_pose.h`'s
+// docstring; if the struct shape evolves intentionally, update both
+// the docstring and these tests in the same commit.
+
+#include "ar_frame_pose.h"
+
+#include <gtest/gtest.h>
+
+#include <cstddef>
+#include <type_traits>
+
+using retailens::Pose;
+using retailens::PlaneTransform;
+
+TEST(PoseLayoutTest, IsStandardLayoutPod) {
+  // Required for `memcpy` marshalling and for the iOS Obj-C++ /
+  // Android JNI bridges to write into the struct directly.
+  EXPECT_TRUE(std::is_standard_layout<Pose>::value);
+  EXPECT_TRUE(std::is_trivially_copyable<Pose>::value);
+}
+
+TEST(PoseLayoutTest, SizeMatchesExpectedFields) {
+  // 11 floats (tx, ty, tz, qx, qy, qz, qw, fx, fy, cx, cy) + 2 int32_t
+  // (imageWidth, imageHeight) = 11*4 + 2*4 = 52 bytes.  No padding
+  // expected: every field is 4-byte aligned and the struct contains
+  // only 4-byte primitives.
+  EXPECT_EQ(sizeof(Pose), static_cast<std::size_t>(11 * 4 + 2 * 4));
+}
+
+TEST(PoseLayoutTest, FieldOrderMatchesContract) {
+  // Translation comes before rotation; rotation before intrinsics;
+  // intrinsics before image dimensions.  Swift / Kotlin marshallers
+  // assume this order — flipping any pair silently breaks the
+  // memcpy-based bridge.
+  EXPECT_EQ(offsetof(Pose, tx), 0u);
+  EXPECT_EQ(offsetof(Pose, ty), sizeof(float) * 1);
+  EXPECT_EQ(offsetof(Pose, tz), sizeof(float) * 2);
+  EXPECT_EQ(offsetof(Pose, qx), sizeof(float) * 3);
+  EXPECT_EQ(offsetof(Pose, qy), sizeof(float) * 4);
+  EXPECT_EQ(offsetof(Pose, qz), sizeof(float) * 5);
+  EXPECT_EQ(offsetof(Pose, qw), sizeof(float) * 6);
+  EXPECT_EQ(offsetof(Pose, fx), sizeof(float) * 7);
+  EXPECT_EQ(offsetof(Pose, fy), sizeof(float) * 8);
+  EXPECT_EQ(offsetof(Pose, cx), sizeof(float) * 9);
+  EXPECT_EQ(offsetof(Pose, cy), sizeof(float) * 10);
+  EXPECT_EQ(offsetof(Pose, imageWidth), sizeof(float) * 11);
+  EXPECT_EQ(offsetof(Pose, imageHeight),
+            sizeof(float) * 11 + sizeof(int32_t));
+}
+
+TEST(PlaneTransformLayoutTest, IsStandardLayoutPod) {
+  EXPECT_TRUE(std::is_standard_layout<PlaneTransform>::value);
+  EXPECT_TRUE(std::is_trivially_copyable<PlaneTransform>::value);
+}
+
+TEST(PlaneTransformLayoutTest, SixteenFloatsContiguous) {
+  // The `m[16]` array MUST be a contiguous 64-byte block — both
+  // bridges call `memcpy(planeTransform.m, source, 64)`.  No leading
+  // padding, no field reorder (there's only one field, but pinning the
+  // size catches any accidental wrapper/struct change).
+  EXPECT_EQ(sizeof(PlaneTransform), static_cast<std::size_t>(16 * 4));
+  EXPECT_EQ(offsetof(PlaneTransform, m), 0u);
+}

package/cpp/tests/stitcher_frame_data_test.cpp

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_frame_data_test.cpp — v0.10.0 audit #9A
+//
+// Sanity coverage for the `StitcherFrameData` POD payload + the
+// `PixelBufferReader` interface contract.  The shared C++
+// `StitcherFrameData` is constructed by both the iOS Obj-C++ side
+// (`StitcherFrameHostObject.mm`) and the Android JNI side
+// (`stitcher_frame_jni.cpp`); these tests pin the default-construction
+// invariants both sides depend on (e.g. `hasTranslation=false`,
+// `qw=1.0`).
+//
+// The `PixelBufferReader` tests use a fake-buffer implementation
+// (`FakePixelBufferReader`) to validate the `copyTo` clipping
+// behaviour the docstring promises.
+
+#include "stitcher_frame_data.hpp"
+
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <cstring>
+#include <memory>
+#include <vector>
+
+using retailens::PixelBufferReader;
+using retailens::StitcherFrameData;
+
+namespace {
+
+/// Minimal fake reader — backs a fixed byte vector.  Used by the
+/// `PixelBufferReader` contract tests below to verify
+/// `copyTo` clips at the smaller of (maxBytes, byteSize).
+class FakePixelBufferReader : public PixelBufferReader {
+ public:
+  explicit FakePixelBufferReader(std::vector<uint8_t> bytes)
+      : _bytes(std::move(bytes)) {}
+
+  std::size_t byteSize() const override { return _bytes.size(); }
+
+  std::size_t copyTo(uint8_t* dst, std::size_t maxBytes) override {
+    const std::size_t n =
+        maxBytes < _bytes.size() ? maxBytes : _bytes.size();
+    std::memcpy(dst, _bytes.data(), n);
+    return n;
+  }
+
+ private:
+  std::vector<uint8_t> _bytes;
+};
+
+}  // namespace
+
+// ─── StitcherFrameData default-construction invariants ─────────────
+
+TEST(StitcherFrameDataTest, DefaultsAreSafeForJSIDispatch) {
+  // The JSI host object's `get()` dispatch keys off these defaults to
+  // expose `undefined` for unset fields.  In particular:
+  //   - `hasTranslation == false`  →  pose.translation === undefined
+  //   - `arTrackingState.empty()`  →  arTrackingState === undefined
+  //   - `qw == 1.0` with rest zero →  identity rotation (safe default
+  //     for non-AR mode where rotation is unknown)
+  StitcherFrameData d;
+  EXPECT_EQ(d.width, 0);
+  EXPECT_EQ(d.height, 0);
+  EXPECT_TRUE(d.source.empty());
+  EXPECT_TRUE(d.pixelFormat.empty());
+  EXPECT_TRUE(d.orientation.empty());
+  EXPECT_DOUBLE_EQ(d.timestampNs, 0.0);
+  EXPECT_DOUBLE_EQ(d.qx, 0.0);
+  EXPECT_DOUBLE_EQ(d.qy, 0.0);
+  EXPECT_DOUBLE_EQ(d.qz, 0.0);
+  EXPECT_DOUBLE_EQ(d.qw, 1.0);  // identity rotation
+  EXPECT_DOUBLE_EQ(d.tx, 0.0);
+  EXPECT_DOUBLE_EQ(d.ty, 0.0);
+  EXPECT_DOUBLE_EQ(d.tz, 0.0);
+  EXPECT_FALSE(d.hasTranslation);
+  EXPECT_TRUE(d.arTrackingState.empty());
+  EXPECT_EQ(d.pixelReader, nullptr);
+}
+
+TEST(StitcherFrameDataTest, IsCopyable) {
+  // `StitcherFrameData` is documented as "value-typed (cheap to copy;
+  // ~100 bytes)".  Copy needs to deep-copy the strings + bump the
+  // pixelReader shared_ptr refcount.
+  StitcherFrameData a;
+  a.source = "ar";
+  a.width = 1920;
+  a.height = 1080;
+  a.pixelReader = std::make_shared<FakePixelBufferReader>(
+      std::vector<uint8_t>{1, 2, 3});
+
+  StitcherFrameData b = a;
+  EXPECT_EQ(b.source, "ar");
+  EXPECT_EQ(b.width, 1920);
+  EXPECT_EQ(b.height, 1080);
+  ASSERT_NE(b.pixelReader, nullptr);
+  EXPECT_EQ(b.pixelReader.use_count(), 2);  // both a and b hold a ref
+  EXPECT_EQ(b.pixelReader->byteSize(), 3u);
+}
+
+// ─── PixelBufferReader contract ────────────────────────────────────
+
+TEST(PixelBufferReaderTest, CopyToReturnsAllBytesWhenMaxBytesExceedsSize) {
+  FakePixelBufferReader reader({0x11, 0x22, 0x33});
+  uint8_t buf[8] = {0};
+  const std::size_t written = reader.copyTo(buf, sizeof(buf));
+  EXPECT_EQ(written, 3u);
+  EXPECT_EQ(buf[0], 0x11);
+  EXPECT_EQ(buf[1], 0x22);
+  EXPECT_EQ(buf[2], 0x33);
+  EXPECT_EQ(buf[3], 0u);  // untouched tail
+}
+
+TEST(PixelBufferReaderTest, CopyToClipsWhenMaxBytesIsSmaller) {
+  // Contract per stitcher_frame_data.hpp: "Implementations MUST handle
+  // the case where maxBytes < byteSize() (clip silently)."
+  FakePixelBufferReader reader({0xAA, 0xBB, 0xCC, 0xDD});
+  uint8_t buf[2] = {0};
+  const std::size_t written = reader.copyTo(buf, sizeof(buf));
+  EXPECT_EQ(written, 2u);
+  EXPECT_EQ(buf[0], 0xAA);
+  EXPECT_EQ(buf[1], 0xBB);
+}
+
+TEST(PixelBufferReaderTest, CopyToWithZeroMaxBytesReturnsZero) {
+  FakePixelBufferReader reader({0x01, 0x02, 0x03});
+  uint8_t dummy = 0xFF;
+  const std::size_t written = reader.copyTo(&dummy, 0);
+  EXPECT_EQ(written, 0u);
+  EXPECT_EQ(dummy, 0xFF);  // dst untouched when maxBytes == 0
+}

package/cpp/tests/stitcher_worklet_registry_test.cpp

@@ -0,0 +1,195 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// stitcher_worklet_registry_test.cpp — v0.10.0 audit #9A
+//
+// Lifecycle + concurrency coverage for the process-scope native
+// `StitcherWorkletRegistry` introduced in v0.8.0 Phase 4b.  See
+// `cpp/stitcher_worklet_registry.hpp` for the public contract.
+//
+// The registry's production `install(runtime, workletValue)` path
+// constructs an `RNWorklet::WorkletInvoker` from a JSI `Runtime` and
+// `Value`.  Standing up a real worklets-core runtime under gtest would
+// pull in Hermes + JSI + the whole worklets-core library — too heavy
+// for these scope-limited storage tests.  Instead we exercise the
+// equivalent `_installEntryForTests(invoker)` test seam (mirrors
+// `_resetForTests` in pattern) with `nullptr` invokers.  The registry
+// never dereferences the pointer — it only stores the shared_ptr and
+// hands it back via `snapshot` — so nullptr is safe.
+//
+// What this covers (lifting from the production `install`/`uninstall`/
+// `snapshot`/`count` contract):
+//   - shared() returns the same instance across calls
+//   - count/snapshot start empty after _resetForTests
+//   - install assigns monotonically increasing host-N IDs
+//   - count tracks installs / uninstalls
+//   - uninstall of an unknown ID is a no-op (matches JS side)
+//   - snapshot returns an independent copy (mutations after snapshot
+//     don't affect the snapshot's view)
+//   - concurrent installs from many threads serialise correctly and
+//     yield unique IDs (no double-issue under contention)
+
+#include "stitcher_worklet_registry.hpp"
+#include <react-native-worklets-core/WKTJsiWorklet.h>
+
+#include <gtest/gtest.h>
+
+#include <algorithm>
+#include <atomic>
+#include <chrono>
+#include <set>
+#include <string>
+#include <thread>
+#include <vector>
+
+using retailens::StitcherWorkletEntry;
+using retailens::StitcherWorkletRegistry;
+
+namespace {
+
+/// Test fixture — resets the singleton before each test so cases
+/// don't leak state into each other.  Without this every test would
+/// see the cumulative entries from prior tests in the run.
+class StitcherWorkletRegistryTest : public ::testing::Test {
+ protected:
+  void SetUp() override {
+    StitcherWorkletRegistry::shared()._resetForTests();
+  }
+  void TearDown() override {
+    StitcherWorkletRegistry::shared()._resetForTests();
+  }
+};
+
+}  // namespace
+
+TEST_F(StitcherWorkletRegistryTest, SharedReturnsSameInstance) {
+  // The singleton invariant is load-bearing for the JS-side mental
+  // model: `useFrameProcessor` mounts on one component and unmounts
+  // from another but the registry stays.
+  StitcherWorkletRegistry& a = StitcherWorkletRegistry::shared();
+  StitcherWorkletRegistry& b = StitcherWorkletRegistry::shared();
+  EXPECT_EQ(&a, &b);
+}
+
+TEST_F(StitcherWorkletRegistryTest, StartsEmptyAfterReset) {
+  auto& r = StitcherWorkletRegistry::shared();
+  EXPECT_EQ(r.count(), 0u);
+  EXPECT_TRUE(r.snapshot().empty());
+}
+
+TEST_F(StitcherWorkletRegistryTest, InstallAssignsHostPrefixedIncrementingIds) {
+  auto& r = StitcherWorkletRegistry::shared();
+  const std::string id0 = r._installEntryForTests(nullptr);
+  const std::string id1 = r._installEntryForTests(nullptr);
+  const std::string id2 = r._installEntryForTests(nullptr);
+
+  // IDs are "host-N" with N monotonically increasing from 0 after a
+  // reset.  The format is part of the public contract — uninstall
+  // callers store these IDs verbatim.
+  EXPECT_EQ(id0, "host-0");
+  EXPECT_EQ(id1, "host-1");
+  EXPECT_EQ(id2, "host-2");
+  EXPECT_EQ(r.count(), 3u);
+}
+
+TEST_F(StitcherWorkletRegistryTest, UninstallRemovesByIdAndUpdatesCount) {
+  auto& r = StitcherWorkletRegistry::shared();
+  const std::string id0 = r._installEntryForTests(nullptr);
+  const std::string id1 = r._installEntryForTests(nullptr);
+  const std::string id2 = r._installEntryForTests(nullptr);
+  EXPECT_EQ(r.count(), 3u);
+
+  r.uninstall(id1);  // remove the middle entry
+  EXPECT_EQ(r.count(), 2u);
+
+  // Snapshot should contain only id0 and id2, in some order — the
+  // contract doesn't promise insertion order survives uninstall
+  // (the erase-remove pattern is stable in practice but we don't
+  // pin that publicly).
+  const auto snap = r.snapshot();
+  std::vector<std::string> remainingIds;
+  remainingIds.reserve(snap.size());
+  for (const auto& entry : snap) {
+    remainingIds.push_back(entry.id);
+  }
+  std::sort(remainingIds.begin(), remainingIds.end());
+  EXPECT_EQ(remainingIds, (std::vector<std::string>{id0, id2}));
+}
+
+TEST_F(StitcherWorkletRegistryTest, UninstallOfUnknownIdIsNoop) {
+  // Matches the JS-side `StitcherWorkletRegistry.uninstall` semantics
+  // (idempotent, no throw on unknown).  Critical because the JS
+  // useEffect cleanup can fire after an unmount/remount race where the
+  // ID has already been removed.
+  auto& r = StitcherWorkletRegistry::shared();
+  r._installEntryForTests(nullptr);
+  EXPECT_EQ(r.count(), 1u);
+  EXPECT_NO_THROW(r.uninstall("host-does-not-exist"));
+  EXPECT_NO_THROW(r.uninstall(""));
+  EXPECT_EQ(r.count(), 1u);  // existing entry untouched
+}
+
+TEST_F(StitcherWorkletRegistryTest, SnapshotIsIndependentOfFutureMutations) {
+  // Per header docstring: "mutations against the registry after
+  // `snapshot` returns do not affect the snapshot."  This matters for
+  // the AR-session dispatch path, which snapshots and then iterates
+  // without holding the registry lock — concurrent uninstall on the
+  // JS thread must NOT invalidate the snapshot.
+  auto& r = StitcherWorkletRegistry::shared();
+  const std::string id0 = r._installEntryForTests(nullptr);
+  const std::string id1 = r._installEntryForTests(nullptr);
+
+  const auto snap = r.snapshot();
+  ASSERT_EQ(snap.size(), 2u);
+
+  r.uninstall(id0);
+  r.uninstall(id1);
+  EXPECT_EQ(r.count(), 0u);
+
+  // Snapshot still has both entries.
+  EXPECT_EQ(snap.size(), 2u);
+  EXPECT_EQ(snap[0].id, id0);
+  EXPECT_EQ(snap[1].id, id1);
+}
+
+TEST_F(StitcherWorkletRegistryTest, ConcurrentInstallsYieldUniqueIds) {
+  // Many threads racing `_installEntryForTests` simultaneously must
+  // not see duplicate IDs (would indicate the mutex around _nextId is
+  // missing or broken).  This is the per-instance equivalent of
+  // TransferredNV21Test's "only one of N concurrent callers wins"
+  // pattern, adapted for "all N callers succeed but produce distinct
+  // IDs".
+  auto& r = StitcherWorkletRegistry::shared();
+  constexpr int kThreads = 16;
+  constexpr int kPerThread = 32;  // 512 total installs
+
+  std::vector<std::thread> workers;
+  workers.reserve(kThreads);
+  std::vector<std::vector<std::string>> idsPerThread(kThreads);
+
+  std::atomic<bool> go{false};
+  for (int t = 0; t < kThreads; ++t) {
+    workers.emplace_back([&, t]() {
+      while (!go.load(std::memory_order_acquire)) {
+        std::this_thread::yield();
+      }
+      for (int i = 0; i < kPerThread; ++i) {
+        idsPerThread[t].push_back(r._installEntryForTests(nullptr));
+      }
+    });
+  }
+  go.store(true, std::memory_order_release);
+  for (auto& w : workers) w.join();
+
+  // Aggregate every ID issued.  Total count = kThreads * kPerThread;
+  // uniqueness = the set size matches.
+  std::set<std::string> allIds;
+  for (const auto& v : idsPerThread) {
+    for (const auto& id : v) {
+      allIds.insert(id);
+    }
+  }
+  EXPECT_EQ(allIds.size(),
+            static_cast<std::size_t>(kThreads * kPerThread));
+  EXPECT_EQ(r.count(),
+            static_cast<std::size_t>(kThreads * kPerThread));
+}

package/cpp/tests/stubs/jsi/jsi.h

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// jsi.h — TEST-ONLY stub of facebook::jsi types.
+//
+// The real jsi.h ships with React Native and pulls in a large surface
+// area (Runtime, Value, Object, Function, HostObject, HostFunction,
+// Array, ArrayBuffer, PropNameID, …) along with the build infra to
+// link them.  For pure-C++ unit tests that exercise data-structure
+// invariants of code that REFERENCES jsi types but never CALLS into
+// them (e.g. `StitcherWorkletRegistry` storing a `shared_ptr` and
+// forwarding `Runtime&` to a constructor stub), we only need the
+// types to be NAMED so headers compile.
+//
+// Pattern: this stub is placed first on the test target's include
+// path so `#include <jsi/jsi.h>` resolves here instead of to RN's
+// real header.  Production builds NEVER see this file — it lives
+// only under `cpp/tests/stubs/`, which is referenced exclusively by
+// `cpp/tests/CMakeLists.txt`.
+//
+// Tests that need to actually CONSTRUCT or CALL into JSI types should
+// not use this stub — they should run against a real JSI runtime (a
+// future v0.11.0+ test target that links Hermes).
+
+#pragma once
+
+namespace facebook {
+namespace jsi {
+
+class Runtime {};
+class Value {};
+
+}  // namespace jsi
+}  // namespace facebook

package/cpp/tests/stubs/react-native-worklets-core/WKTJsiWorklet.h

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// WKTJsiWorklet.h — TEST-ONLY stub of RNWorklet::WorkletInvoker.
+//
+// `cpp/stitcher_worklet_registry.cpp` constructs a
+// `std::make_shared<RNWorklet::WorkletInvoker>(runtime, value)` inside
+// `install`.  The real WorkletInvoker (from react-native-worklets-core)
+// captures the worklet's source / closure / runtime affinity and is
+// non-trivial to stand up in a unit-test context.
+//
+// This stub provides JUST the symbols needed for the registry to
+// compile and link.  The constructor and destructor are no-ops; calling
+// methods on a stub invoker is undefined behaviour, but the registry
+// itself never does (it only stores the shared_ptr and hands it out
+// via `snapshot`).  Tests construct entries directly via
+// `_installEntryForTests(nullptr)` to avoid even the trivial
+// allocation.
+//
+// See cpp/tests/stubs/jsi/jsi.h for the parallel stub of facebook::jsi.
+
+#pragma once
+
+#include <jsi/jsi.h>
+
+namespace RNWorklet {
+
+class WorkletInvoker {
+ public:
+  WorkletInvoker(facebook::jsi::Runtime& /*runtime*/,
+                 const facebook::jsi::Value& /*workletValue*/) {}
+  ~WorkletInvoker() = default;
+};
+
+}  // namespace RNWorklet

package/dist/camera/useCapture.d.ts

@@ -17,7 +17,7 @@
  *   - This hook does NOT persist captures.  Host apps hand the
  *     returned CaptureResult to their own storage layer (WatermelonDB
  *     insert, Redux dispatch, whatever).
- *   - Video recording lives in useVideoCapture (TODO).
+ *   - Video recording lives in useVideoCapture.
  *
  * The public API is designed to be minimal and replaceable: host apps
  * that prefer the raw vision-camera API can opt out of this hook and