react-native-image-stitcher 0.15.1 → 0.16.0

package/src/index.ts

@@ -28,6 +28,7 @@ export { Camera, CameraError } from './camera/Camera';
 export type {
   CameraProps,
   CameraCaptureResult,
+  PanoramaCaptureResult,
   CameraErrorCode,
   CaptureSource,
   CaptureSourcesMode,
@@ -38,12 +39,29 @@ export type {
   Warper,
   FramesDroppedInfo,
 } from './camera/Camera';
+// Non-fatal capture quality signals carried on `CameraCaptureResult.warnings`.
+export type {
+  CaptureWarning,
+  CaptureWarningCode,
+  CaptureWarningCopy,
+} from './camera/captureWarnings';
+// Default English warning templates (single source of truth; re-used by
+// `DEFAULT_GUIDANCE_COPY`).  Exposed so a host can diff / extend them.
+export { DEFAULT_CAPTURE_WARNING_COPY } from './camera/captureWarnings';
 
 // Recoverable-stitch-failure → friendly Alert copy.  Hosts call this in
 // their onError handler to surface actionable guidance ("pan more slowly",
-// "pivot in place") instead of the raw cv::Stitcher diagnostic.
-export { userFacingStitchError } from './camera/cameraErrorMessages';
-export type { UserFacingStitchError } from './camera/cameraErrorMessages';
+// "pivot in place") instead of the raw cv::Stitcher diagnostic.  Pass an
+// `overrides` map (keyed by `RECOVERABLE_STITCH_CODES`) to localise it.
+export {
+  userFacingStitchError,
+  RECOVERABLE_STITCH_GUIDANCE,
+  RECOVERABLE_STITCH_CODES,
+} from './camera/cameraErrorMessages';
+export type {
+  UserFacingStitchError,
+  UserFacingStitchErrorOverrides,
+} from './camera/cameraErrorMessages';
 
 // ─────────────────────────────────────────────────────────────────────
 // AR foundation (public since 0.1.0)
@@ -174,6 +192,51 @@ export type { UseOrientationDriftReturn } from './camera/useOrientationDrift';
 export { OrientationDriftModal } from './camera/OrientationDriftModal';
 export type { OrientationDriftModalProps } from './camera/OrientationDriftModal';
 
+// ── Panorama capture GUIDANCE (feature/pano-ux-guidance) ──────────────
+// The first-time-user pan-capture guidance surfaces, wired into Layer-1
+// <Camera> automatically (panMode / panGuidance / maxPanDurationMs /
+// lateralBudgetCm / rectCrop / showPreview / guidanceCopy props).  Exported for
+// Layer-2 hosts composing their own capture UX on CameraView + the
+// incremental engine.
+//
+// `PanMode` is the landscape-only-vs-both flag; `GuidanceCopy` +
+// `DEFAULT_GUIDANCE_COPY` are the overridable copy surface.
+export type { PanMode } from './camera/panModeGate';
+export {
+  DEFAULT_GUIDANCE_COPY,
+} from './camera/cameraGuidanceCopy';
+export type { GuidanceCopy } from './camera/cameraGuidanceCopy';
+// Shared motion hook — one gyro + one accelerometer subscription feeding
+// the pan-speed bucket (item 4) and the lateral-drift latch (item 6).
+export { usePanMotion } from './camera/usePanMotion';
+export type {
+  UsePanMotionOptions,
+  UsePanMotionReturn,
+  PanSpeedBucket,
+  PanAxis,
+} from './camera/usePanMotion';
+// Presentational guidance surfaces (each renders null when not visible).
+export { RotateToLandscapePrompt } from './camera/RotateToLandscapePrompt';
+export type { RotateToLandscapePromptProps } from './camera/RotateToLandscapePrompt';
+export { PanHowToOverlay } from './camera/PanHowToOverlay';
+export type { PanHowToOverlayProps } from './camera/PanHowToOverlay';
+export { CaptureCountdownOverlay } from './camera/CaptureCountdownOverlay';
+export type { CaptureCountdownOverlayProps } from './camera/CaptureCountdownOverlay';
+export { CaptureFrameCounterOverlay } from './camera/CaptureFrameCounterOverlay';
+export type { CaptureFrameCounterOverlayProps } from './camera/CaptureFrameCounterOverlay';
+export { LateralMotionModal } from './camera/LateralMotionModal';
+export type { LateralMotionModalProps } from './camera/LateralMotionModal';
+export { RectCropPreview } from './camera/RectCropPreview';
+export type {
+  RectCropPreviewProps,
+  RectCropResult,
+  ImageRect,
+} from './camera/RectCropPreview';
+// Native perspective-rectify crop used by RectCropPreview's confirm
+// path; hosts driving their own crop UI call it directly.
+export { cropQuad } from './stitching/cropQuad';
+export type { CropQuadOptions, CropQuadResult } from './stitching/cropQuad';
+
 // ── Incremental stitching engine ──────────────────────────────────────
 // JS bindings around the native `IncrementalStitcher` module.  Use
 // these when you need finer control than <Camera>'s built-in

package/src/stitching/computeInscribedRect.ts

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * computeInscribedRect — resolve the largest axis-aligned rectangle that
+ * fits entirely inside the non-black (coverage) region of a stitched
+ * panorama, via native `BatchStitcher.computeInscribedRect`.
+ *
+ * Used to SEED the post-capture crop editor (`RectCropPreview`): instead of
+ * a blind 8 %-inset rectangle, the editor opens on the max-inscribed rect —
+ * the tightest clean rectangle with no black corners — which the user then
+ * fine-tunes.  Best-effort: callers fall back to the default inset seed if
+ * the native module is absent or the call rejects.
+ *
+ * Same native module + defensive-availability posture as
+ * `src/stitching/cropQuad.ts` and `src/quality/normaliseOrientation.ts`.
+ * The native side (Android `BatchStitcher.computeInscribedRect`, iOS
+ * `OpenCVStitcher.computeInscribedRect`) is the exact `maxInscribedRectFromMask`
+ * port used by the opt-in auto-crop, so the seed matches what that crop would
+ * pick — only here the user can then drag outward to keep more content.
+ */
+
+import { NativeModules } from 'react-native';
+
+
+/** Resolved max-inscribed rectangle, in image-pixel coords. */
+export interface InscribedRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  /** Intrinsic dimensions of the source image the rect was computed on. */
+  imageWidth: number;
+  imageHeight: number;
+}
+
+/** The shape of the native module method we call. */
+interface InscribedRectNativeModule {
+  computeInscribedRect: (options: {
+    imagePath: string;
+  }) => Promise<InscribedRect>;
+}
+
+
+/**
+ * Resolve the native `computeInscribedRect` function off
+ * `NativeModules.BatchStitcher`, or `null` when the module / method isn't
+ * registered (e.g. an older native build).
+ */
+function resolveComputeInscribedRect():
+  | InscribedRectNativeModule['computeInscribedRect']
+  | null {
+  const native: unknown =
+    (NativeModules as Record<string, unknown>)['BatchStitcher'];
+  if (
+    native
+    && typeof native === 'object'
+    && typeof (native as { computeInscribedRect?: unknown })
+      .computeInscribedRect === 'function'
+  ) {
+    return (native as InscribedRectNativeModule).computeInscribedRect;
+  }
+  return null;
+}
+
+
+/**
+ * Compute the max-inscribed rectangle of `imagePath`'s coverage mask.
+ *
+ * @param imagePath  file:// URI or bare path of the stitched image (the
+ *                   native side strips the scheme).
+ * @returns the inscribed rect, or `null` when the native module isn't
+ *   registered (older native build) — callers then fall back to the default
+ *   seed.  REJECTS only if the native call itself errors (decode / read
+ *   failure); callers should catch and treat the rejection as "no seed".
+ */
+export async function computeInscribedRect(
+  imagePath: string,
+): Promise<InscribedRect | null> {
+  const fn = resolveComputeInscribedRect();
+  if (!fn) return null;
+  return fn({ imagePath });
+}

package/src/stitching/cropQuad.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * cropQuad — item-7 perspective crop: rectify a user-dragged
+ * quadrilateral to an upright rectangle.
+ *
+ * The post-capture crop editor (`src/camera/RectCropPreview.tsx`) lets the
+ * user drag 4 independent corners over the stitched result.  When that
+ * quad isn't ~axis-aligned, the host calls THIS wrapper instead of the
+ * cheap `cropToRect`: it hands the 4 IMAGE-PIXEL corners to the native
+ * `BatchStitcher.cropToQuad`, which runs
+ * `cv::getPerspectiveTransform` + `cv::warpPerspective` to produce an
+ * upright rectangle (averaged opposite-edge dimensions) and overwrites the
+ * file in place.
+ *
+ * This is the typed twin of the `cropToRect` call in
+ * `example/InscribedRectDebug.tsx` — same native module (`BatchStitcher`),
+ * same in-place overwrite + `{ width, height }` result contract, same
+ * platform-availability fallback posture as
+ * `src/quality/normaliseOrientation.ts`.
+ *
+ * Corner-order contract: `quadImagePoints` MUST be in canonical
+ * [TL, TR, BR, BL] (clockwise from top-left) order — exactly what
+ * `cropGeometry.ts:orderQuadCorners` produces and `RectCropResult.quad`
+ * carries.  The native side rectifies into a rectangle whose corners map
+ * TL→(0,0), TR→(w,0), BR→(w,h), BL→(0,h); pass un-ordered points and the
+ * output is mirrored / rotated.
+ */
+
+import { NativeModules, Platform } from 'react-native';
+
+import type { Point, Quad } from '../camera/cropGeometry';
+
+
+/** Options for {@link cropQuad}. */
+export interface CropQuadOptions {
+  /**
+   * JPEG quality for the re-encoded output, 1–100.  Defaults to 90 (the
+   * native default, matching `cropToRect`).
+   */
+  quality?: number;
+}
+
+/** Resolved result of a successful {@link cropQuad}. */
+export interface CropQuadResult {
+  /**
+   * The file the rectified image was written to.  Equals the input
+   * `imagePath` (the native crop overwrites in place) — surfaced
+   * explicitly so callers don't have to assume the in-place contract.
+   */
+  outputPath: string;
+  /** Width of the rectified rectangle, in pixels. */
+  width: number;
+  /** Height of the rectified rectangle, in pixels. */
+  height: number;
+}
+
+
+/** The shape of the native module method we call. */
+interface CropQuadNativeModule {
+  cropToQuad: (options: {
+    imagePath: string;
+    quad: number[];
+    quality: number;
+  }) => Promise<{ width: number; height: number }>;
+}
+
+
+/**
+ * Resolve the native `cropToQuad` function off `NativeModules.BatchStitcher`,
+ * or `null` when the module / method isn't registered (e.g. an older native
+ * build).  Same defensive lookup as `normaliseOrientation`.
+ */
+function resolveCropToQuad(): CropQuadNativeModule['cropToQuad'] | null {
+  const native: unknown =
+    (NativeModules as Record<string, unknown>)['BatchStitcher'];
+  if (
+    native
+    && typeof native === 'object'
+    && typeof (native as { cropToQuad?: unknown }).cropToQuad === 'function'
+  ) {
+    return (native as CropQuadNativeModule).cropToQuad;
+  }
+  return null;
+}
+
+
+/**
+ * Flatten the 4 ordered ([TL, TR, BR, BL]) image-pixel corners into the
+ * `[tlX, tlY, trX, trY, brX, brY, blX, blY]` array the native module
+ * expects.  Exported for unit tests + reuse.
+ */
+export function flattenQuad(quad: Quad): number[] {
+  const out: number[] = [];
+  for (const p of quad as ReadonlyArray<Point>) {
+    out.push(p.x, p.y);
+  }
+  return out;
+}
+
+
+/**
+ * Perspective-rectify `quadImagePoints` out of `imagePath` into an upright
+ * rectangle, overwriting the file in place, and resolve the output path +
+ * rectified dimensions.
+ *
+ * @param imagePath        file:// URI (or bare path) of the image to crop.
+ * @param quadImagePoints  the 4 corners in IMAGE-PIXEL space, canonically
+ *                         ordered [TL, TR, BR, BL] (use
+ *                         `orderQuadCorners`).  This is exactly
+ *                         `RectCropResult.quad`.
+ * @param outPath          where to write the result.  The native crop
+ *                         OVERWRITES IN PLACE, so this currently MUST equal
+ *                         `imagePath` (or be omitted — defaults to it).
+ *                         Passing a different path throws, surfacing the
+ *                         limitation rather than silently ignoring it; see
+ *                         the integrator note in the item-7 handoff.
+ * @param opts             optional `{ quality }`.
+ *
+ * @throws if the native module isn't registered, if `outPath` differs from
+ *         `imagePath`, or if the native crop rejects (degenerate quad,
+ *         canvas guard, write failure).
+ */
+export async function cropQuad(
+  imagePath: string,
+  quadImagePoints: Quad,
+  outPath?: string,
+  opts?: CropQuadOptions,
+): Promise<CropQuadResult> {
+  if (outPath !== undefined && outPath !== imagePath) {
+    // The native cropToQuad (like cropToRect) only overwrites in place.
+    // Fail loudly rather than silently writing to imagePath and returning
+    // a path the file isn't at.
+    throw new Error(
+      '[capture-sdk] cropQuad: native crop overwrites in place; '
+      + 'outPath must equal imagePath (or be omitted).',
+    );
+  }
+
+  const fn = resolveCropToQuad();
+  if (!fn) {
+    throw new Error(
+      `[capture-sdk] cropQuad: native module BatchStitcher.cropToQuad not `
+      + `available on ${Platform.OS}.  Ensure the native module is registered.`,
+    );
+  }
+
+  const quality = clampQuality(opts?.quality);
+  const dims = await fn({
+    imagePath,
+    quad: flattenQuad(quadImagePoints),
+    quality,
+  });
+  return {
+    outputPath: imagePath,
+    width: dims.width,
+    height: dims.height,
+  };
+}
+
+
+/** Clamp the requested JPEG quality into [1, 100]; default 90. */
+function clampQuality(quality?: number): number {
+  if (quality === undefined || Number.isNaN(quality)) return 90;
+  if (quality < 1) return 1;
+  if (quality > 100) return 100;
+  return Math.round(quality);
+}

package/src/stitching/incremental.ts

@@ -682,6 +682,33 @@ export interface IncrementalFinalizeResult {
    * on the just-completed capture.
    */
   stitchModeResolved?: 'panorama' | 'scans';
+  /**
+   * 2026-06-14 (DEV overlay) — a semicolon-separated `key=value` trace of the
+   * stitcher's RUNTIME choices for this output, e.g.
+   * `"pipe=manual;warp=spherical;route=batch;seam=graphcut;blend=multiband"`.
+   *   pipe:  `manual` (cv::detail) | `highlevel` (cv::Stitcher)
+   *   warp:  `plane` | `cylindrical` | `spherical`
+   *   route: `batch` (warp-all + seam) | `stream` (low-memory per-frame)
+   *   seam:  `graphcut` | `none`
+   *   blend: `multiband` | `feather`
+   * Intended for a __DEV__-only overlay so the operator can see HOW the
+   * panorama was built (which warper, whether the low-memory stream/feather
+   * fallback kicked in, etc.).  iOS only for now; undefined elsewhere.
+   */
+  debugSummary?: string;
+  /**
+   * 2026-06-15 (iOS) — the exact keyframe JPEG paths used for this stitch.
+   * Lets the host re-stitch the SAME frames on demand via `refinePanorama`
+   * (e.g. the high-level preview tab) without re-running the capture or
+   * enumerating the session directory.  iOS only; undefined elsewhere.
+   */
+  batchKeyframePaths?: string[];
+  /**
+   * 2026-06-15 (iOS) — the capture orientation this stitch baked into the
+   * output.  An on-demand re-stitch (refinePanorama) MUST pass this back or the
+   * result comes out in the raw sensor landscape (sideways).  iOS only.
+   */
+  captureOrientation?: string;
 }
 
 
@@ -750,6 +777,15 @@ export interface IncrementalRefineOptions {
   stitchMode?: 'auto' | 'panorama' | 'scans';
   /** JPEG quality 1..100, default 90. */
   jpegQuality?: number;
+  /**
+   * 2026-06-15 (iOS) — which stitch pipeline to run.  `true` = the manual
+   * `cv::detail` pipeline (the default batch-capture output); `false` = stock
+   * high-level `cv::Stitcher`.  Default `false` on the refine path.  This is
+   * how the on-demand "high-level" preview tab re-stitches the captured
+   * keyframes via cv::Stitcher without re-running the whole capture.  iOS only
+   * (Android refine is always cv::Stitcher).
+   */
+  useManualPipeline?: boolean;
 }
 
 
@@ -771,6 +807,15 @@ export interface IncrementalRefineResult {
   framesDropped: number;
   /** The confidence threshold that succeeded.  -1 when not applicable. */
   finalConfidenceThresh: number;
+  /**
+   * 2026-06-15 (DEV overlay A/B-aware) — the stitcher's own semicolon-separated
+   * `key=value` runtime recipe for THIS refined output, e.g.
+   * `"pipe=highlevel;warp=spherical;route=batch;seam=graphcut;blend=multiband"`.
+   * Mirrors `IncrementalFinalizeResult.debugSummary`.  Lets the on-demand
+   * high-level preview tab show its OWN recipe in the __DEV__ overlay pill
+   * instead of the manual primary's recipe.  iOS only; undefined elsewhere.
+   */
+  debugSummary?: string;
 }
 
 

package/cpp/tests/CMakeLists.txt

@@ -1,104 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-#
-# cpp/tests/CMakeLists.txt — v0.10.0 audit #9A
-#
-# Standalone Google Test runner for the shared C++ port under `cpp/`.
-# Build + run via:
-#
-#     cmake -S cpp/tests -B build/cpp-tests
-#     cmake --build build/cpp-tests
-#     (cd build/cpp-tests && ctest --output-on-failure)
-#
-# Or, from the repo root: `scripts/run-cpp-tests.sh`.
-#
-# What this DOES test:
-#   - Pure-C++ types in cpp/: `Pose`, `PlaneTransform`,
-#     `StitcherFrameData`, `PixelBufferReader` interface contract.
-#   - `timeBudgetCrossed` — the keyframe gate's OpenCV-free time-budget
-#     force-accept predicate (keyframe_timebudget_test.cpp).
-#   - `warpRoiExceedsGuard` — the OpenCV-free warp-canvas size guard that
-#     triggers the cylindrical-fallback pre-pass (warp_guard_test.cpp).
-#   (The StitcherWorkletRegistry test was removed when that source was
-#    archived in the Phase-3 cleanup — its CMake entries had gone stale
-#    and broke the whole suite's configure step.)
-#
-# What this DOES NOT test yet (deferred to v0.11.0+):
-#   - `KeyframeGate` (the full gate) — depends on OpenCV.  Will need an
-#     OpenCV-aware CMake config (link the same opencv_world the prod
-#     build uses).  NOTE: the OpenCV-free `timeBudgetCrossed` predicate
-#     (the time-budget force-accept boundary logic) IS covered, via
-#     keyframe_timebudget_test.cpp — it's an inline header-only function.
-#   - JSI host-object dispatch — needs a real Hermes runtime.
-#   - Anything in `stitcher.cpp` (uses OpenCV stitching pipeline).
-
-cmake_minimum_required(VERSION 3.20)
-project(stitcher_cpp_tests CXX)
-
-set(CMAKE_CXX_STANDARD 17)
-set(CMAKE_CXX_STANDARD_REQUIRED ON)
-set(CMAKE_CXX_EXTENSIONS OFF)
-
-# Must precede `gtest_discover_tests` — without this the discovered
-# cases aren't registered into a CTestTestfile.cmake at this directory
-# level, and `ctest` reports "No tests were found".
-enable_testing()
-
-# Fetch GoogleTest pinned to v1.14.0.  Pin matches what the AOSP /
-# Android NDK test ecosystem uses today; bumps should be deliberate.
-include(FetchContent)
-FetchContent_Declare(
-  googletest
-  GIT_REPOSITORY https://github.com/google/googletest.git
-  GIT_TAG        v1.14.0
-)
-# Prevent GoogleTest from overriding our compiler/linker options
-# (Windows-only quirk; harmless on macOS/Linux).
-set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
-FetchContent_MakeAvailable(googletest)
-
-# ─────────────────────────────────────────────────────────────────────
-# Include paths
-# ─────────────────────────────────────────────────────────────────────
-# Order matters: stubs/ comes FIRST so `#include <jsi/jsi.h>` and
-# `#include <react-native-worklets-core/WKTJsiWorklet.h>` resolve to
-# the test-only stubs before any system header.  The production cpp/
-# directory comes after so retailens:: headers (e.g. ar_frame_pose.h,
-# stitcher_frame_data.hpp) are found as the production code expects.
-include_directories(
-  ${CMAKE_CURRENT_SOURCE_DIR}/stubs
-  ${CMAKE_CURRENT_SOURCE_DIR}/..
-)
-
-# ─────────────────────────────────────────────────────────────────────
-# Test executable
-# ─────────────────────────────────────────────────────────────────────
-add_executable(stitcher_cpp_tests
-  # Test sources.  All subjects are header-only (Pose / PlaneTransform,
-  # StitcherFrameData, and the gate's inline `timeBudgetCrossed`
-  # predicate), so no production .cpp needs linking here.
-  ${CMAKE_CURRENT_SOURCE_DIR}/pose_test.cpp
-  ${CMAKE_CURRENT_SOURCE_DIR}/stitcher_frame_data_test.cpp
-  ${CMAKE_CURRENT_SOURCE_DIR}/keyframe_timebudget_test.cpp
-  ${CMAKE_CURRENT_SOURCE_DIR}/warp_guard_test.cpp
-)
-
-target_link_libraries(stitcher_cpp_tests
-  PRIVATE
-    GTest::gtest_main
-)
-
-# Treat warnings as errors in the test build to catch the kind of
-# silent regressions (unused variables, signed/unsigned comparisons,
-# narrowing conversions) that production cross-compilation flags would
-# otherwise suppress.
-if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
-  target_compile_options(stitcher_cpp_tests PRIVATE
-    -Wall -Wextra -Wpedantic -Werror
-  )
-endif()
-
-# Register with CTest so `ctest --output-on-failure` picks up the
-# individual TEST() cases (gtest_discover_tests scans the binary at
-# build time, no manual ADD_TEST per case).
-include(GoogleTest)
-gtest_discover_tests(stitcher_cpp_tests)

package/cpp/tests/README.md

@@ -1,86 +0,0 @@
-# `cpp/tests/` — shared C++ unit test suite
-
-v0.10.0 audit `#9A` introduced this directory to give the cross-platform
-shared C++ code under `cpp/` a Google Test harness that runs on the
-developer's host machine (not on a device or emulator).  Pairs with the
-Android-side JUnit suite added in `#11A` (see
-`android/src/test/java/io/imagestitcher/rn/`).
-
-## Run
-
-```sh
-scripts/run-cpp-tests.sh           # configure + build + ctest
-scripts/run-cpp-tests.sh --clean   # nuke build/cpp-tests/ first
-```
-
-Requires `cmake ≥ 3.20` and a C++17 toolchain (the macOS AppleClang
-shipped with Xcode 14+ is fine; Linux GCC 9+ / Clang 10+ also work).
-
-Build artefacts land under `build/cpp-tests/` (gitignored).  Google
-Test is fetched at configure time via CMake `FetchContent` pinned to
-`v1.14.0`; no system-wide install required.
-
-## Scope (v0.10.0)
-
-Covered:
-
-- `Pose`, `PlaneTransform` (POD layout / size / field offsets — pinned
-  to the cross-platform marshalling contract documented in
-  `cpp/ar_frame_pose.h`).
-- `StitcherFrameData` (default-construction invariants the JSI host
-  object's `get()` dispatch relies on).
-- `PixelBufferReader` interface contract (clipping behaviour of
-  `copyTo` — validated via the `FakePixelBufferReader` test helper).
-- `StitcherWorkletRegistry` storage lifecycle: shared-instance,
-  install/uninstall/count/snapshot, snapshot independence, concurrent
-  installs yield unique IDs (16 threads × 32 installs).
-
-Not yet covered (intentional deferrals):
-
-- `KeyframeGate` (`cpp/keyframe_gate.cpp`) — depends on OpenCV
-  (`opencv2/imgproc.hpp`, `opencv2/video.hpp` for `calcOpticalFlowPyrLK`).
-  Linking the production OpenCV xcframework / Android SDK into the
-  host-side test target would balloon CI time and disk usage; the
-  alternative is to land a stripped-down `libopencv-core` host build
-  just for tests.  Deferred — comes with the v0.11.0 cross-platform
-  parity suite (`#2C`).
-- `stitcher.cpp` — uses the full OpenCV stitching pipeline; same
-  reason as above.
-- JSI host-object dispatch (`stitcher_frame_jsi.cpp`,
-  `stitcher_proxy_jsi.cpp`, `stitcher_worklet_dispatch.cpp`) — needs
-  a real Hermes runtime.  The `StitcherWorkletRegistry` tests sidestep
-  this via the `_installEntryForTests` seam + JSI stubs under
-  `stubs/`; the JSI dispatch paths can't be similarly stubbed because
-  they actively call into the runtime.
-
-## How the JSI-dependent registry tests work without a real JSI
-
-`stitcher_worklet_registry.cpp` `#include`s
-`<jsi/jsi.h>` and `<react-native-worklets-core/WKTJsiWorklet.h>` to
-construct `WorkletInvoker` instances from a real JS runtime.  The test
-target sidesteps both by:
-
-1. Putting `cpp/tests/stubs/` first on the compiler's include path so
-   `#include <jsi/jsi.h>` resolves to `stubs/jsi/jsi.h` (which declares
-   `facebook::jsi::Runtime` / `Value` as empty classes — enough for
-   the registry's reference-only usage), and
-   `#include <react-native-worklets-core/WKTJsiWorklet.h>` resolves to
-   `stubs/react-native-worklets-core/WKTJsiWorklet.h` (which declares
-   `RNWorklet::WorkletInvoker` with a no-op constructor).
-2. Calling `_installEntryForTests(nullptr)` instead of the production
-   `install(runtime, value)` path.  The registry stores the
-   `shared_ptr<WorkletInvoker>` but never dereferences it (it only
-   hands it back via `snapshot`), so `nullptr` is safe.
-
-The stubs live exclusively under `cpp/tests/stubs/`; production
-builds never see them.  See `stubs/jsi/jsi.h`'s docstring for the
-guard-rails.
-
-## When NOT to add a test here
-
-- If the test needs a real JSI runtime, real OpenCV operations, or
-  real-device sensor data, it belongs in `android/src/androidTest/`
-  (instrumented), the iOS Swift test target, or the v0.11.0 parity
-  harness — NOT here.
-- If the test verifies TypeScript/JS-side behaviour, it belongs under
-  `src/**/__tests__/` (Jest).

package/cpp/tests/keyframe_timebudget_test.cpp

@@ -1,65 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-//
-// keyframe_timebudget_test.cpp — host unit tests for the pure
-// `retailens::timeBudgetCrossed` predicate (the keyframe gate's
-// time-budget force-accept decision).
-//
-// The full KeyframeGate depends on OpenCV and cannot run in this
-// harness (see CMakeLists.txt).  The time-budget boundary logic was
-// therefore deliberately extracted into an inline, OpenCV-free
-// predicate in keyframe_gate.hpp precisely so it CAN be unit-tested
-// here without linking the gate's OpenCV-dependent .cpp.
-
-#include <gtest/gtest.h>
-
-#include "keyframe_gate.hpp"
-
-using retailens::timeBudgetCrossed;
-
-// intervalMs <= 0 disables the budget entirely (opt-out path).
-TEST(TimeBudgetCrossed, DisabledWhenIntervalNonPositive) {
-  EXPECT_FALSE(timeBudgetCrossed(0.0, 1000, 999999));
-  EXPECT_FALSE(timeBudgetCrossed(-5.0, 1000, 999999));
-}
-
-// Never fires before the first accept (lastAcceptMs sentinel -1),
-// regardless of how large `nowMs` is.
-TEST(TimeBudgetCrossed, NeverFiresBeforeFirstAccept) {
-  EXPECT_FALSE(timeBudgetCrossed(2000.0, -1, 1000000));
-}
-
-// Fires exactly at the boundary (elapsed == interval) and beyond.
-TEST(TimeBudgetCrossed, FiresAtAndAfterBoundary) {
-  EXPECT_TRUE(timeBudgetCrossed(2000.0, 1000, 3000));  // elapsed == 2000
-  EXPECT_TRUE(timeBudgetCrossed(2000.0, 1000, 5000));  // elapsed  > 2000
-}
-
-// Does NOT fire just under the boundary.
-TEST(TimeBudgetCrossed, DoesNotFireJustUnderBoundary) {
-  EXPECT_FALSE(timeBudgetCrossed(2000.0, 1000, 2999));  // elapsed == 1999
-}
-
-// A backwards or equal clock must never fire.  A monotonic source
-// should prevent now < lastAccept, but the predicate must be robust.
-TEST(TimeBudgetCrossed, BackwardsOrEqualClockDoesNotFire) {
-  EXPECT_FALSE(timeBudgetCrossed(2000.0, 5000, 4000));  // now < lastAccept
-  EXPECT_FALSE(timeBudgetCrossed(2000.0, 5000, 5000));  // elapsed 0 < 2000
-}
-
-// Sub-millisecond budget must NOT collapse to "accept every frame":
-// the predicate compares elapsed in double, so a 0.5 ms budget needs
-// ~1 ms elapsed (not 0).  Guards the truncation regression.
-TEST(TimeBudgetCrossed, SubMillisecondBudgetDoesNotAcceptEveryFrame) {
-  EXPECT_FALSE(timeBudgetCrossed(0.5, 1000, 1000));  // elapsed 0.0 < 0.5
-  EXPECT_TRUE(timeBudgetCrossed(0.5, 1000, 1001));   // elapsed 1.0 >= 0.5
-}
-
-// Realistic 2 s budget across a slow pan: a keyframe accepted at t,
-// the next force-accept lands at t + 2000 ms, not before.
-TEST(TimeBudgetCrossed, TwoSecondBudgetTypicalUse) {
-  const int64_t lastAccept = 10000;
-  EXPECT_FALSE(timeBudgetCrossed(2000.0, lastAccept, lastAccept + 1500));
-  EXPECT_FALSE(timeBudgetCrossed(2000.0, lastAccept, lastAccept + 1999));
-  EXPECT_TRUE(timeBudgetCrossed(2000.0, lastAccept, lastAccept + 2000));
-  EXPECT_TRUE(timeBudgetCrossed(2000.0, lastAccept, lastAccept + 2001));
-}