react-native-image-stitcher 0.14.1 → 0.15.0

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

@@ -140,6 +140,23 @@ internal class KeyframeGate : AutoCloseable {
             nativeSetFlowMaxTranslationM(nativeHandle, value)
         }
 
+    /// Wall-clock keyframe-interval budget, in MILLISECONDS, between
+    /// consecutive accepted keyframes before force-acceptance.  Same
+    /// knob iOS exposes via setMaxKeyframeIntervalMs (KeyframeGate.swift
+    /// `maxKeyframeIntervalMs`).  Unlike flowMaxTranslationM this applies
+    /// to BOTH the Pose and Flow strategies, and is passed STRAIGHT
+    /// THROUGH (already in the unit the C++ expects — no conversion).
+    /// Default 2000 ms (matches iOS); 0 = disabled.  The C++ setter
+    /// clamps to ≥ 0.  NOTE: like every other facade property the
+    /// initializer below does NOT fire this setter, so the caller
+    /// (IncrementalStitcher.kt) writes it explicitly at capture start
+    /// to push the value into C++ (same contract as the iOS facade).
+    var maxKeyframeIntervalMs: Double = 2000.0
+        set(value) {
+            field = value
+            nativeSetMaxKeyframeIntervalMs(nativeHandle, value)
+        }
+
     /// 2026-05-22 (audit F5) — Flow strategy: Shi-Tomasi max corners
     /// to track per frame.  Same knob iOS exposes via setFlowMaxCorners.
     /// C++ clamps to ≥ 30.  Higher = more sensitive to fine detail but
@@ -305,6 +322,9 @@ internal class KeyframeGate : AutoCloseable {
     private external fun nativeSetDisableAngularFallback(handle: Long, disabled: Boolean)
     private external fun nativeSetFlowNoveltyPercentile(handle: Long, percentile: Double)
     private external fun nativeSetFlowMaxTranslationM(handle: Long, metres: Double)
+    // Wall-clock keyframe-interval budget (ms).  iOS parity:
+    // KeyframeGateBridge.setMaxKeyframeIntervalMs.
+    private external fun nativeSetMaxKeyframeIntervalMs(handle: Long, ms: Double)
     // 2026-05-22 (audit F5) — flow-strategy tunables that were
     // previously iOS-only.  Add Android JNI parity so the Settings UI
     // sliders work on both platforms.
@@ -362,6 +382,15 @@ internal class KeyframeGate : AutoCloseable {
             9 -> "max-reached"
             10 -> "overlap-too-high"
             11 -> "overlap-too-high (angular)"
+            // Flow-strategy reasons (v0.3.0, cpp KeyframeGateDecisionReason
+            // 12-15) — strings must match the cpp/iOS labels exactly.
+            12 -> "ok-flow"
+            13 -> "first-flow"
+            14 -> "overlap-too-high (flow)"
+            15 -> "ok-flow-translation"
+            // Wall-clock keyframe-interval force-accept (Pose + Flow);
+            // cpp KeyframeGateDecisionReason::AcceptTimeInterval = 16.
+            16 -> "ok-time-interval"
             else -> "unknown($code)"
         }
     }

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

@@ -101,10 +101,6 @@ class RNImageStitcherPackage : ReactPackage {
             RNSARSession(reactContext),
             IncrementalStitcher(reactContext),
             FileBridge(reactContext),
-            // v0.8.0 Phase 4b.ii — Android JSI installer for the
-            // host-worklet `__stitcherProxy` global.  Mirror of
-            // iOS' `StitcherJsiInstaller`.
-            StitcherJsiInstallerModule(reactContext),
         )
     }
 

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

@@ -296,20 +296,12 @@ class RNSARCameraView @JvmOverloads constructor(
         // contract was already in place for Phase 4.
         appendPose(camera, frame.timestamp)
 
-        // Forward to the incremental stitcher if engaged, OR if any
-        // host worklets are registered (v0.8.0 Phase 4b.iii).  iOS'
-        // `RNSARWorkletRuntime.dispatchFrame:pose:` fires on every
-        // AR frame regardless of capture state; Android needs the
-        // same semantic so host worklets see the AR-mode preview
-        // stream, not just capture frames.
-        //
-        // `hasHostWorklets()` is a microsecond atomic-read on the
-        // native registry — cheap enough to hit per frame.  When
-        // no host worklets are registered AND no capture is active,
-        // the entire forwardToIncremental branch (including the
-        // ~3-5ms NV21 pack) is skipped — same cost envelope as
-        // before Phase 4b.iii.
-        if (ingestActive || StitcherWorkletRuntime.hasHostWorklets()) {
+        // Forward to the incremental stitcher only when capture is
+        // engaged.  (The v0.8.0 host-worklet dispatch — which also
+        // forwarded preview frames whenever host worklets were
+        // registered — was archived in the 2026-06 batch-keyframe
+        // cleanup.)
+        if (ingestActive) {
             forwardToIncremental(frame, camera)
         }
 
@@ -541,22 +533,14 @@ class RNSARCameraView @JvmOverloads constructor(
         //  written to `tmpJpegFile`, passed as `legacyJpegPath`.
         //  See the v0.3 / F8.6 entries in CHANGELOG.md.)
         //
-        // v0.8.0 Phase 3c — route through the worklet runtime's
-        // `runFirstParty` indirection.  The lambda body is the
-        // unchanged engine ingest call; the indirection sets up
-        // the seam where Phase 4 will fan out to host worklets
-        // without touching this first-party path.  Synchronous
-        // invocation preserves the ARCore Image ownership contract
-        // — the engine consumes the TransferredNV21 inside the
-        // lambda before ARCore recycles the Image.
-        StitcherWorkletRuntime.installIfNeeded()
-        // v0.8.0 Phase 4b.iii — only run first-party stitching when
-        // the host has actively engaged capture (`setIncrementalIngestionActive(true)`).
-        // The host-worklet dispatch below runs regardless, so AR-mode
-        // preview frames stream through registered host worklets even
-        // before/after capture.
+        // Synchronous engine ingest.  The ARCore Image ownership
+        // contract requires the engine to consume the TransferredNV21
+        // before ARCore recycles the Image, so this runs inline.  Only
+        // ingest when the host has actively engaged capture
+        // (`setIncrementalIngestionActive(true)`).  (The v0.8.0 worklet-
+        // runtime `runFirstParty` indirection + host-worklet fan-out
+        // were archived in the 2026-06 batch-keyframe cleanup.)
         if (ingestActive) {
-        StitcherWorkletRuntime.runFirstParty {
         module.ingestFromARCameraView(
             tx = tArr[0].toDouble(),
             ty = tArr[1].toDouble(),
@@ -608,42 +592,7 @@ class RNSARCameraView @JvmOverloads constructor(
                 ) != null
             },
         )
-        }  // closes StitcherWorkletRuntime.runFirstParty { … } (v0.8.0 Phase 3c)
         }  // closes `if (ingestActive)` (v0.8.0 Phase 4b.iii)
-
-        // ── v0.8.0 Phase 4b.iii — host-worklet fan-out ─────────────
-        //
-        // Dispatch the AR frame to every host worklet registered via
-        // `globalThis.__stitcherProxy.install(workletFn)` (the
-        // `useFrameProcessor` hook's AR-mode path).  The native side
-        // fast-path early-exits when the registry is empty (~ns
-        // cost), so this call is free for first-party-only deployments.
-        //
-        // Map the trackingState back to the JS-visible string set.
-        // `RNSARSession.TRACKING_*` are int codes; we re-derive the
-        // string here instead of plumbing it through.  (Could be
-        // refactored into a helper if/when other call sites need
-        // it.)
-        val trackingStateStr = when (camera.trackingState) {
-            TrackingState.TRACKING -> "normal"
-            TrackingState.PAUSED -> "limited"
-            TrackingState.STOPPED -> "notAvailable"
-            else -> ""
-        }
-        StitcherWorkletRuntime.dispatchToHostWorklets(
-            nv21Bytes = packed.nv21,
-            width = packed.width,
-            height = packed.height,
-            qx = qarr[0].toDouble(),
-            qy = qarr[1].toDouble(),
-            qz = qarr[2].toDouble(),
-            qw = qarr[3].toDouble(),
-            tx = tArr[0].toDouble(),
-            ty = tArr[1].toDouble(),
-            tz = tArr[2].toDouble(),
-            timestampNs = frame.timestamp.toDouble(),
-            trackingState = trackingStateStr,
-        )
     }
 
     /// v0.13.2 — map the JS physical device orientation to the

package/cpp/keyframe_gate.cpp

@@ -28,6 +28,7 @@
 #include "keyframe_gate.hpp"
 
 #include <algorithm>
+#include <chrono>
 #include <cmath>
 #include <cstring>
 #include <cstdint>
@@ -285,6 +286,10 @@ struct KeyframeGate::Impl {
     // only matters when the gate is used WITHOUT the JS bridge.
     double overlapThreshold   = 0.2;
     int32_t maxCount          = 6;
+    /// Time-budget force-accept (both strategies).  > 0 ms = force a
+    /// keyframe when this much wall-clock time has elapsed since the last
+    /// accept, even if novelty < threshold.  0.0 = disabled.  See hpp.
+    double maxKeyframeIntervalMs = 0.0;
 
     // V16 A2 — strategy + flow tunables.  Default is Pose to keep
     // pre-A2 behaviour for any caller that hasn't switched.  The
@@ -327,6 +332,13 @@ struct KeyframeGate::Impl {
     std::optional<PlaneBasis>        planeForCapture;
     bool   forceAcceptNext    = false;
     std::optional<Pose>              lastAcceptedPose;
+    /// Time-budget state.  `lastAcceptSteadyMs` = monotonic ms stamp of
+    /// the last accepted keyframe (-1 until the first accept).
+    /// `currentNowMs` = stamp for the in-flight evaluate() call, stashed
+    /// at entry so the static angular-fallback + the strategy paths can
+    /// read it without threading it through every signature.
+    int64_t lastAcceptSteadyMs = -1;
+    int64_t currentNowMs       = -1;
 
     // ── Flow-path state (V16 A2) ──────────────────────────────────
     // `prevFrameGray` is the WORKING-RESOLUTION grayscale image of the
@@ -380,6 +392,9 @@ void KeyframeGate::setFlowMinDistance(double d)         { pImpl_->flowMinDistanc
 // V16 — translation budget.  Clamp to non-negative; 0.0 disables the
 // force-accept entirely (callers can opt-out by passing 0).
 void KeyframeGate::setFlowMaxTranslationM(double m)     { pImpl_->flowMaxTranslationM = (m < 0.0 ? 0.0 : m); }
+// Time-budget force-accept (both strategies).  Clamp to non-negative;
+// 0.0 disables it (callers opt out by passing 0).
+void KeyframeGate::setMaxKeyframeIntervalMs(double ms)  { pImpl_->maxKeyframeIntervalMs = (ms < 0.0 ? 0.0 : ms); }
 // V16 — novelty percentile.  Clamp to [0.5, 0.99].  Below 0.5 the
 // estimate becomes too sensitive to the BEST-tracked-features (under-
 // reports user-perceived novelty); above 0.99 it's effectively max-
@@ -395,6 +410,8 @@ void KeyframeGate::reset() {
     pImpl_->planeForCapture.reset();
     pImpl_->forceAcceptNext = false;
     pImpl_->lastAcceptedPose.reset();
+    pImpl_->lastAcceptSteadyMs = -1;
+    pImpl_->currentNowMs       = -1;
     // V16 A2 — drop flow state.  release() returns the cv::Mat to
     // empty (refcount-managed); std::vector::clear() is the
     // canonical empty.  Mandatory: leftover state from a prior
@@ -428,6 +445,14 @@ bool    KeyframeGate::isEnabled() const         { return pImpl_->enabled; }
 // remain in the enum for back-compat but are NO LONGER EMITTED.
 // Diagnostic logging at the call sites tells us if a degenerate
 // projection triggered the fallback.
+// Monotonic wall-clock in milliseconds for the time-budget force-accept.
+// Used when the caller passes monotonicNowMs < 0 (production); tests pass
+// an explicit stamp to drive elapsed time deterministically.
+static int64_t steadyNowMs() {
+    return std::chrono::duration_cast<std::chrono::milliseconds>(
+        std::chrono::steady_clock::now().time_since_epoch()).count();
+}
+
 KeyframeGateDecision KeyframeGate::evaluateAngularFallback(
     Impl& s,
     const Pose& pose)
@@ -441,6 +466,16 @@ KeyframeGateDecision KeyframeGate::evaluateAngularFallback(
         return { false, KeyframeGateDecisionReason::RejectMaxReached,
                  -1.0, s.acceptedCount, s.maxCount };
     }
+    // Time-budget force-accept — overrides BOTH the disable-angular hard
+    // reject and the novelty reject below.  The angular path keeps no image
+    // baseline (only lastAcceptedPose), so this is a complete accept.
+    if (timeBudgetCrossed(s.maxKeyframeIntervalMs, s.lastAcceptSteadyMs, s.currentNowMs)) {
+        s.lastAcceptedPose   = pose;
+        s.lastAcceptSteadyMs = s.currentNowMs;
+        s.acceptedCount     += 1;
+        return { true, KeyframeGateDecisionReason::AcceptTimeInterval,
+                 -1.0, s.acceptedCount, s.maxCount };
+    }
     // 2026-05-14 — non-AR-mode opt-out.  When `disableAngularFallback`
     // is set, treat every angular-fallback call as a hard reject.
     // The caller's flow strategy is then the only path that can
@@ -469,6 +504,7 @@ KeyframeGateDecision KeyframeGate::evaluateAngularFallback(
                  newContent, s.acceptedCount, s.maxCount };
     }
     s.lastAcceptedPose = pose;
+    s.lastAcceptSteadyMs = s.currentNowMs;
     s.acceptedCount += 1;
     return { true, KeyframeGateDecisionReason::AcceptOkAngular,
              newContent, s.acceptedCount, s.maxCount };
@@ -476,9 +512,14 @@ KeyframeGateDecision KeyframeGate::evaluateAngularFallback(
 
 
 KeyframeGateDecision KeyframeGate::evaluate(const Pose& pose,
-                                            const PlaneTransform* latchedPlane)
+                                            const PlaneTransform* latchedPlane,
+                                            int64_t monotonicNowMs)
 {
     Impl& s = *pImpl_;
+    // Stash the monotonic stamp for this call so the time-budget checks
+    // (here, the angular fallback, and the strategy paths) all read one
+    // consistent "now".  Caller may inject it (tests); else steady_clock.
+    s.currentNowMs = (monotonicNowMs >= 0) ? monotonicNowMs : steadyNowMs();
 
     // 1) Mode disabled → pass-through.
     if (!s.enabled) {
@@ -504,6 +545,7 @@ KeyframeGateDecision KeyframeGate::evaluate(const Pose& pose,
             }
         }
         s.lastAcceptedPose = pose;
+        s.lastAcceptSteadyMs = s.currentNowMs;
         s.acceptedCount += 1;
         return { true, KeyframeGateDecisionReason::AcceptForceLast,
                  -1.0, s.acceptedCount, s.maxCount };
@@ -512,6 +554,7 @@ KeyframeGateDecision KeyframeGate::evaluate(const Pose& pose,
     // 3) First-frame anchor — always accepted.
     if (s.acceptedCount == 0) {
         s.lastAcceptedPose = pose;
+        s.lastAcceptSteadyMs = s.currentNowMs;
         if (latchedPlane) {
             auto basis = planeBasisFromMatrix(latchedPlane->m);
             if (basis) {
@@ -587,16 +630,22 @@ KeyframeGateDecision KeyframeGate::evaluate(const Pose& pose,
     if (overlapRatio > 1.0f) overlapRatio = 1.0f;
     double newContentFraction = 1.0 - static_cast<double>(overlapRatio);
 
-    if (newContentFraction < s.overlapThreshold) {
+    const bool poseTimeCrossed = timeBudgetCrossed(
+        s.maxKeyframeIntervalMs, s.lastAcceptSteadyMs, s.currentNowMs);
+    if (newContentFraction < s.overlapThreshold && !poseTimeCrossed) {
         return { false, KeyframeGateDecisionReason::RejectOverlapTooHigh,
                  newContentFraction, s.acceptedCount, s.maxCount };
     }
 
-    // Accept.
+    // Accept (novelty crossed, or the time-budget forced it).
     s.lastCornersOnPlane = currentCorners;
     s.lastAcceptedPose   = pose;
+    s.lastAcceptSteadyMs = s.currentNowMs;
     s.acceptedCount += 1;
-    return { true, KeyframeGateDecisionReason::AcceptOk,
+    return { true,
+             (newContentFraction >= s.overlapThreshold)
+                 ? KeyframeGateDecisionReason::AcceptOk
+                 : KeyframeGateDecisionReason::AcceptTimeInterval,
              newContentFraction, s.acceptedCount, s.maxCount };
 }
 
@@ -699,9 +748,13 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
     const uint8_t* grayData,
     int32_t width,
     int32_t height,
-    int32_t stride)
+    int32_t stride,
+    int64_t monotonicNowMs)
 {
     Impl& s = *pImpl_;
+    // Stash the monotonic stamp (see evaluate()).  The Pose-strategy
+    // dispatch below forwards it so both entry points agree on "now".
+    s.currentNowMs = (monotonicNowMs >= 0) ? monotonicNowMs : steadyNowMs();
 
     // §1 — disabled passes through unchanged for either strategy.
     if (!s.enabled) {
@@ -717,6 +770,7 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
     // mostly defensive.
     if (s.forceAcceptNext) {
         s.forceAcceptNext = false;
+        s.lastAcceptSteadyMs = s.currentNowMs;
         s.acceptedCount  += 1;
         // No newContent fraction — we accepted unconditionally.
         return { true, KeyframeGateDecisionReason::AcceptForceLast,
@@ -728,7 +782,7 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
         // Pose path is OpenCV-free and identical to the
         // backward-compat `evaluate()` entry point.  Skip the
         // grayscale wrap entirely — `grayData` is ignored.
-        return evaluate(pose, latchedPlane);
+        return evaluate(pose, latchedPlane, s.currentNowMs);
     }
 
     // Flow path — wrap incoming pixel data as a non-owning cv::Mat
@@ -738,7 +792,7 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
         // Defensive: caller forgot to supply image data despite
         // strategy=Flow.  Fall back to pose path so we degrade
         // gracefully rather than crashing on a null deref.
-        return evaluate(pose, latchedPlane);
+        return evaluate(pose, latchedPlane, s.currentNowMs);
     }
     cv::Mat currGrayFull(height, width, CV_8UC1,
                         const_cast<uint8_t*>(grayData),
@@ -760,6 +814,7 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
         s.prevFrameOrigWidth  = width;
         s.prevFrameOrigHeight = height;
         s.lastAcceptedPose    = pose;
+        s.lastAcceptSteadyMs  = s.currentNowMs;
         s.acceptedCount       = 1;
         return { true, KeyframeGateDecisionReason::AcceptFirstFlow,
                  -1.0, s.acceptedCount, s.maxCount };
@@ -878,24 +933,27 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
     const bool translationBudgetCrossed =
         (s.flowMaxTranslationM > 0.0) &&
         (translationSinceLastAccept >= s.flowMaxTranslationM);
-
-    // §7 — accept-or-reject combined check.  Accept if EITHER the
-    // novelty crossed `overlapThreshold` (the original rule) OR the
-    // translation budget was exceeded (the V16 force-accept).  The
-    // decision reason distinguishes the two so telemetry can identify
-    // captures driven mostly by translation force-accepts vs. natural
-    // novelty accepts.
-    if (novelty < s.overlapThreshold && !translationBudgetCrossed) {
+    // Time-budget force-accept (both strategies; see hpp).  Same shape as
+    // the translation budget, but measured on elapsed wall-clock time.
+    const bool flowTimeCrossed = timeBudgetCrossed(
+        s.maxKeyframeIntervalMs, s.lastAcceptSteadyMs, s.currentNowMs);
+
+    // §7 — accept-or-reject combined check.  Accept if the novelty crossed
+    // `overlapThreshold` (the original rule) OR the translation budget OR
+    // the time budget was exceeded (the force-accepts).  The decision
+    // reason distinguishes them so telemetry can identify what drove each.
+    if (novelty < s.overlapThreshold && !translationBudgetCrossed && !flowTimeCrossed) {
         return { false, KeyframeGateDecisionReason::RejectOverlapTooHighFlow,
                  novelty, s.acceptedCount, s.maxCount };
     }
-    // Pick the reason — novelty win takes precedence (we report what
-    // crossed the threshold first conceptually; if both crossed, the
-    // novelty path is the "natural" reason).
+    // Pick the reason — precedence: natural novelty, then translation, then
+    // time (if several crossed, report the most "natural" cause).
     const KeyframeGateDecisionReason acceptReason =
         (novelty >= s.overlapThreshold)
             ? KeyframeGateDecisionReason::AcceptOkFlow
-            : KeyframeGateDecisionReason::AcceptFlowTranslation;
+            : translationBudgetCrossed
+                ? KeyframeGateDecisionReason::AcceptFlowTranslation
+                : KeyframeGateDecisionReason::AcceptTimeInterval;
 
     // §8 — accept.  Re-detect features in the newly-accepted frame
     // (the previous set is now stale; many of them have moved out
@@ -915,11 +973,12 @@ KeyframeGateDecision KeyframeGate::evaluateWithFrame(
     s.prevFrameOrigWidth  = width;
     s.prevFrameOrigHeight = height;
     s.lastAcceptedPose    = pose;
+    s.lastAcceptSteadyMs  = s.currentNowMs;
     s.acceptedCount      += 1;
-    // `acceptReason` was decided in §7 — either AcceptOkFlow (novelty
-    // crossed) or AcceptFlowTranslation (translation budget forced
-    // the accept).  Reported back here so the host's telemetry can
-    // distinguish.
+    // `acceptReason` was decided in §7 — AcceptOkFlow (novelty crossed),
+    // AcceptFlowTranslation (translation budget forced it), or
+    // AcceptTimeInterval (time budget forced it).  Reported back here so
+    // the host's telemetry can distinguish.
     return { true, acceptReason,
              novelty, s.acceptedCount, s.maxCount };
 }

package/cpp/keyframe_gate.hpp

@@ -99,8 +99,23 @@ enum class KeyframeGateDecisionReason : int32_t {
     AcceptFirstFlow             = 13,  // "first-flow" — first frame under flow strategy
     RejectOverlapTooHighFlow    = 14,  // "overlap-too-high (flow)"
     AcceptFlowTranslation       = 15,  // "ok-flow-translation" — translation since last accept exceeded flowMaxTranslationM (force-accept even when novelty < threshold)
+    AcceptTimeInterval          = 16,  // "ok-time-interval" — wall-clock interval since last accept exceeded maxKeyframeIntervalMs (force-accept even when novelty < threshold; applies to BOTH Pose and Flow strategies)
 };
 
+/// Pure, OpenCV-free predicate for the time-budget force-accept — split
+/// out so it can be unit-tested on the host WITHOUT linking the gate's
+/// OpenCV-dependent .cpp.  True iff a positive budget is set, a prior
+/// accept stamp exists (lastAcceptMs >= 0), and at least that many
+/// milliseconds have elapsed (nowMs - lastAcceptMs >= intervalMs).
+inline bool timeBudgetCrossed(double intervalMs, int64_t lastAcceptMs, int64_t nowMs) {
+    // Compare elapsed-ms in `double` (not a truncating int64 cast of
+    // intervalMs) so a sub-millisecond budget doesn't collapse to
+    // "accept every frame".
+    return intervalMs > 0.0
+        && lastAcceptMs >= 0
+        && static_cast<double>(nowMs - lastAcceptMs) >= intervalMs;
+}
+
 struct KeyframeGateDecision {
     bool       accept;
     KeyframeGateDecisionReason reason;
@@ -128,6 +143,13 @@ public:
     void setEnabled(bool enabled);
     void setOverlapThreshold(double threshold);    // [0, 1]; default 0.4
     void setMaxCount(int32_t maxCount);            // ≥ 1; default 6
+    /// Time-budget force-accept (applies to BOTH strategies, Pose + Flow).
+    /// When > 0 and that many milliseconds of wall-clock time have elapsed
+    /// since the last accepted keyframe, the gate force-accepts the current
+    /// frame even if novelty < threshold — a "don't go longer than N ms
+    /// without a keyframe" guarantee for slow / static pans.  Counts toward
+    /// maxCount (respects the cap).  Default 0.0 = disabled; clamped to ≥ 0.
+    void setMaxKeyframeIntervalMs(double ms);
     void markNextFrameAsLast();                    // one-shot, consumed by next evaluate()
     void reset();                                  // clears acceptedCount, lastCorners, planeCached AND flow state
 
@@ -210,14 +232,21 @@ public:
     // @param stride        bytes per row (usually equal to width;
     //                       larger when the underlying buffer is
     //                       padded).
+    // @param monotonicNowMs  optional monotonic timestamp (milliseconds)
+    //                        for the time-budget force-accept.  Pass -1
+    //                        (default) to have the gate read its own
+    //                        steady_clock; tests pass an explicit value to
+    //                        drive elapsed time deterministically.
     KeyframeGateDecision evaluate(const Pose& pose,
-                                  const PlaneTransform* latchedPlane);
+                                  const PlaneTransform* latchedPlane,
+                                  int64_t monotonicNowMs = -1);
     KeyframeGateDecision evaluateWithFrame(const Pose& pose,
                                            const PlaneTransform* latchedPlane,
                                            const uint8_t* grayData,
                                            int32_t width,
                                            int32_t height,
-                                           int32_t stride);
+                                           int32_t stride,
+                                           int64_t monotonicNowMs = -1);
 
     // ── State accessors (read-only, post-evaluate) ────────────────
     int32_t getAcceptedCount() const;