react-native-image-stitcher 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -16,6 +16,275 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+Three new primitives completing the Tier 2 surface in the
+three-tier extensibility pattern.  See `docs/frame-access-tiers.md`
+for the full decision flow + use-case mapping.
+
+#### Layer 1 — `save_frame_as_jpeg` vc Frame Processor plugin (native)
+
+Worklet-callable JPEG encoder. Registers on both platforms:
+
+- **iOS** — `SaveFrameAsJpegPlugin.mm` (CIImage → CGImage → UIImage
+  → UIImageJPEGRepresentation → atomic NSData write).  Registered
+  via `+ (void)load` hook into `FrameProcessorPluginRegistry`.
+- **Android** — `SaveFrameAsJpegPlugin.kt` wrapping the lib's
+  existing `YuvImageConverter.encodeJpegFromNV21` encoder (the
+  same one used by `RNSARCameraView`'s keyframe-accept callback).
+  Registered alongside `cv_flow_gate_process_frame` in
+  `RNImageStitcherPackage.ensureFrameProcessorPluginRegistered`.
+
+Plugin contract (identical on both platforms):
+  - Args: `path` (string, REQUIRED), `quality` (number 0-100,
+    default 75, clamped `[1, 100]`)
+  - Returns: `{ ok: true, path, width, height }` OR
+             `{ ok: false, error: "..." }`
+
+Hosts can call this directly from their own `useFrameProcessor`
+worklet for custom rate-control logic; most consumers use it
+indirectly via Layer 3.
+
+#### Layer 2 — `useThrottledFrameProcessor` hook
+
+```tsx
+const fp = useThrottledFrameProcessor(
+  (frame) => {
+    'worklet';
+    // Worklet-native processing at sub-frame-rate
+  },
+  { sampleHz: 2 },
+  [],
+);
+```
+
+Pure TS throttle gate over `useFrameProcessor` (v0.8.0).  Worklet
+fires up to `sampleHz` times per second; ticks too close together
+dropped via a monotonic-time `useSharedValue` gate.
+
+**Use for**: worklet-native processing — native OCR via
+Vision.framework / ML Kit wrapped as vc Frame Processor plugins,
+TFLite ML inference, LiDAR depth (`frame.arDepth`).  Direct
+buffer/pose/depth access in the worklet; bridge small bbox-result
+payloads to JS via `runOnJS`.
+
+`sampleHz` clamped to `[0.5, 30]`.
+
+#### Layer 3 — `useFrameStream` hook
+
+```tsx
+const fp = useFrameStream(
+  { sampleHz: 2, quality: 75 },
+  (sample) => {
+    // JS-thread callback: sample.jpegPath, sample.pose, sample.timestamp
+    setThumbnail(sample.jpegPath);
+  },
+);
+```
+
+Composes Layer 2 + Layer 1 + `runOnJS` bridge to deliver
+`SampledFrame` objects to a JS-thread handler.  Slot-reuse
+strategy bounds disk usage to ~4 stale JPEGs.
+
+**Use for**: JS-thread consumers — file-path OCR libraries (RN
+modules wrapping ML Kit), cloud upload, thumbnail preview UI,
+JS-side ML (TF.js, transformers.js).
+
+`sampleHz` clamped to `[0.5, 10]`; `quality` clamped `[1, 100]`.
+
+#### Types
+
+  - `SampledFrame` — `{ jpegPath, pose, timestamp, width, height }`
+  - `FrameStreamOptions` — `{ sampleHz, quality?, outputDir? }`
+  - `ThrottledFrameProcessorOptions` — `{ sampleHz }`
+
+All exported from `react-native-image-stitcher`.
+
+### Documentation
+
+- `docs/frame-access-tiers.md` — new comprehensive reference for
+  all four host-facing hooks (`useKeyframeStream`,
+  `useThrottledFrameProcessor`, `useFrameStream`,
+  `useFrameProcessor`) with decision flow, cost envelope, use-case
+  mapping, AR vs non-AR mode tradeoff.
+
+### Example app
+
+`example/App.tsx` now mounts `useFrameStream` at 2 Hz with a
+visible thumbnail overlay (bottom-right corner) — visual proof of
+the Layer 1 + 2 + 3 pipeline working end-to-end on both iPhone
+(60 Hz AR) and Galaxy A35 (30 Hz AR).
+
+### Compatibility
+
+- Strict additive over v0.8.0.  No host changes required.
+- Works in both AR and non-AR modes via v0.8.0's unified
+  `useFrameProcessor`.
+- 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
+  run for this release — the layered design doesn't touch
+  first-party stitching, so a regression is structurally unlikely.
+  Harness still in place from v0.8.0 (`scripts/ssim-compare.py`)
+  for any host that wants to run it locally.
+
+[0.9.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.8.0...v0.9.0
+
 ## [0.8.0] — 2026-05-27
 
 ### Added — `useFrameProcessor` hook for host worklets

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/android/src/main/java/io/imagestitcher/rn/RNImageStitcherPackage.kt

@@ -55,19 +55,33 @@ class RNImageStitcherPackage : ReactPackage {
                 ) { proxy, options ->
                     CvFlowGateFrameProcessor(proxy, options)
                 }
+                // v0.9.0 Layer 1 — register `save_frame_as_jpeg`
+                // alongside the cv_flow_gate plugin.  Same lifecycle,
+                // same defensive error handling (the outer try/catch
+                // covers both registrations).  Either both register
+                // or neither does — if vc isn't on the classpath,
+                // both calls are skipped together.
+                FrameProcessorPluginRegistry.addFrameProcessorPlugin(
+                    SaveFrameAsJpegPlugin.PLUGIN_NAME,
+                ) { proxy, options ->
+                    SaveFrameAsJpegPlugin(proxy, options)
+                }
                 fpPluginRegistered = true
             } catch (e: NoClassDefFoundError) {
                 android.util.Log.i(
                     "RNImageStitcherPackage",
                     "vision-camera FrameProcessorPluginRegistry not on classpath — "
-                    + "skipping cv_flow_gate_process_frame plugin registration "
-                    + "(host app doesn't appear to use Frame Processors).",
+                    + "skipping cv_flow_gate_process_frame + save_frame_as_jpeg "
+                    + "plugin registration (host app doesn't appear to use "
+                    + "Frame Processors).",
                 )
                 fpPluginRegistered = true  // don't retry every package init
             } catch (e: Throwable) {
                 android.util.Log.w(
                     "RNImageStitcherPackage",
-                    "Failed to register cv_flow_gate_process_frame plugin: ${e.message}",
+                    "Failed to register Frame Processor plugins "
+                    + "(cv_flow_gate_process_frame / save_frame_as_jpeg): "
+                    + e.message,
                 )
                 fpPluginRegistered = true
             }

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

@@ -0,0 +1,162 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+import android.graphics.ImageFormat
+import android.media.Image
+import android.util.Log
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.mrousavy.camera.frameprocessors.Frame
+import com.mrousavy.camera.frameprocessors.FrameProcessorPlugin
+import com.mrousavy.camera.frameprocessors.VisionCameraProxy
+import io.imagestitcher.rn.ar.YuvImageConverter
+
+/**
+ * v0.9.0 Layer 1 — Android vc Frame Processor plugin that JPEG-
+ * encodes the supplied frame to a host-supplied path.  Mirror of
+ * iOS' `SaveFrameAsJpegPlugin.mm`.
+ *
+ * Plugin name (must match iOS): `save_frame_as_jpeg`.
+ *
+ * ## Wrapping the existing encoder
+ *
+ * The lib already encodes JPEGs from NV21 bytes via
+ * `YuvImageConverter.encodeJpegFromNV21` — that's the path
+ * `RNSARCameraView.kt`'s keyframe-accept callback uses (line 589,
+ * `onAccept = { targetPath -> ... encodeJpegFromNV21(...) }`).
+ * This plugin reuses that exact encoder so:
+ *   - JPEG output is byte-equivalent to the keyframe-accept output
+ *     (same encoder, same quality knob)
+ *   - No new encoder maintenance burden
+ *
+ * vision-camera's `Frame.image` is an `android.media.Image` in
+ * `YUV_420_888` format (the camera's native).  We pass it through
+ * `YuvImageConverter.packNV21(image)` to extract the dense NV21
+ * byte array + dims, then `encodeJpegFromNV21(packed, file, q, rot)`
+ * does the JPEG write.
+ *
+ * ## Plugin contract (matches iOS surface exactly)
+ *
+ * Arguments dict:
+ *   - `path` (string, REQUIRED): absolute output path.
+ *   - `quality` (number, optional): 0-100 JPEG quality.  Default 75.
+ *     Clamped to [1, 100].
+ *
+ * Returns:
+ *   - On success: `{ "ok" => true, "path" => ..., "width" => ...,
+ *                    "height" => ... }`
+ *   - On failure: `{ "ok" => false, "error" => "..." }`
+ *
+ * Errors surfaced via the result map (not thrown) — host worklets
+ * can branch on `result.ok` without try/catch.  Same convention
+ * as iOS.
+ *
+ * ## Lifetime / threading
+ *
+ * The supplied `Frame` (and its `Image`) is valid only for the
+ * duration of this callback — vision-camera closes the underlying
+ * `Image` on return.  All Image access (NV21 pack + JPEG encode)
+ * happens synchronously inside `callback()`.
+ *
+ * ## Format restriction
+ *
+ * Only `YUV_420_888` input is supported (vc Android's standard).
+ * Anything else returns `{ ok: false, error: "unsupported format" }`.
+ * No format conversion fallback — that would mask bugs in the host
+ * camera config.
+ *
+ * ## Registration
+ *
+ * Registered in `RNImageStitcherPackage.kt`'s companion-object
+ * `ensureFrameProcessorPluginRegistered()`, alongside
+ * `cv_flow_gate_process_frame`.  Same defensive
+ * NoClassDefFoundError handling — if vc isn't on the host's
+ * classpath, registration is silently skipped (and the plugin's
+ * `init { … }` calls below never happen).
+ */
+@DoNotStrip
+@Keep
+class SaveFrameAsJpegPlugin(
+    @Suppress("UNUSED_PARAMETER") proxy: VisionCameraProxy,
+    @Suppress("UNUSED_PARAMETER") options: Map<String, Any>?,
+) : FrameProcessorPlugin() {
+
+    override fun callback(frame: Frame, params: Map<String, Any>?): Any {
+        val path = params?.get("path") as? String
+            ?: return mapOf(
+                "ok" to false,
+                "error" to "missing required `path` argument",
+            )
+        val rawQuality = (params["quality"] as? Number)?.toInt() ?: 75
+        val quality = rawQuality.coerceIn(1, 100)
+
+        // Frame may throw if vc already released it.
+        val image: Image = try {
+            frame.image
+        } catch (e: Throwable) {
+            return mapOf(
+                "ok" to false,
+                "error" to "frame invalid: ${e.message}",
+            )
+        }
+
+        if (image.format != ImageFormat.YUV_420_888) {
+            return mapOf(
+                "ok" to false,
+                "error" to "unsupported format ${image.format} (need YUV_420_888)",
+            )
+        }
+
+        // Pack NV21 — same call site RNSARCameraView uses.
+        val packed = YuvImageConverter.packNV21(image)
+            ?: return mapOf(
+                "ok" to false,
+                "error" to "YuvImageConverter.packNV21 returned null",
+            )
+
+        // Reuse the lib's existing JPEG encoder.  Rotation is 0 here
+        // (the host's frame is in camera-native orientation; if they
+        // want display orientation they can pass an `orientation`
+        // arg in a future version — for v0.9.0 the worklet emits
+        // raw-camera-oriented JPEGs, matching the keyframe-accept
+        // pipeline's behaviour).
+        //
+        // Signature: `encodeJpegFromNV21(packed, outputPath: String,
+        // jpegQuality: Int, displayRotation: Int): String?` — returns
+        // the written path on success, null on failure.
+        val encodedPath: String? = try {
+            YuvImageConverter.encodeJpegFromNV21(
+                packed,
+                path,
+                jpegQuality = quality,
+                displayRotation = 0,
+            )
+        } catch (e: Throwable) {
+            return mapOf(
+                "ok" to false,
+                "error" to "encodeJpegFromNV21 threw: ${e.message}",
+            )
+        }
+        if (encodedPath == null) {
+            return mapOf(
+                "ok" to false,
+                "error" to "encodeJpegFromNV21 returned null",
+            )
+        }
+
+        return mapOf(
+            "ok" to true,
+            "path" to encodedPath,
+            "width" to packed.width,
+            "height" to packed.height,
+        )
+    }
+
+    companion object {
+        private const val TAG = "SaveFrameAsJpegPlugin"
+
+        /// Plugin name; MUST match iOS + the JS-side
+        /// `initFrameProcessorPlugin('save_frame_as_jpeg')` call.
+        const val PLUGIN_NAME = "save_frame_as_jpeg"
+    }
+}

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