react-native-image-stitcher 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -16,6 +16,366 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-05-23
+
+> [!IMPORTANT]
+> **v0.3.0 is the audit-follow-up release.**  After v0.2.x we ran an
+> exhaustive PanoramaSettings ground-truth audit and shipped the
+> v0.3-pixel-data work alongside ~15 follow-up correctness fixes,
+> two crash fixes, a stitcher mode-fallback retry, and the
+> RetaiLens-parity debug UI port.  Detailed entries below.
+>
+> **Behaviour changes**
+>   - Android AR mode + both platforms' non-AR mode now actually run
+>     the Flow strategy (sparse optical-flow novelty) end-to-end.
+>     Pre-0.3 they silently fell back to Pose strategy because no
+>     pixel data was supplied — hosts who tuned
+>     `keyframeOverlapThreshold` on those paths were tuning a
+>     different algorithm than is now active.
+>   - `stitchMode: 'auto'` now resolves correctly on iOS (was
+>     silently hardcoded to Panorama) and uses IMU-measured
+>     translation in non-AR mode.
+>   - `frameSelectionMode` is now honoured on both platforms;
+>     previously hardcoded to `'flow-based'`.
+>   - Mode-fallback retry: if the resolved cv::Stitcher mode fails
+>     with degenerate camera params, the stitcher automatically
+>     retries with the opposite mode before giving up.
+
+### Added
+
+- **Pixel-aware Flow strategy across all four capture paths** —
+  iOS AR, iOS non-AR, Android AR, Android non-AR.  The C++
+  KeyframeGate's `evaluateWithFrame` overload is now reached from
+  every entry point with real grayscale pixel data (Y plane bytes
+  on AR paths, decoded JPEG luma on non-AR paths).
+- **Debug UI suite** (gated by `settings.debug`):
+  `CaptureMemoryPill` (top-right), `CaptureKeyframePill` (top-center),
+  `CaptureOrientationPill` (top-left), `CaptureStitchStatsToast` +
+  `useStitchStatsToast` hook, plus a detailed metrics block
+  (`CaptureDebugOverlay`).  All exported individually for Layer 2
+  hosts to compose their own debug surface.
+- **`stitchModeResolved`** in `IncrementalFinalizeResult` +
+  `CameraCaptureResult.panorama` — surfaces which cv::Stitcher
+  pipeline actually ran (`panorama` / `scans`), useful for
+  displaying on the output preview.
+
+### Fixed
+
+- **F1 — Android `disableAngularFallback` was always false.**
+  The non-AR opt-out tested `captureSource ∈ {"wide", "ultrawide"}`
+  against a JS API that has been sending `"ar"` / `"non-ar"` since
+  v0.2.  String mismatch silently nullified the opt-out → gyro
+  drift accepted near-identical frames → `STITCH_CAMERA_PARAMS_FAIL
+  — warpRoi too large (43039×55525)` on shelf-scan captures.
+- **F1b — iOS `disableAngularFallback` wasn't wired at all.**  The
+  C++ setter existed but the Swift facade had no property, the
+  Obj-C++ bridge had no method, and IncrementalStitcher never
+  called it.  Same crash class as F1, just hidden until now.
+- **F2 — iOS `stitchMode` was hardcoded to Panorama.**  Now reads
+  the JS setting and resolves 'auto' via translation/rotation
+  magnitude-ratio (port of Android's resolveStitchModeAuto).
+- **F2b — Auto-resolver uses IMU translation in non-AR mode.**  The
+  JS-driver path doesn't carry pose tx/ty/tz, so the pose-only
+  resolver always picked 'panorama' even for shelf scans.  Now
+  folds the IMU translation gate's measured displacement into the
+  resolver (`tMeters = max(tPose, tImu)`).
+- **F2c — Cross-capture IMU drift bias.**  Pre-fix the gravityX IIR
+  estimate was preserved across capture boundaries; if the phone
+  was at a different orientation between captures, the stale
+  estimate biased the linear-acceleration calculation for the
+  ~200 ms IIR convergence window, integrating into posX and
+  compounding per-capture.  Now reseed gravityX on every
+  subscription start (= every capture).
+- **F2d — IMU gate auto-rearms on every budget interval.**  Pre-fix
+  the gate latched after the first `markNextFrameAsLastKeyframe`
+  fire and never re-triggered.  Now resets posX + velX + fired
+  internally so it fires every `flowMaxTranslationCm` of measured
+  translation.
+- **F2e — Android batch-keyframe now emits overlap %.**  Pre-fix
+  `overlapPercent` was hardcoded to -1 in the accept emit, and
+  reject events emitted nothing at all — debug overlay was frozen
+  between accepts.  Now reflects the gate's actual newContent
+  fraction on both accepts and rejects.
+- **F2f — IMU delta resets on ANY frame accept.**  Pre-fix the
+  `imuΔ` debug indicator only reset when the IMU gate itself
+  fired; a flow-novelty accept left posX ticking up indefinitely.
+  Now Camera.tsx watches `acceptedCount` and resets the gate on
+  every increment.  A separate `totalAbsMetres` accumulator banks
+  the magnitude across resets so the finalize-time auto-resolver
+  still sees full translation history.
+- **F4 — Camera.tsx now passes the four flow-tunable fields and
+  `captureSource`.**  Pre-fix `flowMaxCorners`, `flowQualityLevel`,
+  `flowMinDistance`, `enableMaxInscribedRectCrop`, and
+  `captureSource` were silently dropped between the modal and the
+  native bridge.  Now all five reach the engine.
+- **F5 — Android KeyframeGate gained the missing Flow-tunable
+  surface.**  Added Kotlin facade properties + JNI thunks for
+  `setFlowMaxCorners`, `setFlowQualityLevel`, `setFlowMinDistance`,
+  `setStrategy`.  Android now mirrors iOS for the gate's full
+  knob set.  Added the eval-throttle (`flowEvalEveryNFrames`)
+  to the AR ingest path.
+- **F6 — `frameSelectionMode` is no longer hardcoded to
+  'flow-based'.**  Camera.tsx now passes the JS setting through;
+  both platforms honour `time-based` (gate disabled),
+  `pose-based` (Pose strategy), and `flow-based` (Flow strategy).
+- **F7 — README documented `defaultFlowMaxTranslationCm` as 8
+  cm.**  Actual default is 50 cm; 6× off.
+- **ARCore Session.close() on AR-off** (Android-only crash fix).
+  Pre-fix `RNSARSession.stop()` and `stopForView()` called
+  `Session.pause()` then nulled the session reference.  ARCore's
+  `pause()` only stops frame production — its native worker
+  threads stay alive.  Orphaned, those threads kept running and
+  crashed under memory pressure with SIGSEGV in
+  `tango_pool_lp4`/`libarcore_c.so` (tombstone-confirmed).  Now
+  calls `pause()` then `close()` (ARCore's documented full
+  teardown), and the camera-view drops its own stale reference.
+- **Stitcher mode-fallback retry.**  When the configured stitchMode
+  fails with degenerate camera params, the stitcher now
+  automatically retries with the opposite mode before giving up
+  (panorama → scans or scans → panorama).  Result type carries
+  `stitchModeUsed` so callers can see which mode succeeded.  The
+  warpRoi-too-large error message now includes the configured
+  mode + frame index for diagnostics.
+- **Thumbnail strip first-frame race.**  Pre-fix the `useEffect`
+  that cleared `batchKeyframeThumbnails` on statusPhase change
+  could race ahead of the JS subscriber: the AR camera's GL
+  thread could emit an ACCEPT during handleHoldStart's
+  `await incremental.start(...)` window, the subscriber would
+  add frame 0 to thumbnails, THEN React's queued statusPhase
+  effect would wipe the array — frame 0 was missing from the
+  strip.  Fixed by moving the reset synchronously to the top of
+  handleHoldStart, before any await.
+
+### Audit ground-truth findings (no code change, doc-only)
+
+- **F1 — Android `disableAngularFallback` was always false.** The
+  Android JNI's non-AR opt-out for the angular-delta gate fallback
+  tested `captureSource ∈ {"wide", "ultrawide"}` against a JS API
+  that has been sending `"ar"` / `"non-ar"` since 2026-05-14.  The
+  string mismatch silently nullified the opt-out for the entire
+  Android non-AR path, letting gyro drift accumulate into the
+  integrated yaw/pitch and produce near-identical "accepted"
+  frames — which is what blew up cv::Stitcher with the "warpRoi too
+  large (43039×55525) — estimator produced degenerate camera params"
+  error on shelf-scan captures.  Fix: read `"non-ar"`.
+- **F2 — iOS `stitchMode` setting is now honoured end-to-end.**  Pre-
+  audit, `OpenCVStitcher.mm:436` hardcoded `cv::Stitcher::PANORAMA`
+  regardless of the JS setting, so operators picking `'scans'` or
+  `'auto'` from the modal saw no effect on iOS.  iOS now reads
+  `configOverrides["stitchMode"]`, tracks first + last accepted
+  keyframe poses, and implements `resolveStitchModeAuto` (port of
+  Android's translation/rotation magnitude-ratio heuristic) at
+  finalize time.  Both platforms now resolve `'auto'` identically.
+- **F4 — Camera.tsx now passes settings the modal exposed but Camera
+  silently dropped.**  Pre-audit, the `config` block passed to
+  `incremental.start()` omitted four fields that iOS native already
+  read: `flowMaxCorners`, `flowQualityLevel`, `flowMinDistance`,
+  `enableMaxInscribedRectCrop`.  Modal sliders for these were
+  silent no-ops on every platform.  Now wired.  Also added
+  `captureSource` to the config so F1's Android opt-out has
+  something to read.
+- **F5 — Android KeyframeGate now exposes the full Flow tunable
+  surface.**  Pre-audit, the Android KeyframeGate facade lacked
+  Kotlin properties + JNI thunks for `setFlowMaxCorners` /
+  `setFlowQualityLevel` / `setFlowMinDistance` / `setStrategy`,
+  even though the underlying C++ gate has had them since 0.2.0.
+  Added the missing JNI bindings + Kotlin facade fields.  Android
+  IncrementalStitcher now reads `flowMaxCorners`, `flowQualityLevel`,
+  `flowMinDistance`, `flowEvalEveryNFrames`, and `frameSelectionMode`
+  from configOverrides with clamp ranges matching iOS.
+- **F6 — Camera.tsx no longer hardcodes `frameSelectionMode`.**  Pre-
+  audit, line 835 hardcoded `'flow-based'`, so the modal's
+  `time-based` / `pose-based` / `flow-based` toggle had no runtime
+  effect.  Now passes `settings.frameSelectionMode` through.  Both
+  platforms honour the setting: `time-based` disables the gate
+  (passthrough), `pose-based` enables Pose strategy, `flow-based`
+  enables Flow strategy.  Android additionally now applies the
+  eval-throttle (`flowEvalEveryNFrames`) to the AR ingest path,
+  matching iOS' `IncrementalStitcher.swift:2459-2471` behaviour.
+- **F7 — README documented `defaultFlowMaxTranslationCm` default as
+  `8`.**  Actual `DEFAULT_PANORAMA_SETTINGS.flowMaxTranslationCm` is
+  `50`; 6× off.  Corrected.
+
+### Audit ground-truth findings (doc-only)
+
+The full audit traced every `PanoramaSettings` field through Camera.tsx,
+the iOS bridge (`IncrementalStitcher.swift::applyConfigOverrides` and
+the cv::Stitcher path), the Android bridge
+(`IncrementalStitcher.kt::start`), the C++ gate (`cpp/keyframe_gate.cpp`),
+and the live-engine config type (`RLISStitcherConfig`).  Conclusions:
+
+- Batch-keyframe and the live engines (hybrid + slit-scan) share
+  **zero settings**.  All RLISStitcherConfig fields (NCC, plane
+  projection, paint mode, slit-scan painting) flow only through
+  Layer 2 entry points (`incremental.start({ engine: 'slitscan-…' })`),
+  never through `<Camera>` (which hardcodes `engine: 'batch-keyframe'`).
+- ~10 fields in `PanoramaSettings` are confirmed dead (no native
+  consumer at all): `useARPreview`, `incrementalEngine`,
+  `slitWidthFraction`, `acceptGate`, `maxRecordingMs`,
+  `framesPerSecond`, `minFrames`, `maxFrames`, `quality`, and the
+  legacy `useDetectedPlane` alias.  These are scheduled for removal
+  in v0.4.0 as part of the engine-discriminated typed-settings
+  rewrite.
+
+## [0.3.0-pre-audit] — 2026-05-21
+
+> [!IMPORTANT]
+> **Behaviour change on Android AR mode and on both platforms' non-AR
+> mode.**  Keyframe selection now actually runs the **Flow strategy**
+> (sparse optical-flow novelty) on these paths, where pre-0.3 the
+> C++ KeyframeGate silently fell back to the Pose strategy
+> (angular-delta) because no pixel data was supplied.  Hosts that
+> tuned `keyframeOverlapThreshold` on these paths were tuning a
+> different algorithm than is now active — see the migration note
+> below before re-validating capture quality.  iOS AR mode is
+> unchanged (already ran Flow with pixel data via the AR delegate).
+
+### Fixed
+
+- **[#9](https://github.com/bhargavkanda/react-native-image-stitcher/issues/9): Android AR mode — first keyframe thumbnail no longer delayed
+  several hundred milliseconds.**  Pre-0.3 the AR ingest pipeline
+  encoded every ARCore frame to JPEG and wrote it to disk on the
+  GL render thread (~25 ms per frame at ~60 Hz) regardless of
+  whether the gate would accept it.  Then the gate ran a pose-only
+  evaluation (no pixel data) which silently fell back to the
+  stricter Pose strategy, masking the result by force-accepting via
+  the IMU translation gate.  Net effect: noticeable lag before
+  frame 1 thumbnail rendered, and frame 1 / frame 2 spacing
+  visually too large.
+  - v0.3 rewires the AR ingest path to extract just the **Y plane
+    bytes** from the ARCore camera image (zero-copy via
+    DirectByteBuffer → JVM byte[] + JNI `GetPrimitiveArrayCritical`)
+    and feeds them directly to the C++ gate's existing
+    `evaluateWithFrame` overload.  Per-frame cost on the GL render
+    thread drops from ~25-40 ms to ~2-5 ms for rejected frames.
+  - JPEG encode + disk write is **deferred to only accepted frames**
+    (typically 3-6 per capture) via an `onAccept` lambda the gate
+    invokes if-and-only-if it keeps the frame.  Single disk write
+    per accepted keyframe (pre-0.3 was: encode-then-copy = two
+    writes).
+  - Gate now runs Flow strategy with real pixel content — feature-
+    tracking-based novelty, not the strict angular-delta proxy.
+- **iOS non-AR + Android non-AR Flow strategy regression** —
+  related to #9 but not user-reported.  Both non-AR paths previously
+  called `evaluate(pose, plane: nil)` with no pixel data, which
+  silently fell back to Pose strategy on both platforms.  v0.3
+  decodes the JPEG snapshot to grayscale before the gate call so
+  Flow strategy runs:
+  - iOS: `CGImageSource → CGContext` into a single-channel
+    `CVPixelBuffer` (`kCVPixelFormatType_OneComponent8`).  The
+    `KeyframeGateBridge.mm` got OneComponent8 case-handling
+    (parallel to the existing NV12 / BGRA cases).  ~10-20 ms per
+    snapshot on iPhone 13/16 Pro.
+  - Android: `Imgcodecs.imread(path, IMREAD_GRAYSCALE)` decodes
+    the JPEG straight to a CV_8UC1 Mat which we marshal into a
+    ByteArray for the new `nativeEvaluateWithFrame` JNI thunk.
+    ~10-20 ms per snapshot on Galaxy A35.
+
+### Added
+
+- **`KeyframeGate.evaluateWithFrame(pose, plane, grayData, w, h, stride)`**
+  (Kotlin) — pixel-aware Flow-strategy gate-evaluate entry point,
+  parity with the existing iOS `KeyframeGateBridge.evaluatePixelBuffer:…`.
+- **`nativeEvaluateWithFrame`** JNI thunk in `keyframe_gate_jni.cpp`.
+  Uses `GetPrimitiveArrayCritical` for zero-copy access to the
+  JVM-side byte[] during the gate evaluate.
+- **`kCVPixelFormatType_OneComponent8` handling** in iOS
+  `KeyframeGateBridge.mm` — base address is read directly as the
+  Y plane with no conversion cost.
+
+### Changed
+
+- **`IncrementalStitcher.ingestFromARCameraView` signature** (Android,
+  internal):
+  - **Removed**: `path: String` parameter.  AR camera view no longer
+    encodes a JPEG to feed this method — it hands over Y-plane bytes
+    instead.
+  - **Added**: `grayData: ByteArray, grayWidth: Int, grayHeight: Int,
+    grayStride: Int, onAccept: (targetPath: String) -> Boolean`.
+    The lambda is invoked only on gate-accept and is expected to
+    write a JPEG of the current camera image to the supplied target
+    path.  Returns true on success.
+  - `RNSARCameraView.forwardToIncremental` updated accordingly.
+- **`RNSARCameraView.postFrameToEngine` removed.**  The thin wrapper
+  was only used to wrap the old positional call to
+  `ingestFromARCameraView`; the new lambda-based call shape is
+  inline in `forwardToIncremental`.
+
+### Migration from 0.2.x
+
+**Most consumers**: no code change required.  The public JS API
+(`<Camera>`, `useCapture`, `useIMUTranslationGate`,
+`useDeviceOrientation`, everything) is byte-identical to 0.2.1.
+
+**Hosts that tuned `keyframeOverlapThreshold` against Android AR or
+either non-AR path**: the threshold now controls **Flow novelty
+percentile** instead of **Pose angular delta**.  Same setting, very
+different metric — re-tune against your typical captures.  The
+default (`0.20`) was chosen to roughly match the pre-0.3 visible
+behaviour; most hosts shouldn't need to change anything, but
+quality-sensitive hosts should re-validate before shipping.
+
+**Hosts that observed the Android-AR first-frame delay**: the bug
+is fixed — first thumbnail should render within ~50 ms of shutter
+hold (was ~200+ ms).
+
+### Deferred to v0.4 ([#11](https://github.com/bhargavkanda/react-native-image-stitcher/issues/11))
+
+Non-AR capture currently still goes through vision-camera's
+`takeSnapshot()` API at ~4 FPS with a per-snapshot JPEG-encode +
+disk-write + decode-to-grayscale round-trip.  v0.4 will migrate
+non-AR to vision-camera's Frame Processor API: raw pixel data
+direct from the camera, no JPEG, no disk, full camera frame rate.
+At that point the JPEG-decode-to-grayscale workaround added in
+v0.3's iOS/Android non-AR paths becomes redundant and will be
+removed.  See issue #11 for the full scope.
+
+## [0.2.1] — 2026-05-21
+
+### Changed
+
+- **Example app no longer wires Expo modules.**  The deferred v0.2
+  follow-up landed: the example app now uses the standard React
+  Native 0.84 host wiring throughout — `RCTReactNativeFactory` in
+  `AppDelegate.swift`, `DefaultReactHost.getDefaultReactHost` in
+  `MainApplication.kt`, no `use_expo_modules!` macro in `Podfile`,
+  no `expo-root-project` plugin or `expoAutolinking.useExpoModules()`
+  call in the gradle files, and no `expo`/`expo-modules-core`/
+  `expo-modules-autolinking` packages in `example/package.json`.
+  The two inline `patch-package`-style Podfile patches for Expo
+  SDK 55 on RN 0.84 are also gone — they were only needed because
+  we were dragging Expo in.  Verified by clean build + install on
+  iPhone 16 Pro and Galaxy A35 (with `LANG=en_US.UTF-8 pod install`
+  + `JAVA_HOME` set to OpenJDK 17, both required workarounds for
+  unrelated tooling bugs we now document in the troubleshooting
+  table).
+- **`docs/host-app-integration.md` rewritten** for the post-Expo
+  posture.  Dropped ~340 lines describing Podfile macros,
+  AppDelegate Expo factory wiring, MainApplication Expo factory
+  wiring, gradle `expo-root-project` plugin, and the
+  `expo-modules-core+55.0.14.patch` patch-package patch.  The
+  remaining content (vision-camera permission strings, ARCore
+  manifest entries, the one `react-native-sensors+7.3.6.patch`
+  patch for the jcenter→mavenCentral swap, network access from
+  devices to Metro, troubleshooting) is preserved.  The README's
+  IMPORTANT block at [README.md:53-66](README.md:53) and the
+  pre-existing setup walkthrough still apply.
+
+### Migration from 0.2.0
+
+Hosts upgrading from 0.2.0 with their existing Expo modules host
+wiring **don't have to change anything** — Expo modules are
+additive, so the wiring keeps working even though the SDK no
+longer requires it.  But the wiring is now strictly optional, and
+[`docs/host-app-integration.md`](docs/host-app-integration.md)
+describes the simpler post-Expo path.  If you want to follow the
+simpler path: drop the four Expo packages from your
+`package.json`, revert your `AppDelegate.swift` /
+`MainApplication.kt` / Podfile / gradle / patches to the standard
+RN 0.84 templates documented in that file, run
+`pod deintegrate && pod install` (the CocoaPods 1.16 bug needs
+`LANG=en_US.UTF-8`), and rebuild.
+
 ## [0.2.0] — 2026-05-21
 
 > [!IMPORTANT]
@@ -311,7 +671,9 @@ Native module names also changed:
 - iOS pod: `RetaiLensCaptureSDK` → `RNImageStitcher`
 - iOS xcframework: shipped as `opencv2.xcframework` (linked from `RNImageStitcher.podspec`)
 
-[Unreleased]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/bhargavkanda/react-native-image-stitcher/compare/v0.1.1...v0.1.2

package/README.md

@@ -118,7 +118,7 @@ See `src/camera/Camera.tsx` for the full TSDoc.  Highlights:
 | `defaultWarper` | `'plane'` | `'plane'`, `'cylindrical'`, `'spherical'` |
 | `defaultFlowNoveltyPercentile` | `0.85` | Range 0.50 – 0.99 |
 | `defaultFlowEvalEveryNFrames` | `5` | Range 1 – 10 |
-| `defaultFlowMaxTranslationCm` | `8` | 0 = disabled |
+| `defaultFlowMaxTranslationCm` | `50` | 0 = disabled |
 | `defaultKeyframeMaxCount` | `6` | Range 3 – 10 |
 | `defaultKeyframeOverlapThreshold` | `0.20` | Range 0.20 – 0.60 |
 

package/android/src/main/cpp/keyframe_gate_jni.cpp

@@ -120,6 +120,46 @@ Java_io_imagestitcher_rn_KeyframeGate_nativeSetFlowNoveltyPercentile(
     gate(handle)->setFlowNoveltyPercentile(static_cast<double>(percentile));
 }
 
+// 2026-05-22 (audit F5) — Android JNI parity for the Shi-Tomasi
+// corner tunables.  Pre-audit, iOS bridges these via KeyframeGateBridge
+// but Android had no equivalent — JS Settings sliders for
+// flowMaxCorners / flowQualityLevel / flowMinDistance were no-ops on
+// Android.  See setFlowMaxCorners / setFlowQualityLevel /
+// setFlowMinDistance docs in keyframe_gate.hpp.
+JNIEXPORT void JNICALL
+Java_io_imagestitcher_rn_KeyframeGate_nativeSetFlowMaxCorners(
+    JNIEnv*, jclass, jlong handle, jint maxCorners)
+{
+    gate(handle)->setFlowMaxCorners(static_cast<int32_t>(maxCorners));
+}
+
+JNIEXPORT void JNICALL
+Java_io_imagestitcher_rn_KeyframeGate_nativeSetFlowQualityLevel(
+    JNIEnv*, jclass, jlong handle, jdouble quality)
+{
+    gate(handle)->setFlowQualityLevel(static_cast<double>(quality));
+}
+
+JNIEXPORT void JNICALL
+Java_io_imagestitcher_rn_KeyframeGate_nativeSetFlowMinDistance(
+    JNIEnv*, jclass, jlong handle, jdouble minDistance)
+{
+    gate(handle)->setFlowMinDistance(static_cast<double>(minDistance));
+}
+
+// 2026-05-22 (audit F6) — gate strategy selector.  Maps the Kotlin
+// enum's int value back to the C++ GateStrategy enum.  Pre-audit
+// Android had no way to flip strategy → was stuck on the C++ default
+// (Pose), making `frameSelectionMode = 'flow-based'` a silent no-op
+// on Android.
+JNIEXPORT void JNICALL
+Java_io_imagestitcher_rn_KeyframeGate_nativeSetStrategy(
+    JNIEnv*, jclass, jlong handle, jint strategyInt)
+{
+    auto strategy = static_cast<retailens::GateStrategy>(strategyInt);
+    gate(handle)->setStrategy(strategy);
+}
+
 JNIEXPORT void JNICALL
 Java_io_imagestitcher_rn_KeyframeGate_nativeReset(
     JNIEnv*, jclass, jlong handle)
@@ -201,4 +241,102 @@ Java_io_imagestitcher_rn_KeyframeGate_nativeEvaluate(
     return out;
 }
 
+// ── Per-frame evaluate WITH PIXEL DATA ──────────────────────────
+//
+// 2026-05-21 (v0.3) — pixel-aware Flow-strategy entry point.  The
+// `nativeEvaluate` above hands the gate pose + plane only, which
+// forces the C++ side to silently fall back from Flow strategy to
+// Pose strategy in cpp/keyframe_gate.cpp's evaluateWithFrame()
+// (defensive fallback at the grayData==nullptr branch).  This thunk
+// is the proper Flow-strategy entry point: the caller supplies the
+// frame's grayscale plane (Y plane for YUV camera images, or a
+// JPEG-decode result for the JS-driver path), and the C++ Flow
+// path actually runs feature tracking on it.
+//
+// grayBytes:  Java byte[] holding the grayscale plane.  Accessed via
+//             GetPrimitiveArrayCritical (no copy, pins GC briefly for
+//             the duration of the gate.evaluateWithFrame call —
+//             evaluation is ~1-5 ms so the pin window is tight).
+// width:      grayscale image width in pixels.
+// height:     grayscale image height in pixels.
+// stride:     bytes per row.  May exceed width when the plane has
+//             padding (ARCore's Image.Plane.getRowStride() can pad).
+//
+// plane16OrNull: same as nativeEvaluate — column-major 4×4 plane
+//             transform, or null for angular-delta fallback.
+//
+// Returns DoubleArray[5] identical to nativeEvaluate.
+JNIEXPORT jdoubleArray JNICALL
+Java_io_imagestitcher_rn_KeyframeGate_nativeEvaluateWithFrame(
+    JNIEnv* env, jclass, jlong handle,
+    jfloat tx, jfloat ty, jfloat tz,
+    jfloat qx, jfloat qy, jfloat qz, jfloat qw,
+    jfloat fx, jfloat fy, jfloat cx, jfloat cy,
+    jint imageWidth, jint imageHeight,
+    jfloatArray plane16OrNull,
+    jbyteArray grayBytes,
+    jint grayWidth, jint grayHeight, jint grayStride)
+{
+    retailens::Pose pose;
+    pose.tx = tx; pose.ty = ty; pose.tz = tz;
+    pose.qx = qx; pose.qy = qy; pose.qz = qz; pose.qw = qw;
+    pose.fx = fx; pose.fy = fy; pose.cx = cx; pose.cy = cy;
+    pose.imageWidth  = static_cast<int32_t>(imageWidth);
+    pose.imageHeight = static_cast<int32_t>(imageHeight);
+
+    retailens::PlaneTransform planeStorage;
+    const retailens::PlaneTransform* planePtr = nullptr;
+    if (plane16OrNull) {
+        jsize len = env->GetArrayLength(plane16OrNull);
+        if (len == 16) {
+            jfloat* src = env->GetFloatArrayElements(plane16OrNull, nullptr);
+            if (src) {
+                std::memcpy(planeStorage.m, src, sizeof(float) * 16);
+                env->ReleaseFloatArrayElements(plane16OrNull, src, JNI_ABORT);
+                planePtr = &planeStorage;
+            }
+        }
+    }
+
+    // Pin the byte[] for the duration of the gate evaluate.  Use
+    // GetPrimitiveArrayCritical (zero-copy, JVM pins the GC) over
+    // GetByteArrayElements (may copy on some VMs) because at 30-60
+    // Hz of 2 MB Y-planes, the copy cost adds up.  Evaluate is
+    // ~1-5 ms so the pin window is short.  Always paired with
+    // ReleasePrimitiveArrayCritical even on the error paths below.
+    retailens::KeyframeGateDecision d;
+    if (grayBytes && grayWidth > 0 && grayHeight > 0 && grayStride >= grayWidth) {
+        void* raw = env->GetPrimitiveArrayCritical(grayBytes, nullptr);
+        if (raw) {
+            d = gate(handle)->evaluateWithFrame(
+                pose, planePtr,
+                static_cast<const uint8_t*>(raw),
+                static_cast<int32_t>(grayWidth),
+                static_cast<int32_t>(grayHeight),
+                static_cast<int32_t>(grayStride));
+            env->ReleasePrimitiveArrayCritical(grayBytes, raw, JNI_ABORT);
+        } else {
+            // GetPrimitiveArrayCritical failed (rare, but defensive).
+            // Fall back to pose-only path so we degrade gracefully
+            // rather than crashing the whole capture pipeline.
+            d = gate(handle)->evaluate(pose, planePtr);
+        }
+    } else {
+        // Caller passed null / invalid dims — defensive fall-through
+        // to pose-only path (matches the C++ side's own defensive
+        // fallback in evaluateWithFrame when grayData == nullptr).
+        d = gate(handle)->evaluate(pose, planePtr);
+    }
+
+    jdoubleArray out = env->NewDoubleArray(5);
+    jdouble values[5];
+    values[0] = d.accept ? 1.0 : 0.0;
+    values[1] = static_cast<jdouble>(static_cast<int32_t>(d.reason));
+    values[2] = d.newContentFraction;
+    values[3] = static_cast<jdouble>(d.acceptedCount);
+    values[4] = static_cast<jdouble>(d.maxCount);
+    env->SetDoubleArrayRegion(out, 0, 5, values);
+    return out;
+}
+
 } // extern "C"