react-native-image-stitcher 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -16,6 +16,515 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-05-23
+
+### v0.4 settings revamp (F10)
+
+> [!WARNING]
+> **Breaking type change.**  The flat 45-field `PanoramaSettings`
+> interface from v0.3 has been replaced with three engine-discriminated
+> hierarchical types (`PanoramaSettings`, `SlitscanSettings`,
+> `HybridSettings`).  Consumers passing custom settings literals to
+> `<Camera>` or to a Layer 2 modal must migrate to the new shape; the
+> v0.3 type is deleted, not aliased.  The C++ engine wire format is
+> unchanged — only the JS-side type surface moved.
+>
+> **Migration guide:** [`docs/migrations/v0.3-to-v0.4-panorama-settings.md`](docs/migrations/v0.3-to-v0.4-panorama-settings.md)
+> walks through every recipe (default-only hosts, custom-literal
+> hosts, slit-scan / hybrid hosts, storage migration for persisted
+> settings).
+
+#### Why
+
+The 2026-05-22 audit (entry below in v0.3.0) traced every
+`PanoramaSettings` field's native consumer and proved the flat type
+mixed three engines' (batch-keyframe, slit-scan, hybrid) settings into
+one bag of disjoint subsets.  Hosts had no way to know at the type
+level which settings their chosen engine would even read; the modal
+exposed knobs that were silently ignored on the active engine.  The
+revamp splits the type along engine boundaries so the types match what
+each engine actually consumes.
+
+#### What changed
+
+- **New file:** `src/camera/PanoramaSettings.ts` — `CaptureBaseSettings`
+  + three top-level types (`PanoramaSettings`, `SlitscanSettings`,
+  `HybridSettings`), each with co-located `DEFAULT_*_SETTINGS`.  Sub-trees
+  group related knobs: `stitcher` / `frameSelection.flow` (panorama);
+  `painting` / `registration.ncc1d` / `registration.ncc2d.emaSmoothing` /
+  `registration.ncc2d.panAxisLock` / `plane` / `advanced` (slitscan).
+- **New file:** `src/camera/PanoramaSettingsBridge.ts` — three pure
+  adapter functions (`panoramaSettingsToNativeConfig`,
+  `slitscanSettingsToNativeConfig`, `hybridSettingsToNativeConfig`)
+  that translate the typed JS tree → the flat
+  `Record<string, primitive>` the native bridges consume.  Handles
+  presence-as-enable (`ncc1d` defined ⇒ `enable1dNcc: true` on the
+  wire) and source-conditional plane optionals.
+- **New file:** `src/camera/buildPanoramaInitialSettings.ts` — pure
+  helper that translates `<Camera>`'s `default*` props into the
+  initial `PanoramaSettings` snapshot.  Takes the device's low-mem
+  classification as an argument so the function stays pure and
+  testable.
+- **Rewritten:** `src/camera/PanoramaSettingsModal.tsx` — now consumes
+  the new `PanoramaSettings` shape.  UI sections mirror the type tree
+  (Capture source, Debug, Stitcher accordion, Frame Selection
+  accordion with nested Flow tunables).  ~600 LOC smaller than v0.3
+  because dead slit-scan / hybrid / video-recording fields are gone.
+- **Rewired:** `src/camera/Camera.tsx` — settings state uses the new
+  type; `incremental.start({ config })` now passes
+  `panoramaSettingsToNativeConfig(settings)` instead of an inline flat
+  dict.  IMU translation gate reads
+  `settings.frameSelection.flow?.maxTranslationCm`.  Debug overlay
+  reads `settings.frameSelection.mode` + `settings.stitcher.stitchMode`.
+- **Updated:** `src/index.ts` — exports the new types + adapters; drops
+  the deleted v0.3 type.
+- **Test infra:** added `jest` + `ts-jest` + `@types/jest` devDeps; new
+  `jest.config.js`, `tsconfig.test.json`, `tsconfig.build.json` (the
+  latter excludes `__tests__/` from the shipped `dist/`).  19 tests
+  across two suites cover the bridge round-trips, presence-as-enable
+  cases, plane-source variants, and prop→settings-tree translation.
+
+#### Migration table — v0.3 flat → v0.4 hierarchical
+
+For `<Camera>`-consuming hosts (the only public path that took
+`PanoramaSettings` in v0.3):
+
+| v0.3 field                       | v0.4 path                                       |
+|----------------------------------|-------------------------------------------------|
+| `captureSource`                  | `captureSource` (unchanged)                     |
+| `debug`                          | `debug` (unchanged)                             |
+| `stitchMode`                     | `stitcher.stitchMode`                           |
+| `warperType`                     | `stitcher.warperType`                           |
+| `blenderType`                    | `stitcher.blenderType`                          |
+| `seamFinderType`                 | `stitcher.seamFinderType`                       |
+| `enableMaxInscribedRectCrop`     | `stitcher.enableMaxInscribedRectCrop`           |
+| `frameSelectionMode`             | `frameSelection.mode`                           |
+| `keyframeMaxCount`               | `frameSelection.maxKeyframes`                   |
+| `keyframeOverlapThreshold`       | `frameSelection.overlapThreshold`               |
+| `flowNoveltyPercentile`          | `frameSelection.flow.noveltyPercentile`         |
+| `flowEvalEveryNFrames`           | `frameSelection.flow.evalEveryNFrames`          |
+| `flowMaxTranslationCm`           | `frameSelection.flow.maxTranslationCm`          |
+| `flowMaxCorners`                 | `frameSelection.flow.maxCorners`                |
+| `flowQualityLevel`               | `frameSelection.flow.qualityLevel`              |
+| `flowMinDistance`                | `frameSelection.flow.minDistance`               |
+
+#### Deleted from the public type surface
+
+These fields were consumed only by slit-scan or hybrid engines (or
+not consumed at all per the audit) and were dead surface on
+`<Camera>`'s batch-keyframe path:
+
+- `incrementalEngine` — `<Camera>` always uses `batch-keyframe`; the
+  knob never reached this component.  Hosts that want slit-scan or
+  hybrid build their own capture flow on `incremental.start()` and
+  pass `SlitscanSettings` / `HybridSettings` instead.
+- `useARPreview` — superseded by `captureSource` ('ar' / 'non-ar').
+- `useDetectedPlane` — superseded by `SlitscanSettings.plane.source`.
+- `planeSource`, `virtualPlaneDepthMeters`, `arkitPlaneAlignmentThreshold`,
+  `planeProjectionStyle` — slit-scan only; on `SlitscanSettings.plane.*`.
+- `slitWidthFraction`, `sliverPosition`, `firstFrameFullFrame`,
+  `paintMode` — slit-scan only; on `SlitscanSettings.painting.*`.
+- `acceptGate`, `enableTriangulation`, `enableTriAccumulator`,
+  `enable2dNcc`, `enableRansacHomography`, `nccSearchRadius1d`,
+  `nccSearchMargin2d`, `nccConfidenceThreshold2d`,
+  `enableNcc2dEmaSmoothing`, `ncc2dEmaAlpha`,
+  `enableNcc2dPanAxisLock`, `ncc2dCrossAxisLockPx` — slit-scan only;
+  on `SlitscanSettings.registration.*`.
+- `hybridProjection` — hybrid only; on `HybridSettings.projection`.
+- `maxRecordingMs`, `framesPerSecond`, `minFrames`, `maxFrames`,
+  `quality` — historical video-recording fallback fields with no
+  consumer on `<Camera>`'s batch-keyframe path.
+
+#### Latent v0.3 bug fixed in passing
+
+The v0.3 `<Camera>` accepted a `defaultCaptureSource` prop but the
+internal `buildInitialSettings` function never copied it into
+`settings.captureSource` — only into `arPreference` state.  The
+discrepancy meant the wire dict sent to native always reported
+`captureSource: 'ar'` even when the operator's effective source was
+`'non-ar'`, which silently disabled Android's `disableAngularFallback`
+opt-out (audit fix F1).  v0.4's `extractPanoramaOverrides` +
+`buildPanoramaInitialSettings` route the prop through correctly.
+Hosts using `defaultCaptureSource="non-ar"` will see native receive
+the matching value for the first time.
+
+#### Known limitation — modal Capture-source field vs. AR toggle
+
+The on-screen AR toggle button at the bottom of `<Camera>` updates
+`arPreference` state (and through it `effectiveCaptureSource`),
+which decides which preview component mounts.  The Capture-source
+segmented control inside the settings modal updates
+`settings.captureSource`, which only affects what's reported to the
+native engine via `panoramaSettingsToNativeConfig` (gates Android's
+angular-fallback opt-out per audit fix F1).  These two values can
+drift if the operator toggles the AR button without re-opening
+settings, OR flips the modal field without touching the AR button.
+The on-screen toggle is the canonical UI affordance for the live
+preview path; the modal field is best thought of as a tester escape
+hatch for the wire-format consequence.  A future cleanup is to make
+both update the same source of truth — out of scope for v0.4.
+
+#### Migration example
+
+```ts
+// Before (v0.3)
+const settings: PanoramaSettings = {
+  captureSource: 'ar',
+  stitchMode: 'auto',
+  blenderType: 'multiband',
+  flowMaxTranslationCm: 50,
+  flowNoveltyPercentile: 0.85,
+  keyframeMaxCount: 6,
+  frameSelectionMode: 'flow-based',
+  // … 40+ more fields
+};
+
+// After (v0.4)
+const settings: PanoramaSettings = {
+  captureSource: 'ar',
+  debug: false,
+  stitcher: {
+    stitchMode: 'auto',
+    warperType: 'plane',
+    blenderType: 'multiband',
+    seamFinderType: 'graphcut',
+    enableMaxInscribedRectCrop: false,
+  },
+  frameSelection: {
+    mode: 'flow-based',
+    maxKeyframes: 6,
+    overlapThreshold: 0.20,
+    flow: {
+      noveltyPercentile: 0.85,
+      evalEveryNFrames: 5,
+      maxTranslationCm: 50,
+      maxCorners: 150,
+      qualityLevel: 0.01,
+      minDistance: 10,
+    },
+  },
+};
+
+// Or just use the default:
+import { DEFAULT_PANORAMA_SETTINGS } from 'react-native-image-stitcher';
+const settings = { ...DEFAULT_PANORAMA_SETTINGS, captureSource: 'non-ar' };
+```
+
+
+## [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
@@ -357,7 +866,8 @@ 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.1...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

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 |