react-native-image-stitcher 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -16,6 +16,228 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] — 2026-05-28
+
+### Added — `useStitcherWorklet` for non-AR composition
+
+Closes the v0.8.0 Phase 5 either-or constraint: hosts that want to
+write their OWN `useFrameProcessor` worklet body can now COMPOSE
+first-party stitching back in with a single `stitcher.call(frame)`
+call, instead of having to choose between their worklet and the
+lib's stitching.
+
+```tsx
+import {
+  Camera, useFrameProcessor, useStitcherWorklet,
+  type StitcherFrame,
+} from 'react-native-image-stitcher';
+
+function MyScreen() {
+  const stitcher = useStitcherWorklet();
+  const fp = useFrameProcessor((frame: StitcherFrame) => {
+    'worklet';
+    hostPreLogic(frame);
+    stitcher.call(frame);   // ← first-party stitching
+    hostPostLogic(frame);
+  }, [stitcher.call]);
+  return <Camera frameProcessor={fp} ... />;
+}
+```
+
+Migrating from v0.10.x is a one-line diff:
+
+```diff
++ const stitcher = useStitcherWorklet();
+  const fp = useFrameProcessor((frame: StitcherFrame) => {
+    'worklet';
++   stitcher.call(frame);   // ← first-party stitching back in
+    hostLogic(frame);
+- }, [hostLogic]);
++ }, [stitcher.call, hostLogic]);
+```
+
+### Changed
+
+- `useFrameProcessorDriver` is now a thin wrapper around
+  `useStitcherWorklet`.  Public API (`start` / `stop` /
+  `isRunning` / `frameProcessor`) is unchanged.  Pose-reset
+  semantics preserved via the new `stitcher.reset()` method which
+  the driver calls internally from `start()` and `stop()`.
+- The gyro subscription that powers pose tracking now lives in
+  `useStitcherWorklet` and runs for the lifetime of the hook
+  (mount → unmount) rather than being tied to the driver's
+  `start()` / `stop()`.  In practice this matches all observed
+  host integrations (capture screens mount `<Camera>` for the
+  duration of capture; idle screens don't).  Battery delta is
+  small (≪1% CPU at 33 ms gyro sampling).
+- `<Camera frameProcessor>` JSDoc rewritten: the "Non-AR mode
+  tradeoff (HONEST)" section is replaced by a "Non-AR mode
+  composition" section that shows the v0.11.0 composition
+  pattern.  The runtime `console.info` text is softened from
+  "your worklet REPLACES first-party stitching, panorama capture
+  will not produce stitched output" to "if you want first-party
+  stitching alongside, call `useStitcherWorklet()` from your
+  worklet body".
+- Example app (`example/App.tsx`) now demonstrates the
+  composition pattern end-to-end: one
+  `useFrameProcessor` body that calls both `stitcher.call(frame)`
+  and the existing 1 Hz host tick log.  `<Camera>` mounts with
+  `frameProcessor={exampleFrameProcessor}` (previously left
+  unwired with an "intentionally unused" comment block).
+- `docs/frame-access-tiers.md` adds a `useStitcherWorklet`
+  reference section + 1-line migration diff.  Softens the
+  "either-or" language in the Tier 3 + AR-vs-non-AR sections.
+
+### Files changed
+- NEW: `src/stitching/useStitcherWorklet.ts`
+- `src/stitching/useFrameProcessorDriver.ts` (refactored thin wrapper)
+- `src/index.ts` (export new hook + types)
+- `src/camera/Camera.tsx` (docstring + console.info softened)
+- `example/App.tsx` (composition demo)
+- `docs/frame-access-tiers.md` (new section + softened wording)
+- `docs/v0.11.0-manual-verification-checklist.md` (Phase 4 human-loop checklist)
+
+### Not touched
+- All native code (`ios/Sources/`, `android/src/main/cpp/`,
+  `android/src/main/java/io/imagestitcher/rn/`) — pure TS refactor.
+- AR-mode dispatch path — already composes natively.
+- `useFrameProcessor` (v0.8.0 public hook) — unchanged.
+
+### Verified
+- JS Jest: **69 / 69 pass**
+- C++ Gtest: **17 / 17 pass**
+- Android JUnit: **6 / 6 pass**
+- iOS build (Debug, generic iOS device): clean
+- Android `:app:assembleDebug`: clean
+- Real-device panorama capture verification deferred to the
+  human-in-the-loop checklist (`docs/v0.11.0-manual-verification-checklist.md`).
+
+## [0.10.0] — 2026-05-28
+
+### Added — v0.10.0 PR A: host-side test infrastructure (`#9A` + `#11A`)
+
+Two parallel test harnesses landed so future tech-debt PRs in the
+v0.10.0 sweep (and beyond) can pin invariants without standing up a
+device build per change.
+
+#### Shared C++ Google Test runner (`#9A`)
+
+- `cpp/tests/CMakeLists.txt` — standalone CMake project that fetches
+  Google Test `v1.14.0` via `FetchContent` and compiles a single
+  `stitcher_cpp_tests` executable.  No system-wide gtest install
+  required.
+- `scripts/run-cpp-tests.sh` — one-shot configure / build / `ctest`
+  driver.  Output lands under gitignored `build/cpp-tests/`.
+- Initial suite (17 cases):
+  - `Pose` / `PlaneTransform` POD layout, size, field-offset
+    invariants (pinned to the cross-platform marshalling contract
+    in `cpp/ar_frame_pose.h`).
+  - `StitcherFrameData` default-construction invariants the JSI
+    host-object `get()` dispatch depends on (e.g. `qw=1.0`,
+    `hasTranslation=false`).
+  - `PixelBufferReader` `copyTo` clipping contract — validated via
+    a `FakePixelBufferReader` test helper.
+  - `StitcherWorkletRegistry` lifecycle: shared-instance, install
+    /uninstall/count/snapshot, snapshot independence from later
+    mutations, concurrent installs (16 threads × 32 each) yield
+    unique IDs without lock contention bugs.
+- New test-only registry seam `_installEntryForTests(invoker)` (in
+  `cpp/stitcher_worklet_registry.{hpp,cpp}`) — mirrors the existing
+  `_resetForTests` pattern.  Bypasses the JSI runtime path so tests
+  don't need Hermes + worklets-core; `nullptr` invokers are safe
+  because the registry never dereferences them.
+- JSI / worklets-core stubs under `cpp/tests/stubs/` let
+  `stitcher_worklet_registry.cpp` compile in the host-side test
+  target without pulling in React Native's JSI headers or the
+  worklets-core library.  Stubs are scoped exclusively to the test
+  include path; production builds never see them.
+- See `cpp/tests/README.md` for the strategy + a list of what's
+  deferred to v0.11.0+ (KeyframeGate / OpenCV-dependent code; JSI
+  host-object dispatch).
+
+#### Android JUnit scaffold (`#11A`)
+
+- `android/build.gradle` — adds `testImplementation
+  "junit:junit:4.13.2"`.  Minimal — only JUnit 4 (matches AGP's
+  default test runner).
+- `android/src/test/java/io/imagestitcher/rn/TransferredNV21Test.kt`
+  — 6 tests covering the v0.10.0 `TransferredNV21` single-use
+  ownership wrapper: constructor empty/non-empty, takeOnce returns
+  the original reference, takeOnce throws on second call, thread-
+  safe single-winner under 16-thread contention, distinct wrappers
+  are independent.
+- Run via `./gradlew :react-native-image-stitcher:testDebugUnitTest`.
+
+Neither suite changes runtime behaviour — both are additive test
+infrastructure.
+
+### Added — v0.10.0 PR B: `refinePanorama` progress events + cleanup audit (`#15A` + `#16C`)
+
+#### `#15A` — phase-milestone progress emit from `refinePanorama`
+
+`refinePanorama` (both the explicit JS `module.refinePanorama(...)` API
+and the hybrid-engine auto-refine path that calls it internally) now
+emits coarse phase events on the existing `IncrementalStateUpdate`
+device-event channel.  Five stages cover one refine lifetime:
+
+| Stage         | `refineProgress` | When                                 |
+| ------------- | ---------------- | ------------------------------------ |
+| `validating`  | 0.05             | start of method, before any I/O      |
+| `stitching`   | 0.10             | OpenCV stitch in flight              |
+| `writing`     | 0.90             | stitch returned, JPEG written        |
+| `done`        | 1.00             | success — promise about to resolve   |
+| `error`       | 1.00             | failure — `refineError` is set       |
+
+`refineStage` carries the stage string; `refineProgress` carries the
+fraction; `refineFrames` reports the input keyframe count; `refineError`
+is populated on the failure path so the host can render a one-line
+failure pill.
+
+Coarse on purpose: OpenCV's `Stitcher` doesn't expose mid-pipeline
+progress, so the `0.10 → 0.90` jump is one opaque step.  JS uses
+`refineStage` for the UI label and `refineProgress` purely for the
+spinner.
+
+Reuses the existing channel (no second listener wiring required).
+Existing JS consumers that don't read the new fields are unaffected.
+
+#### `#16C` — moderate cleanup audit sweep
+
+- `src/camera/useCapture.ts` — removed a stale "`useVideoCapture` (TODO)"
+  reference; the hook has existed since v0.4.
+- `ios/Sources/RNImageStitcher/IncrementalStitcherBridge.swift` — removed
+  a self-flagged "remove this comment after" reference left over from a
+  past PiP investigation.
+- `console.*` audit: every call in `src/` was reviewed; all 13 are
+  legitimate (warn/error for surfaceable failures; `console.info`
+  one-shots that document known tradeoffs).  No removals needed.
+- TODO/FIXME triage: 4 remaining own-code TODOs all reference tracked
+  future work (lens-probe follow-up, shared-stitcher-port-part-2,
+  EXIF writer).  Left in place.
+- `ts-prune`: 3 surface-level orphans (`PanoramaConfirmModal`,
+  `IncrementalStitcherView`, `stitchFrames`) are intentional public
+  deep-import API; not re-exported from `src/index.ts` but
+  documented and consumed by hosts.  Left in place.
+
+No production behaviour changed — these are docstring + dead-comment
+removals only.
+
+### Fixed — v0.10.0 PR B (iOS): refine state events not reaching JS under RN bridgeless interop
+
+Switched `IncrementalStitcherBridge` state-event delivery from
+`RCTEventEmitter.sendEvent` to `bridge.enqueueJSCall("RCTDeviceEventEmitter", "emit", ...)`.
+Root cause: under RN bridgeless interop (RN 0.84), `sendEvent`
+silently no-ops for some event-body shapes even when the bridge is
+non-nil and the listener count is > 0 — refine events with the
+`refineStage` / `refineProgress` / `refineFrames` keys were not
+reaching any JS subscriber while live state events with a smaller
+body shape on the same channel were.  Also defensively
+`removeObserver` before `addObserver` in `init()` so the
+NotificationCenter registration is idempotent if RN re-invokes
+`init()` on the same instance (also observed on bridgeless interop).
+Android is unaffected — Android's bridge already emits via
+`DeviceEventManagerModule.RCTDeviceEventEmitter.emit(...)` directly.
+
 ## [0.9.0] — 2026-05-27
 
 ### Added — layered frame-access helpers
@@ -125,6 +347,30 @@ the Layer 1 + 2 + 3 pipeline working end-to-end on both iPhone
 - New hooks return `useFrameProcessor`-shape objects compatible
   with `<Camera frameProcessor={...}>` (Phase 5 from v0.8.0).
 
+### Known limitations (v0.9.0 — addressed in v0.11.0)
+
+- **Layer 3 `useFrameStream` in AR mode**: the Layer 1
+  `save_frame_as_jpeg` vc Frame Processor plugin expects a vision-
+  camera `Frame` with `.buffer = CMSampleBufferRef`.  In AR mode
+  the worklet receives a `StitcherFrameHostObject` (v0.8.0
+  Phase 4b's JSI host object) without `.buffer` — the plugin call
+  returns `{ok: false, ...}` and `useFrameStream` silently skips
+  the sample.  Hosts needing per-frame native processing in AR
+  mode should use **Layer 2 (`useThrottledFrameProcessor`)** —
+  it works in both modes and is the right primitive for the
+  worklet-native use cases listed in `docs/frame-access-tiers.md`
+  (OCR via Vision/ML Kit, TFLite ML detection, LiDAR depth).
+  AR-mode Layer 3 support tracked in v0.11.0's plan
+  (`docs/plans/2026-05-27-v0.11.0-non-ar-composition.md`) —
+  bundled with `useStitcherWorklet` since both extend the
+  `__stitcherProxy` host-function infrastructure.
+- **Layer 3 `useFrameStream` in non-AR mode**: wiring the host's
+  frameProcessor through `<Camera>` displaces the lib's
+  first-party stitching driver (the documented Phase 5 either-or
+  constraint from v0.8.0).  Non-AR panorama capture won't produce
+  stitched output while a host frameProcessor is wired.  Tracked
+  in v0.11.0 (`useStitcherWorklet` composition).
+
 ### Notes
 
 - Formal SSIM parity gate (Phase 7 of the v0.9.0 plan) was NOT

package/android/build.gradle

@@ -282,6 +282,16 @@ dependencies {
     if (findProject(':react-native-worklets-core') != null) {
         implementation project(':react-native-worklets-core')
     }
+
+    // v0.10.0 audit #11A — Android JUnit test scaffold.  JVM unit
+    // tests for pure-Kotlin data wrappers + algorithm helpers that
+    // don't need an Android device.  Run via
+    // `gradlew :react-native-image-stitcher:test`.
+    //
+    // Kept minimal — only JUnit 4 (matches AGP's default test
+    // runner).  Hosts that want to add their own android-test
+    // dependencies can do so independently.
+    testImplementation "junit:junit:4.13.2"
 }
 
 // Helper from the React Native gradle convention to read host-app

package/android/src/main/java/io/imagestitcher/rn/IncrementalStitcher.kt

@@ -1673,12 +1673,26 @@ class IncrementalStitcher(
     @ReactMethod
     fun refinePanorama(options: ReadableMap, promise: Promise) {
         val framePathsArr = options.getArray("framePaths")
+        val requestedCount = framePathsArr?.size() ?: 0
+        // v0.10.0 #15A — emit `validating` at the very top so JS sees
+        // refine activity even when validation fails fast.  Frames may
+        // be empty here; report whatever the caller asked for.
+        emitRefineProgress(
+            stage = "validating",
+            fraction = 0.05,
+            frames = requestedCount,
+            errorMessage = null,
+        )
         if (framePathsArr == null || framePathsArr.size() < 2) {
-            promise.reject(
-                "incremental-refine-invalid-input",
-                "refinePanorama requires at least 2 framePaths (got " +
-                    "${framePathsArr?.size() ?: 0}).",
+            val msg = "refinePanorama requires at least 2 framePaths (got " +
+                "$requestedCount)."
+            emitRefineProgress(
+                stage = "error",
+                fraction = 1.0,
+                frames = requestedCount,
+                errorMessage = msg,
             )
+            promise.reject("incremental-refine-invalid-input", msg)
             return
         }
         val framePaths = Array(framePathsArr.size()) {
@@ -1686,10 +1700,14 @@ class IncrementalStitcher(
         }
         val outputPathOpt = options.getString("outputPath")
         if (outputPathOpt.isNullOrEmpty()) {
-            promise.reject(
-                "incremental-refine-invalid-input",
-                "refinePanorama requires a non-empty outputPath.",
+            val msg = "refinePanorama requires a non-empty outputPath."
+            emitRefineProgress(
+                stage = "error",
+                fraction = 1.0,
+                frames = framePaths.size,
+                errorMessage = msg,
             )
+            promise.reject("incremental-refine-invalid-input", msg)
             return
         }
         val outputPath = stripFileScheme(outputPathOpt)
@@ -1709,16 +1727,26 @@ class IncrementalStitcher(
         // Pre-flight existence check — same defensive layer iOS has.
         for (p in framePaths) {
             if (!File(p).exists()) {
-                promise.reject(
-                    "incremental-refine-missing-keyframe",
-                    "refinePanorama: keyframe missing on disk — $p",
+                val msg = "refinePanorama: keyframe missing on disk — $p"
+                emitRefineProgress(
+                    stage = "error",
+                    fraction = 1.0,
+                    frames = framePaths.size,
+                    errorMessage = msg,
                 )
+                promise.reject("incremental-refine-missing-keyframe", msg)
                 return
             }
         }
 
         refineScope.launch {
             try {
+                emitRefineProgress(
+                    stage = "stitching",
+                    fraction = 0.1,
+                    frames = framePaths.size,
+                    errorMessage = null,
+                )
                 val stitcher = BatchStitcher.bridgeInstance
                     ?: throw IllegalStateException(
                         "BatchStitcher.bridgeInstance is null — " +
@@ -1742,6 +1770,18 @@ class IncrementalStitcher(
                     useInscribedRectCrop,
                     stitchMode = effectiveMode,
                 )
+                // Stitch returned — BatchStitcher writes the JPEG
+                // synchronously, so "writing" reflects the final
+                // assembly + file I/O cost (which has already been
+                // paid by this point in practice).  Emit so JS can
+                // flip its label from "Stitching" to "Writing"
+                // before the done event fires.
+                emitRefineProgress(
+                    stage = "writing",
+                    fraction = 0.9,
+                    frames = framePaths.size,
+                    errorMessage = null,
+                )
                 val framesRequested =
                     if (dims.size > 2) dims[2] else framePaths.size
                 val framesIncluded =
@@ -1757,8 +1797,20 @@ class IncrementalStitcher(
                     putInt("framesDropped", framesRequested - framesIncluded)
                     putDouble("finalConfidenceThresh", finalConfidenceThresh)
                 }
+                emitRefineProgress(
+                    stage = "done",
+                    fraction = 1.0,
+                    frames = framePaths.size,
+                    errorMessage = null,
+                )
                 promise.resolve(map)
             } catch (t: Throwable) {
+                emitRefineProgress(
+                    stage = "error",
+                    fraction = 1.0,
+                    frames = framePaths.size,
+                    errorMessage = t.message ?: t.javaClass.simpleName,
+                )
                 promise.reject("incremental-refine-failed", t.message, t)
             }
         }
@@ -1883,6 +1935,59 @@ class IncrementalStitcher(
         emitState(state)
     }
 
+    /**
+     * v0.10.0 #15A — emit a refine-pipeline phase update on the same
+     * `IncrementalStateUpdate` channel that carries `isRefining` /
+     * `refinedPanoramaPath`.  Five `stage` values fire across the
+     * lifetime of one `refinePanorama` call:
+     *
+     *   - "validating" (fraction 0.05) — synchronous input checks
+     *   - "stitching"  (fraction 0.10) — start of the OpenCV stitch
+     *   - "writing"    (fraction 0.90) — stitch returned, JPEG written
+     *   - "done"       (fraction 1.00) — promise about to resolve
+     *   - "error"      (fraction 1.00) — failure path (errorMessage
+     *                                    is non-null)
+     *
+     * Coarse on purpose: OpenCV's Stitcher doesn't expose stage-by-
+     * stage callbacks, so the 0.10 → 0.90 jump is one opaque step.
+     * JS uses `stage` for the UI label and `fraction` for the spinner.
+     *
+     * iOS sibling: IncrementalStitcher.swift::emitRefineProgress.
+     * Field names + stage strings are kept identical so the JS
+     * subscriber in src/stitching/incremental.ts doesn't branch on
+     * platform.
+     */
+    private fun emitRefineProgress(
+        stage: String,
+        fraction: Double,
+        frames: Int?,
+        errorMessage: String?,
+    ) {
+        val state = Arguments.createMap().apply {
+            putNull("panoramaPath")
+            putInt("width", 0)
+            putInt("height", 0)
+            putInt("acceptedCount", 0)
+            putInt("outcome", 0)              // AcceptedHigh
+            putDouble("confidence", 1.0)
+            putDouble("overlapPercent", -1.0)
+            putInt("processingMs", 0)
+            putBoolean("isLandscape", false)
+            putInt("paintedExtent", 0)
+            putInt("panExtent", 0)
+            putInt("keyframeMax", 0)
+            putString("refineStage", stage)
+            putDouble("refineProgress", fraction)
+            if (frames != null) {
+                putInt("refineFrames", frames)
+            }
+            if (errorMessage != null) {
+                putString("refineError", errorMessage)
+            }
+        }
+        emitState(state)
+    }
+
     /**
      * 2026-05-16 — given the live panorama path, derive a sibling
      * path for the refined output.  Same algorithm iOS uses:

package/cpp/stitcher_worklet_registry.cpp

@@ -78,4 +78,14 @@ void StitcherWorkletRegistry::_resetForTests() {
   _nextId = 0;
 }
 
+std::string StitcherWorkletRegistry::_installEntryForTests(
+    std::shared_ptr<RNWorklet::WorkletInvoker> invoker) {
+  std::lock_guard<std::mutex> lock(_mutex);
+  std::ostringstream idStream;
+  idStream << "host-" << _nextId++;
+  std::string id = idStream.str();
+  _entries.push_back({id, std::move(invoker)});
+  return id;
+}
+
 }  // namespace retailens

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).