react-native-image-stitcher 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -16,6 +16,171 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] — 2026-05-25
+
+### Added — F8.6 Android pixel-buffer engine parity
+
+Closes the v0.5.0 follow-up tracked in the [0.5.0] section.
+
+**Live engine ingest no longer requires a JPEG round-trip.**
+The `IncrementalFirstwinsEngine` (slit-scan / first-wins) and the
+hybrid `IncrementalEngine` both gained a new
+`addFramePixelData(nv21, w, h, ...)` method.  It builds the BGR
+`cv::Mat` in-process via
+`Imgproc.cvtColor(yuv, COLOR_YUV2BGR_NV21)`, then delegates to a
+newly-extracted shared `addFrameMat` helper that runs the original
+engine pipeline verbatim.  The legacy `addFrameAtPath(path, ...)`
+is now a thin wrapper: `imread → downsample → addFrameMat`.
+
+**Routing.**  `IncrementalStitcher.ingestFromARCameraView` got
+three optional parameters — `nv21PixelData: ByteArray?`,
+`nv21PixelWidth: Int`, `nv21PixelHeight: Int`.  When supplied (and
+`batchKeyframeMode == false`), the live engine ingests via
+`addFramePixelData`; otherwise falls back to `addFrameAtPath` with
+`legacyJpegPath`.  Backwards-compatible — all-null defaults
+preserve every existing caller.
+
+**Frame Processor wiring.**  `consumeFrameFromPlugin` now packs the
+incoming `Image` NV21 once at the top (was twice — gate consumed
+Y only, then the `onAccept` lambda re-packed for JPEG encode) and
+threads the bytes through to both the gate (which reads only the
+Y subset) AND the new `nv21PixelData` parameter.  Net: single
+`packNV21` per producer-thread frame.
+
+**Measured on Galaxy A35, `engine: 'firstwins-rectilinear'`,
+non-AR Frame Processor capture:**
+
+| Outcome | F8.6 pixel-data | Legacy JPEG path (estimated) |
+|---|---|---|
+| `AcceptedHigh` (first-frame init) | 7–11 ms | 50–70 ms |
+| `SkippedTooClose` (gate bail) | 0.5–2 ms | 50–60 ms (imread is unconditional) |
+
+`SkippedTooClose` dominates the producer-thread frame budget
+(~95% of frames at 30 fps with a slow pan).  Eliminating the
+imread on those frames is the bulk of the F8.6 win.
+
+### Added
+
+* New `<Camera engine={...}>` prop exposes the live engine
+  selection (`'batch-keyframe'` (default) / `'firstwins-rectilinear'`
+  / `'hybrid'` / `'slitscan-*'`).  Lets hosts opt into in-flight
+  stitching for low-latency previews; previously the choice was
+  hardcoded.
+
+### Changed
+
+* `New: F8.6 perf-diagnostic logs` (`F8.6-route`, `F8.6-perf`) fire
+  in live-engine mode only — inert under the default
+  `batch-keyframe`.  Will be removed in v0.6 once F8.6 is baked in
+  production.
+
+### Fixed
+
+* In `IncrementalStitcher.consumeFrameFromPlugin`, the `onAccept`
+  lambda was re-packing the live `Image` instead of reusing the
+  already-packed NV21 from the outer scope.  Now it reuses the
+  outer `packed` — saves a redundant `packNV21` call on every
+  accepted frame.
+
+## [0.5.0] — 2026-05-25
+
+### Added — F8 Frame Processor port
+
+`<Camera>` now drives **non-AR captures through a vision-camera
+Frame Processor** on the camera producer thread instead of the
+4 Hz `takeSnapshot` → JPEG → cache-file path the v0.4 series used.
+
+- **`useFrameProcessorDriver`** (`src/stitching/useFrameProcessorDriver.ts`)
+  — new hook with the same `{ start, stop, frameProcessor,
+  isRunning }` shape as the legacy `useIncrementalJSDriver`.  Gyro
+  yaw / pitch / **roll** are integrated on the JS thread and
+  published via `useSharedValue` so the worklet reads pose
+  zero-hop.  Plugin acquisition uses a mount-once + 16 ms
+  setTimeout retry pattern to side-step the vision-camera
+  registry init race.
+- **`cv_flow_gate_process_frame` JSI plugin** — registered on both
+  platforms:
+  - iOS: `ios/Sources/RNImageStitcher/KeyframeGateFrameProcessor.mm`
+    + `@objc IncrementalStitcher.consumeFrameFromPlugin(...)`
+    wrapper.  `CVPixelBuffer` flows end-to-end into
+    `IncrementalStitcher.consumeFrame` — the SAME entry point AR
+    mode already uses.  Zero JPEG round-trip on accept.
+  - Android: `android/src/main/java/io/imagestitcher/rn/CvFlowGateFrameProcessor.kt`
+    + Kotlin `consumeFrameFromPlugin(...)` wrapper.  Extracts the
+    Y plane on the producer thread, encodes inline JPEG on accept
+    via the existing `YuvImageConverter`, hands the path to
+    `ingestFromARCameraView`.  Pixel-buffer parity tracked as F8.6.
+- **`frameSourceMode: 'frameProcessor'`** in
+  `IncrementalStitcher.start()` options — flips
+  `frameProcessorIngestEnabled` ON so the plugin's producer-thread
+  feed reaches the engine.  Default for non-AR captures from v0.5.
+- **`legacyDriver?: boolean`** prop on `<Camera>` — opt-in escape
+  hatch back to `useIncrementalJSDriver` for hosts that hit a
+  vision-camera incompatibility.  Will be removed in v0.6.
+- **`VISION_CAMERA_RUNTIME` error code** for vision-camera
+  runtime errors that aren't transient lifecycle events.
+- **Roll axis** (gyro-Z) in the synthesised pose quaternion —
+  `q = q_yaw * q_pitch * q_roll`.  Field captures with wrist-twist
+  no longer lie to the cv::Stitcher's intrinsic estimator.
+
+### Changed
+
+- Default non-AR driver is now `useFrameProcessorDriver`.  Hosts
+  using `<Camera>` opt in transparently — no code change needed
+  unless you want the legacy path (`legacyDriver={true}`).
+- `host-supplied frameProcessor` prop on `<Camera>` is now treated
+  as a legacy escape hatch: silently overridden by the SDK driver
+  in default mode with a one-shot `console.warn`.
+
+### Deprecated
+
+- **`useIncrementalJSDriver`** — works through v0.5, removed in
+  v0.6.  Hosts that drove non-AR captures with this hook should
+  migrate to letting `<Camera>` do it by default
+  (`legacyDriver` unset).  The hook now emits a one-shot
+  `console.warn` from its `start()` call.
+
+### Fixed
+
+- **Vision-camera transient lifecycle errors** (screen-lock,
+  app-switch, DoNotDisturb, MDM camera restriction) are now
+  filtered inside `<CameraView>` instead of propagating to the
+  host's `onError`.  Auto-recovery happens on resume; hosts no
+  longer get spurious crash reports on every phone-lock.
+
+### Added — peer dependency
+
+- **`react-native-worklets-core`** is now a declared peer
+  dependency (`>=1.3.0`).  It was already required transitively
+  via `react-native-vision-camera@^4`; the explicit declaration
+  documents the contract.
+
+### Tracking — known follow-ups (don't gate this release)
+
+- **F8.6 (v0.5.1)** — Android engine refactor for pixel-buffer-
+  direct ingest (true zero-copy parity with iOS).  Would extract
+  an `addFrameMat` helper from `IncrementalFirstwinsEngine` and
+  `IncrementalEngine`'s `addFrameAtPath`, add a parallel
+  `addFramePixelData` that constructs the BGR `cv::Mat` from NV21
+  bytes via `cvtColor`, and rewire `RNSARCameraView` to skip the
+  per-frame JPEG encode.  Expected gain: ~30–50 ms per accepted
+  frame.  Deferred because the engine bodies are 400+ lines of
+  complex AR-mode code; needs A35 device verification before
+  merge, which the v0.5.0 prep session didn't have.
+
+- **F8.3-followup-roll** — resolved in v0.5.0.
+
+- **F8.3.H2-target** — RESOLVED in v0.5.0 via a different
+  mechanism than originally planned.  The selector pin is now a
+  compile-time `#selector(...)` reference inside
+  `IncrementalStitcher.swift` plus a dev-build runtime assert in
+  `IncrementalStitcher.init()` — both fire if the Swift method
+  signature drifts from what `KeyframeGateFrameProcessor.mm`
+  expects.  The obsolete test file was deleted.  `swift test` now
+  runs the (8-test) `QualityCheckerTests` suite cleanly because
+  `Package.swift` switched from an exclude list (broke every time
+  a new `.mm` landed) to an explicit `sources` allowlist.
+
 ## [0.4.1] — 2026-05-23
 
 ### Fixed

package/README.md

@@ -160,6 +160,7 @@ The component owns the runtime state; the parent persists across launches via th
 | **Android namespace** | `io.imagestitcher.rn`. |
 | **Stitching pipeline** | Shared C++ under `cpp/stitcher.cpp` invoked from both iOS Obj-C++ and Android JNI.  PANORAMA + SCANS modes; C+D progressive-confidence retry over keyframes. |
 | **Two capture-source paths** | AR uses ARKit (iOS) / ARCore (Android) pose stream.  Non-AR uses vision-camera + IMU integration via `useIMUTranslationGate`. |
+| **Frame Processor driver (v0.5+)** | Non-AR captures evaluate the keyframe gate on the camera producer thread at native frame rate via a vision-camera Frame Processor (`cv_flow_gate_process_frame`).  iOS passes `CVPixelBuffer` end-to-end; Android writes a Y-plane-derived JPEG on accept.  Opt-out via `<Camera legacyDriver />` for one minor cycle.  See `docs/f8-frame-processor-plan.md` for the design. |
 | **Two supported pan modes** | Landscape phone + vertical pan; portrait phone + horizontal pan.  Any other combination is a user deviation, not a supported mode. |
 
 ## License

package/android/build.gradle

@@ -215,6 +215,39 @@ dependencies {
     // on demand (~30 MB) the first time the user opens an AR
     // capture screen on a supported device.
     implementation "com.google.ar:core:1.45.0"
+
+    // F8.4 — vision-camera as a compile-time peer dep.  Same
+    // `compileOnly` pattern as React Native above: host apps that
+    // wire `<Camera>` already include the autolinked
+    // `:react-native-vision-camera` Gradle project; we just need
+    // `com.mrousavy.camera.frameprocessors.*` types on the compile
+    // classpath to build `CvFlowGateFrameProcessor.kt` + the
+    // registration in `RNImageStitcherPackage`.  Runtime
+    // resolution is the host's responsibility —
+    // `RNImageStitcherPackage`'s static initialiser catches
+    // `NoClassDefFoundError` so the SDK still loads if a non-
+    // camera consumer omits the dep.
+    //
+    // `findProject(...)` guard: lets the SDK still compile in
+    // hosts that haven't installed react-native-vision-camera.
+    // The plugin file's import resolution will fail in that case,
+    // which is fine — we conditionally exclude the plugin sources
+    // below.
+    if (findProject(':react-native-vision-camera') != null) {
+        compileOnly project(':react-native-vision-camera')
+        // CameraX `ImageProxy` / `ImageInfo` types — vision-camera
+        // exposes them through `Frame.getImageProxy()` and we need
+        // the compile-time class for `imageInfo.rotationDegrees`.
+        // `compileOnly` because the host app already ships these via
+        // vision-camera's transitive runtime dep.
+        compileOnly "androidx.camera:camera-core:1.5.0-alpha03"
+    } else {
+        // Without vision-camera on the classpath the Frame
+        // Processor plugin source can't compile (imports unresolved).
+        // Exclude it from the source set so the rest of the SDK
+        // still builds for non-camera consumers.
+        android.sourceSets.main.java.exclude '**/CvFlowGateFrameProcessor.kt'
+    }
 }
 
 // Helper from the React Native gradle convention to read host-app

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

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: Apache-2.0
+package io.imagestitcher.rn
+
+import android.media.Image
+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
+
+/**
+ * F8.4 — Android vision-camera Frame Processor plugin that mirrors
+ * iOS' `KeyframeGateFrameProcessor.mm`.
+ *
+ * Plugin name (must match the iOS plugin):
+ *   `cv_flow_gate_process_frame`
+ *
+ * JS-side usage is identical to iOS — the same `useFrameProcessorDriver`
+ * hook + the same `plugin.call(frame, args)` contract.  The JS layer
+ * is 100% platform-agnostic.
+ *
+ * ## What this plugin does
+ *
+ * Per producer-thread frame:
+ *   1. Pull the `android.media.Image` out of vision-camera's `Frame`.
+ *   2. Extract pose primitives from the worklet's `params` dict
+ *      (defaults safe for non-AR: tx/ty/tz=0, qw=1 identity, fx/fy=0
+ *      → engine uses 65°×50° FoV fallback).
+ *   3. Call `IncrementalStitcher.consumeFrameFromPlugin(image, …)`
+ *      which:
+ *        - Drops the call if `frameSourceMode != "frameProcessor"`
+ *          (prevents double-feeding the engine alongside the legacy
+ *          `processFrameAtPath` path).
+ *        - Otherwise: extracts the Y plane, evaluates the keyframe
+ *          gate via `KeyframeGate.evaluateWithFrame`, encodes the
+ *          accepted frame to JPEG synchronously, and hands the path
+ *          to the existing `ingestFromARCameraView` engine entry.
+ *
+ * ## Lifetime / threading
+ *
+ * The `Frame` (and the underlying `Image` / `ImageProxy`) is valid
+ * only for the duration of this callback — vision-camera closes it
+ * on return.  All Image access (including the JPEG encode on
+ * accept) MUST happen synchronously inside `callback()`.
+ *
+ * ## Divergence vs iOS
+ *
+ * iOS keeps the `CVPixelBuffer` reachable end-to-end into the
+ * stitcher engine (zero-copy).  Android's engine entry point
+ * (`ingestFromARCameraView`) takes a Y `ByteArray` + a JPEG file
+ * path, so we copy Y bytes here and encode JPEG inline on accept.
+ * Cross-platform parity at the engine level is tracked as F8.6.
+ *
+ * ## Registration
+ *
+ * Registered in `RNImageStitcherPackage.kt`'s companion-object
+ * static initialiser via `FrameProcessorPluginRegistry`.  Vision-
+ * camera docs say "should be called as soon as possible — ideally
+ * on app start or in a static initialiser"; the package class is
+ * loaded by RN autolinking at app startup, so the registration
+ * fires before any JS Frame Processor can `initFrameProcessorPlugin`
+ * the plugin.
+ */
+@DoNotStrip
+@Keep
+class CvFlowGateFrameProcessor(
+    proxy: VisionCameraProxy,
+    options: Map<String, Any>?,
+) : FrameProcessorPlugin() {
+
+    // The `proxy` and `options` are accepted by the
+    // `PluginInitializer` contract but the plugin is stateless —
+    // all gate tunables live on `IncrementalStitcher` and are
+    // configured at its `start()` time from the host-app settings.
+    // The plugin is a thin pose-injector.
+    //
+    // Lint suppressors: we intentionally don't read these.
+    @Suppress("unused", "UNUSED_PARAMETER")
+    private val unused = proxy to options
+
+    @Suppress("UNCHECKED_CAST")
+    override fun callback(frame: Frame, params: Map<String, Any>?): Any? {
+        // Frame may throw `FrameInvalidError` if vision-camera has
+        // already released it.  Defensive: swallow and return.
+        val image: Image = try {
+            frame.image
+        } catch (e: Throwable) {
+            return mapOf("submitted" to false, "error" to "frame invalid")
+        }
+
+        val stitcher = IncrementalStitcher.bridgeInstance
+        if (stitcher == null) {
+            // Module never registered (host hasn't initialised the
+            // React bridge yet, or autolinking skipped us).  Drop
+            // the call; JS sees `submitted: false` and can detect.
+            return mapOf("submitted" to false, "error" to "stitcher not registered")
+        }
+
+        // F8.4-Android-c rotation fix: read CameraX's authoritative
+        // "rotation needed to display upright" value via
+        // `imageProxy.imageInfo.rotationDegrees`.
+        //
+        // The earlier attempt used `Frame.orientation` (the enum),
+        // but vision-camera's `getOrientation()` returns the REVERSE
+        // of the rotation-needed value (see Frame.java:88, the
+        // "Reverse it" comment).  Trying to invert the enum
+        // ourselves was off by 90° on the A35.  The raw
+        // `imageInfo.rotationDegrees` is unambiguous.
+        //
+        // Used by the engine's JPEG encoder to write the correct
+        // EXIF Orientation tag so thumbnails (and any other
+        // EXIF-honoring viewer) display upright.  The raw cv::Mat
+        // the stitcher sees is unaffected — see consumeFrameFromPlugin
+        // docstring for the no-double-rotation rationale.
+        val sensorRotationDegrees = try {
+            frame.imageProxy.imageInfo.rotationDegrees
+        } catch (_: Throwable) {
+            // FrameInvalidError or null mid-callback — treat as
+            // portrait back-camera default (sensor mounted 90° CW).
+            90
+        }
+
+        stitcher.consumeFrameFromPlugin(
+            image = image,
+            tx = argDouble(params, "tx", 0.0),
+            ty = argDouble(params, "ty", 0.0),
+            tz = argDouble(params, "tz", 0.0),
+            qx = argDouble(params, "qx", 0.0),
+            qy = argDouble(params, "qy", 0.0),
+            qz = argDouble(params, "qz", 0.0),
+            qw = argDouble(params, "qw", 1.0),
+            fx = argDouble(params, "fx", 0.0),
+            fy = argDouble(params, "fy", 0.0),
+            cx = argDouble(params, "cx", image.width / 2.0),
+            cy = argDouble(params, "cy", image.height / 2.0),
+            timestampMs = argDouble(params, "timestampMs", 0.0),
+            // Default 2 == `.tracking` so the worklet doesn't need
+            // to send a tracking-state field on every frame.
+            trackingStateRaw = argInt(params, "trackingStateRaw", 2),
+            sensorRotationDegrees = sensorRotationDegrees,
+        )
+
+        return mapOf("submitted" to true)
+    }
+
+    private fun argDouble(args: Map<String, Any>?, key: String, default: Double): Double {
+        if (args == null) return default
+        val v = args[key] ?: return default
+        return when (v) {
+            is Number -> v.toDouble()
+            else -> default
+        }
+    }
+
+    private fun argInt(args: Map<String, Any>?, key: String, default: Int): Int {
+        if (args == null) return default
+        val v = args[key] ?: return default
+        return when (v) {
+            is Number -> v.toInt()
+            else -> default
+        }
+    }
+}

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

@@ -197,7 +197,155 @@ internal class IncrementalFirstwinsEngine(
         }
         val frameBGR = downsampleToCompose(srcRaw)
         if (frameBGR !== srcRaw) srcRaw.release()
+        val tele = addFrameMat(
+            frameBGR,
+            qx, qy, qz, qw,
+            fx, fy, cx, cy,
+            imageWidth, imageHeight,
+            yaw, pitch,
+            fovHorizDegrees, fovVertDegrees,
+            t0,
+        )
+        f8_6_logPerf("firstwins/jpeg", t0, tele.outcome)
+        return tele
+    }
+
+    /**
+     * F8.6 — pixel-data twin of [addFrameAtPath].  Accepts the
+     * camera frame as an NV21 byte buffer instead of a JPEG file
+     * path; skips the JPEG decode round-trip (~30–50 ms per
+     * accepted frame on a mid-tier device).
+     *
+     * Use this from the vision-camera Frame Processor path (where
+     * we already have direct producer-thread access to YUV bytes)
+     * and from the ARCore path (where the previous
+     * JPEG-encode-on-every-frame in `RNSARCameraView` was a
+     * measurable hot-spot).
+     *
+     * The body matches [addFrameAtPath] one-for-one except for the
+     * Mat construction: an `Mat(h*3/2, w, CV_8UC1)` wraps the
+     * NV21 bytes, then `Imgproc.cvtColor` produces the BGR Mat the
+     * engine pipeline already expects.  Everything downstream is
+     * the shared [addFrameMat] helper.
+     *
+     * `nv21Width`/`nv21Height` describe the buffer's actual
+     * dimensions.  `imageWidth`/`imageHeight` describe the
+     * camera's reported sensor dims used for intrinsics scaling —
+     * these can differ when the camera is downsampling for Frame
+     * Processor output.
+     */
+    fun addFramePixelData(
+        nv21: ByteArray,
+        nv21Width: Int,
+        nv21Height: Int,
+        qx: Double, qy: Double, qz: Double, qw: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        imageWidth: Int, imageHeight: Int,
+        yaw: Double, pitch: Double,
+        fovHorizDegrees: Double, fovVertDegrees: Double,
+        trackingPoor: Boolean,
+    ): FrameTelemetry {
+        val t0 = System.nanoTime()
+        if (trackingPoor) {
+            return FrameTelemetry(
+                FrameOutcome.SkippedTrackingPoor, -1.0, 0, yaw, pitch,
+                msSince(t0),
+                isLandscape = isLandscape,
+            )
+        }
+        // NV21 layout: Y plane (w*h bytes) + interleaved VU
+        // (w*h/2 bytes).  A single CV_8UC1 Mat of height h*3/2
+        // packs the whole thing; cvtColor with COLOR_YUV2BGR_NV21
+        // does the planar-aware decode in one call.
+        //
+        // F8.6 IS-1 — length guard.  If the caller supplied a
+        // short buffer, `yuv.put(0,0,nv21)` would copy only
+        // `nv21.size` bytes and leave the rest zero-init; cvtColor
+        // would then read stale/zero UV and produce silently
+        // corrupt colour.  Fail fast instead.
+        val expectedBytes = nv21Width * nv21Height * 3 / 2
+        require(nv21.size >= expectedBytes) {
+            "addFramePixelData: nv21 buffer too small " +
+                "(${nv21.size} bytes < $expectedBytes for " +
+                "${nv21Width}x${nv21Height})"
+        }
+        val yuv = Mat(nv21Height + nv21Height / 2, nv21Width, CvType.CV_8UC1)
+        yuv.put(0, 0, nv21)
+        val srcRaw = Mat()
+        Imgproc.cvtColor(yuv, srcRaw, Imgproc.COLOR_YUV2BGR_NV21)
+        yuv.release()
+        if (srcRaw.empty()) {
+            return FrameTelemetry(
+                FrameOutcome.RejectedAlignmentLost, -1.0, 0, yaw, pitch,
+                msSince(t0),
+                isLandscape = isLandscape,
+            )
+        }
+        val frameBGR = downsampleToCompose(srcRaw)
+        if (frameBGR !== srcRaw) srcRaw.release()
+        val tele = addFrameMat(
+            frameBGR,
+            qx, qy, qz, qw,
+            fx, fy, cx, cy,
+            imageWidth, imageHeight,
+            yaw, pitch,
+            fovHorizDegrees, fovVertDegrees,
+            t0,
+        )
+        f8_6_logPerf("firstwins/pixel", t0, tele.outcome)
+        return tele
+    }
 
+    /**
+     * F8.6 perf-diagnostic counter.  Logs ingest timing every Nth
+     * call so a single capture session yields enough samples to
+     * eyeball the JPEG-path vs pixel-data-path delta.  Remove this
+     * once F8.6 is verified in production.
+     */
+    @Volatile private var f8_6_perfCallCounter: Long = 0L
+    private fun f8_6_logPerf(
+        path: String,
+        t0Nanos: Long,
+        outcome: FrameOutcome,
+    ) {
+        val n = ++f8_6_perfCallCounter
+        // Every 5th call ≈ ~1 line/sec at 5 Hz live-engine rate;
+        // first call always logs so we see something on capture
+        // start without waiting.
+        if (n == 1L || n % 5L == 0L) {
+            Log.i(
+                "F8.6-perf",
+                "$path took ${msSince(t0Nanos)}ms outcome=$outcome (call #$n)",
+            )
+        }
+    }
+
+    /**
+     * F8.6 — the body extracted from [addFrameAtPath].  Takes a
+     * BGR `Mat` (downsampled to compose dims) and runs the full
+     * engine pipeline: first-frame init or subsequent-frame paste
+     * via either rectilinear or cylindrical warp.
+     *
+     * Behaviour is identical to the pre-F8.6 `addFrameAtPath`
+     * (the body is a verbatim move).  Both `addFrameAtPath` and
+     * `addFramePixelData` delegate here after their respective
+     * Mat constructions.
+     */
+    private fun addFrameMat(
+        frameBGR: Mat,
+        qx: Double, qy: Double, qz: Double, qw: Double,
+        fx: Double, fy: Double, cx: Double, cy: Double,
+        imageWidth: Int, imageHeight: Int,
+        yaw: Double, pitch: Double,
+        // FOV params kept for symmetry with `IncrementalEngine.addFrameMat`
+        // (the hybrid engine, which uses them in `computeOverlapPct`).
+        // The firstwins/slit-scan engine here doesn't consume them —
+        // its paste decision is driven by pose-projected pixel
+        // displacement, not FoV-overlap percent.
+        @Suppress("UNUSED_PARAMETER") fovHorizDegrees: Double,
+        @Suppress("UNUSED_PARAMETER") fovVertDegrees: Double,
+        t0: Long,
+    ): FrameTelemetry {
         val rNew = quaternionToRotationMat(qx, qy, qz, qw)
 
         if (!hasFirstFrame) {