react-native-smooth-clip-view 0.4.1 → 0.4.2

package/README.md

@@ -107,9 +107,9 @@ UI-runtime runs without retaining a consumer worklet for the animation lifetime.
 It does not update React state, animated props, Yoga, the ShadowTree, or a public
 SharedValue.
 
-`beginInteraction()` atomically interrupts native motion and returns its visible
-raw presentation. Apply the final gesture sample with `setFrame()` before calling
-it when the release must start from that exact frame.
+`beginInteraction()` atomically interrupts native motion and returns
+its visible raw presentation. Apply the final gesture sample with `setFrame()`
+before calling it when the release must start from that exact frame.
 
 ## React API
 
@@ -135,8 +135,21 @@ relative energy threshold `6e-9`. A spring is rejected when its resolved native
 trajectory could make `contentScale` nonpositive.
 
 An animation requested before the host has a positive layout waits, then starts
-with its full duration. Host loss after motion starts freezes every member and
-resolves the transaction `false`. Replacement, cancellation, destruction, and
+with its full duration. While the application is inactive, native animation
+transactions stay pending and do not report cancellation. Timing animations
+retain wall-clock progress and catch up after activation. Springs stay frozen;
+their first foreground step consumes at most 64 ms, matching Reanimated, and
+then they continue normally. If the platform discarded an underlying animation
+object, the transaction settles successfully at its requested target.
+
+Interactive `setFrame()` updates remain application-owned. The library does not
+reset a drag or mutate related SharedValues or React state when lifecycle state
+changes, so applications do not need lifecycle integration for the clip itself.
+
+Host loss while the application is active keeps the existing semantics:
+standalone animations apply their target and finish successfully, while groups
+(including public controllers because they use one-member groups) freeze every
+member and resolve `false`. Replacement, cancellation, destruction, and
 rejection also settle once with `false`.
 
 ## Atomic groups

package/android/src/main/cpp/SmoothClipAndroid.h

@@ -54,6 +54,7 @@ void setViewLifecycleVisibilityAndroid(
     uint64_t driverId,
     facebook::jni::alias_ref<JSmoothClipView> view,
     bool lifecycleVisible);
+void setApplicationActiveAndroid(bool active);
 
 // Advances the registry frame loop. Called from Kotlin (SmoothClipBindings)
 // inside Choreographer#doFrame with the frame's vsync timestamp converted to

package/android/src/main/cpp/SmoothClipBindings.cpp

@@ -918,6 +918,12 @@ void nativeSetViewLifecycleVisibility(
       static_cast<uint64_t>(driverId), view, lifecycleVisible != 0);
 }
 
+void nativeSetApplicationActive(
+    jni::alias_ref<jni::JObject>,
+    jboolean active) {
+  smoothclip::setApplicationActiveAndroid(active != 0);
+}
+
 void nativeInvalidate(jni::alias_ref<jni::JObject>) {
   smoothclip::invalidateBindings();
 }
@@ -942,6 +948,8 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
             makeNativeMethod(
                 "nativeSetViewLifecycleVisibility",
                 nativeSetViewLifecycleVisibility),
+            makeNativeMethod(
+                "nativeSetApplicationActive", nativeSetApplicationActive),
             makeNativeMethod("nativeInvalidate", nativeInvalidate),
             makeNativeMethod("nativeOnFrame", nativeOnFrame),
         });

package/android/src/main/cpp/SmoothClipRegistry.cpp

@@ -166,6 +166,16 @@ std::vector<int32_t> &animatingGroups() {
   return value;
 }
 
+bool &applicationActiveState() {
+  static bool value = true;
+  return value;
+}
+
+std::optional<double> &applicationInactiveSinceS() {
+  static std::optional<double> value;
+  return value;
+}
+
 // The sink is written from the JS thread (installBindings / invalidate) and
 // invoked on main. Invoking under the lock also keeps the owning bindings
 // state alive for the duration of the callback.
@@ -639,6 +649,7 @@ void startPendingGroup(ActiveGroup &group) {
 }
 
 void reconcileGroupReadiness(uint64_t driverId) {
+  if (!applicationActiveState()) return;
   const auto stateIterator = registry().find(driverId);
   if (stateIterator == registry().end() || stateIterator->second.groupId == 0) {
     return;
@@ -704,7 +715,8 @@ int32_t startAnimation(
   // visible all read animation->current, giving a never-rendered pending-run
   // freeze-at-start / replace-from-start semantics with no extra branches.
   animation.current = animation.start;
-  animation.started = anyDisplayableView(state);
+  animation.started =
+      applicationActiveState() && anyDisplayableView(state);
   state.animation = std::move(animation);
   for (ViewEntry &entry : state.views) {
     entry.participation = state.animation->started && entryDisplayable(entry)
@@ -730,7 +742,8 @@ int32_t startAnimation(
 }
 
 void finishIfHostUnavailable(uint64_t driverId, DriverState &state) {
-  if (!state.animation.has_value() || !state.animation->started ||
+  if (!applicationActiveState() || !state.animation.has_value() ||
+      !state.animation->started ||
       anyDisplayableView(state)) {
     return;
   }
@@ -746,7 +759,7 @@ void reconcileViewDisplayability(
     uint64_t driverId,
     DriverState &state,
     ViewEntry &entry) {
-  if (!state.animation.has_value()) return;
+  if (!applicationActiveState() || !state.animation.has_value()) return;
   if (!state.animation->started) {
     if (entryDisplayable(entry)) startPendingAnimation(driverId, state);
     return;
@@ -892,6 +905,7 @@ void advanceGroup(int32_t groupId, ActiveGroup &group, double now) {
 void onFrameImpl(double now) {
   SMOOTH_CLIP_TRACE("SmoothClip.frame");
   gFrameScheduled = false;
+  if (!applicationActiveState()) return;
   // Snapshot: advance() clears live-list entries on completion. advance()
   // never erases registry entries and never starts animations (completion
   // delivery hops through CallInvoker::invokeAsync), so the find() guard
@@ -939,6 +953,66 @@ void onFrameAndroid(double frameTimeS) {
   }
 }
 
+void setApplicationActiveAndroid(bool active) {
+  if (!isOnMainThread() || applicationActiveState() == active) return;
+  if (!active) {
+    applicationActiveState() = false;
+    applicationInactiveSinceS() = nowSeconds();
+    gFrameScheduled = false;
+    return;
+  }
+
+  const double now = nowSeconds();
+  const double inactiveDurationS = applicationInactiveSinceS().has_value()
+      ? std::max(0.0, now - *applicationInactiveSinceS())
+      : 0.0;
+  applicationInactiveSinceS().reset();
+  applicationActiveState() = true;
+
+  // Reanimated's spring frame delta includes the inactive interval and is
+  // clamped to 64 ms, but its termination is energy-based rather than a wall
+  // clock timeout. Keep lastFrameS unchanged so the first resumed step sees
+  // that clamped delta, while moving only the safety-cap origin forward so an
+  // ordinary background interval cannot terminate the spring by itself.
+  if (inactiveDurationS > 0) {
+    for (auto &[driverId, state] : registry()) {
+      (void)driverId;
+      if (state.groupId == 0 && state.animation.has_value() &&
+          state.animation->started &&
+          state.animation->kind == AnimationKind::Spring) {
+        state.animation->startedAtS = rebaseSpringStartAfterInactivity(
+            state.animation->startedAtS, inactiveDurationS);
+      }
+    }
+    for (auto &[groupId, group] : groupRegistry()) {
+      (void)groupId;
+      if (!group.started || group.kind != AnimationKind::Spring) continue;
+      group.startedAtS = rebaseSpringStartAfterInactivity(
+          group.startedAtS, inactiveDurationS);
+      for (GroupMemberAnimation &member : group.members) {
+        member.animation.startedAtS = rebaseSpringStartAfterInactivity(
+            member.animation.startedAtS, inactiveDurationS);
+      }
+    }
+  }
+
+  for (auto &[driverId, state] : registry()) {
+    if (state.groupId == 0 && state.animation.has_value() &&
+        !state.animation->started && anyDisplayableView(state)) {
+      startPendingAnimation(driverId, state);
+    }
+  }
+  for (auto &[groupId, group] : groupRegistry()) {
+    (void)groupId;
+    if (!group.started && allGroupMembersReady(group)) {
+      startPendingGroup(group);
+    }
+  }
+  if (!animatingDrivers().empty() || !animatingGroups().empty()) {
+    scheduleFrame();
+  }
+}
+
 // --- Public smoothclip:: interface (shared with iOS via SmoothClipRegistry.h)
 
 void setCompletionCallback(const void *owner, CompletionCallback callback) {
@@ -1241,7 +1315,8 @@ int32_t startGroupCommon(
     member.animation.lastFrameS = stamp.startedAtS;
     member.animation.frameClockAnchored = stamp.frameClockAnchored;
   }
-  group.started = allGroupMembersReady(group);
+  group.started =
+      applicationActiveState() && allGroupMembersReady(group);
   groupRegistry().emplace(groupId, std::move(group));
   if (reduce) {
     finishGroupImpl(groupId, true, true);

package/android/src/main/java/com/smoothclipview/SmoothClipBindings.kt

@@ -77,6 +77,8 @@ internal object SmoothClipBindings {
         lifecycleVisible: Boolean,
     )
 
+    external fun nativeSetApplicationActive(active: Boolean)
+
     /**
      * Releases runtime-bound listener state during host teardown; must run
      * while the JS runtime is still alive (module invalidate).
@@ -99,6 +101,10 @@ internal object SmoothClipBindings {
         Choreographer.getInstance().postFrameCallback(frameCallback)
     }
 
+    fun pauseFrameLoop() {
+        Choreographer.getInstance().removeFrameCallback(frameCallback)
+    }
+
     /** Advances the frame loop with the doFrame vsync timestamp. */
     external fun nativeOnFrame(frameTimeNanos: Long)
 }

package/android/src/main/java/com/smoothclipview/SmoothClipModule.kt

@@ -1,10 +1,12 @@
 package com.smoothclipview
 
 import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.LifecycleEventListener
 import com.facebook.react.bridge.ReactApplicationContext
 import com.facebook.react.bridge.ReadableArray
 import com.facebook.react.bridge.UiThreadUtil
 import com.facebook.react.bridge.WritableArray
+import com.facebook.react.common.LifecycleState
 import com.facebook.react.module.annotations.ReactModule
 import com.facebook.react.turbomodule.core.interfaces.BindingsInstallerHolder
 import com.facebook.react.turbomodule.core.interfaces.TurboModuleWithJSIBindings
@@ -17,12 +19,46 @@ import com.facebook.react.turbomodule.core.interfaces.TurboModuleWithJSIBindings
  */
 @ReactModule(name = NativeSmoothClipModuleSpec.NAME)
 class SmoothClipModule(context: ReactApplicationContext) :
-    NativeSmoothClipModuleSpec(context), TurboModuleWithJSIBindings {
+    NativeSmoothClipModuleSpec(context),
+    TurboModuleWithJSIBindings,
+    LifecycleEventListener {
+
+    init {
+        context.addLifecycleEventListener(this)
+        setApplicationActive(context.lifecycleState == LifecycleState.RESUMED)
+    }
+
+    private fun setApplicationActive(active: Boolean) {
+        val updateState = {
+            if (!active) {
+                SmoothClipBindings.pauseFrameLoop()
+            }
+            SmoothClipBindings.nativeSetApplicationActive(active)
+        }
+        if (UiThreadUtil.isOnUiThread()) {
+            updateState()
+        } else {
+            UiThreadUtil.runOnUiThread(updateState)
+        }
+    }
+
+    override fun onHostResume() {
+        setApplicationActive(true)
+    }
+
+    override fun onHostPause() {
+        setApplicationActive(false)
+    }
+
+    override fun onHostDestroy() {
+        setApplicationActive(false)
+    }
 
     override fun getBindingsInstaller(): BindingsInstallerHolder =
         SmoothClipBindings.getBindingsInstaller()
 
     override fun invalidate() {
+        reactApplicationContext.removeLifecycleEventListener(this)
         super.invalidate()
         // Completions must stop and runtime-bound listener functions must be
         // released before the JS runtime is torn down; otherwise a later host

package/cpp/SmoothClipAnimationCurve.h

@@ -91,6 +91,14 @@ inline double timingFraction(
   return clamp01((nowS - startedAtS) / durationS);
 }
 
+// Springs clamp a long frame delta, so inactive wall time must remain visible
+// to lastFrameS. Only the independent safety-cap origin moves forward.
+inline double rebaseSpringStartAfterInactivity(
+    double startedAtS,
+    double inactiveDurationS) {
+  return startedAtS + std::max(0.0, inactiveDurationS);
+}
+
 // --- Timing curve --------------------------------------------------------
 
 inline double cubicBezierParameterForX(

package/ios/SmoothClipRegistry.mm

@@ -44,6 +44,12 @@
                      animationId:(int32_t)animationId
                  sharedBeginTime:(CFTimeInterval)sharedBeginTime;
 - (void)smoothClipCancelAnimationUsingTarget:(BOOL)useTarget;
+- (BOOL)smoothClipPauseSpringAnimation:(int32_t)animationId
+                           atMediaTime:(CFTimeInterval)mediaTime;
+- (BOOL)smoothClipResumeSpringAnimation:(int32_t)animationId
+                            atMediaTime:(CFTimeInterval)mediaTime
+                             catchUpBy:(CFTimeInterval)catchUp;
+- (BOOL)smoothClipHasInstalledAnimation:(int32_t)animationId;
 - (BOOL)smoothClipIsJoinable;
 - (BOOL)smoothClipCanDisplay;
 - (double)smoothClipInheritedVelocityToPresentation:
@@ -76,6 +82,8 @@ struct ActiveAnimation {
   // False while a pre-ready run waits for its first displayable host. Host
   // loss after the run starts finishes it at the target.
   bool started = false;
+  bool exposedToInactivity = false;
+  bool needsForegroundReconciliation = false;
 };
 
 struct DriverState {
@@ -155,6 +163,11 @@ bool &applicationActiveState() {
   return active;
 }
 
+std::optional<CFTimeInterval> &applicationInactiveSince() {
+  static std::optional<CFTimeInterval> value;
+  return value;
+}
+
 CompletionSink &completionSink() {
   static CompletionSink sink;
   return sink;
@@ -185,6 +198,113 @@ std::vector<DriverSnapshot> cancelGroupInternal(
 void tryStartGroup(int32_t groupId);
 void finishGroupForHostLoss(int32_t groupId);
 DriverSnapshot snapshotForDriver(uint64_t driverId);
+SmoothClipView *viewForKey(ViewKey key);
+
+bool animationNeedsForegroundReconciliation(const DriverState &state) {
+  if (!state.animation.has_value()) return false;
+  const ActiveAnimation &animation = *state.animation;
+  if (animation.needsForegroundReconciliation) return true;
+  if (!animation.exposedToInactivity) return false;
+  if (animation.participants.empty()) return true;
+  for (const ViewKey key : animation.participants) {
+    if (![viewForKey(key)
+            smoothClipHasInstalledAnimation:animation.animationId]) {
+      return true;
+    }
+  }
+  return false;
+}
+
+bool groupNeedsForegroundReconciliation(int32_t groupId) {
+  const auto groupIterator = groupRegistry().find(groupId);
+  if (groupIterator == groupRegistry().end()) return false;
+  for (const uint64_t driverId : groupIterator->second.driverIds) {
+    const auto stateIterator = registry().find(driverId);
+    if (stateIterator != registry().end() &&
+        stateIterator->second.animation.has_value() &&
+        stateIterator->second.animation->groupId == groupId &&
+        animationNeedsForegroundReconciliation(stateIterator->second)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+bool pauseSpringForInactivity(
+    DriverState &state,
+    CFTimeInterval mediaTime) {
+  if (!state.animation.has_value() || !state.animation->started ||
+      state.animation->kind != AnimationKind::Spring) {
+    return true;
+  }
+  ActiveAnimation &animation = *state.animation;
+  if (animation.participants.empty()) {
+    animation.needsForegroundReconciliation = true;
+    return false;
+  }
+  bool paused = true;
+  for (const ViewKey key : animation.participants) {
+    paused = [viewForKey(key)
+        smoothClipPauseSpringAnimation:animation.animationId
+                           atMediaTime:mediaTime] && paused;
+  }
+  if (!paused) animation.needsForegroundReconciliation = true;
+  return paused;
+}
+
+bool resumeSpringAfterInactivity(
+    DriverState &state,
+    CFTimeInterval mediaTime,
+    CFTimeInterval catchUp) {
+  if (!state.animation.has_value() || !state.animation->started ||
+      state.animation->kind != AnimationKind::Spring) {
+    return true;
+  }
+  ActiveAnimation &animation = *state.animation;
+  bool resumed = !animation.participants.empty();
+  for (const ViewKey key : animation.participants) {
+    resumed = [viewForKey(key)
+        smoothClipResumeSpringAnimation:animation.animationId
+                            atMediaTime:mediaTime
+                             catchUpBy:catchUp] && resumed;
+  }
+  if (!resumed) animation.needsForegroundReconciliation = true;
+  return resumed;
+}
+
+bool resumeGroupSpringsAfterInactivity(
+    int32_t groupId,
+    CFTimeInterval mediaTime,
+    CFTimeInterval catchUp) {
+  const auto groupIterator = groupRegistry().find(groupId);
+  if (groupIterator == groupRegistry().end()) return false;
+  bool resumed = true;
+  for (const uint64_t driverId : groupIterator->second.driverIds) {
+    const auto stateIterator = registry().find(driverId);
+    if (stateIterator == registry().end() ||
+        !stateIterator->second.animation.has_value() ||
+        stateIterator->second.animation->groupId != groupId) {
+      return false;
+    }
+    resumed = resumeSpringAfterInactivity(
+        stateIterator->second, mediaTime, catchUp) && resumed;
+  }
+  return resumed;
+}
+
+void clearGroupInactivityExposure(int32_t groupId) {
+  const auto groupIterator = groupRegistry().find(groupId);
+  if (groupIterator == groupRegistry().end()) return;
+  for (const uint64_t driverId : groupIterator->second.driverIds) {
+    const auto stateIterator = registry().find(driverId);
+    if (stateIterator != registry().end() &&
+        stateIterator->second.animation.has_value() &&
+        stateIterator->second.animation->groupId == groupId) {
+      stateIterator->second.animation->exposedToInactivity = false;
+      stateIterator->second.animation->needsForegroundReconciliation = false;
+    }
+  }
+}
 
 Presentation unavailablePresentation() {
   // Non-finite geometry makes the JS side fall back to its current value
@@ -647,6 +767,7 @@ void tryStartGroup(int32_t groupId) {
     if (stateIterator == registry().end() ||
         !stateIterator->second.animation.has_value() ||
         stateIterator->second.animation->groupId != groupId ||
+        stateIterator->second.animation->started ||
         !driverReady(stateIterator->second)) {
       return;
     }
@@ -689,19 +810,14 @@ bool applicationIsActive() {
 void applicationWillResignActive() {
   NSCAssert(NSThread.isMainThread, @"SmoothClip registry is main-thread only");
   if (!applicationActiveState()) return;
+  const CFTimeInterval mediaTime = CACurrentMediaTime();
   applicationActiveState() = false;
-  std::vector<int32_t> groupIds;
-  groupIds.reserve(groupRegistry().size());
-  for (const auto &[groupId, group] : groupRegistry()) {
-    (void)group;
-    groupIds.push_back(groupId);
-  }
-  for (const int32_t groupId : groupIds) {
-    finishGroupForHostLoss(groupId);
-  }
+  applicationInactiveSince() = mediaTime;
   for (auto &[driverId, state] : registry()) {
-    if (!state.animation.has_value() || state.animation->groupId == 0) {
-      finishStandaloneAtTarget(driverId, state);
+    (void)driverId;
+    if (state.animation.has_value() && state.animation->started) {
+      state.animation->exposedToInactivity = true;
+      pauseSpringForInactivity(state, mediaTime);
     }
   }
 }
@@ -709,6 +825,14 @@ void applicationWillResignActive() {
 void applicationDidBecomeActive() {
   NSCAssert(NSThread.isMainThread, @"SmoothClip registry is main-thread only");
   if (applicationActiveState()) return;
+  const CFTimeInterval mediaTime = CACurrentMediaTime();
+  const CFTimeInterval inactiveDuration = applicationInactiveSince().has_value()
+      ? std::max((CFTimeInterval)0,
+                 mediaTime - *applicationInactiveSince())
+      : 0;
+  const CFTimeInterval springCatchUp =
+      std::min((CFTimeInterval)0.064, inactiveDuration);
+  applicationInactiveSince().reset();
   applicationActiveState() = true;
   std::vector<int32_t> groupIds;
   groupIds.reserve(groupRegistry().size());
@@ -717,13 +841,35 @@ void applicationDidBecomeActive() {
     groupIds.push_back(groupId);
   }
   for (const int32_t groupId : groupIds) {
-    tryStartGroup(groupId);
+    bool needsReconciliation = groupNeedsForegroundReconciliation(groupId);
+    if (!needsReconciliation) {
+      needsReconciliation = !resumeGroupSpringsAfterInactivity(
+          groupId, mediaTime, springCatchUp);
+    }
+    if (needsReconciliation) {
+      cancelGroupInternal(groupId, GroupCancelBehavior::Finish, true);
+    } else {
+      clearGroupInactivityExposure(groupId);
+      tryStartGroup(groupId);
+    }
   }
   for (auto &[driverId, state] : registry()) {
-    (void)driverId;
-    if (state.animation.has_value() && !state.animation->started &&
-        state.animation->groupId == 0 && anyDisplayableView(state)) {
-      startPendingAnimation(state);
+    if (!state.animation.has_value() || state.animation->groupId != 0) {
+      continue;
+    }
+    bool needsReconciliation = animationNeedsForegroundReconciliation(state);
+    if (!needsReconciliation) {
+      needsReconciliation = !resumeSpringAfterInactivity(
+          state, mediaTime, springCatchUp);
+    }
+    if (needsReconciliation) {
+      finishStandaloneAtTarget(driverId, state);
+    } else {
+      state.animation->exposedToInactivity = false;
+      state.animation->needsForegroundReconciliation = false;
+      if (!state.animation->started && anyDisplayableView(state)) {
+        startPendingAnimation(state);
+      }
     }
   }
 }
@@ -818,6 +964,9 @@ void viewDisplayabilityChanged(uint64_t driverId, SmoothClipView *view) {
     return;
   }
   if (![view smoothClipCanDisplay]) {
+    if (!applicationActiveState()) {
+      return;
+    }
     if (state.animation->groupId != 0 && state.animation->started) {
       finishGroupForHostLoss(state.animation->groupId);
     } else if (state.animation->started) {
@@ -841,7 +990,10 @@ void unregisterView(uint64_t driverId, SmoothClipView *view) {
   DriverState &state = iterator->second;
   const ViewKey key = keyForView(view);
   if (state.animation.has_value()) {
-    if (state.animation->groupId != 0 && state.animation->started) {
+    if (!applicationActiveState() && state.animation->started) {
+      state.animation->participants.erase(key);
+      state.animation->needsForegroundReconciliation = true;
+    } else if (state.animation->groupId != 0 && state.animation->started) {
       finishGroupForHostLoss(state.animation->groupId);
     } else if (state.animation->groupId == 0 && state.animation->started) {
       finishStandaloneAtTarget(driverId, state);
@@ -1611,6 +1763,10 @@ void viewAnimationDidStop(
 
   const ViewKey key = keyForView(view);
   if (state.animation->participants.erase(key) == 0) return;
+  if (!applicationActiveState() || state.animation->exposedToInactivity) {
+    state.animation->needsForegroundReconciliation = true;
+    return;
+  }
   state.animation->finished = state.animation->finished && finished;
   finishIfNoInstalledParticipants(driverId, state);
 }

package/ios/SmoothClipView.mm

@@ -365,6 +365,9 @@ static smoothclip::Presentation SmoothClipCanonicalSnapshot(
   smoothclip::TimingAnimation _timingAnimation;
   smoothclip::SpringAnimation _springAnimation;
   SmoothClipAnimationDelegate *_animationDelegate;
+  BOOL _springPausedForInactivity;
+  BOOL _pausedSpringHadMaskAnimation;
+  BOOL _pausedSpringHadShadowAnimation;
 
   // 'inherit' velocity samples (raw canonical geometry, per view); recording/
   // coalescing/projection live in the shared cpp/SmoothClipVelocityTracker.h
@@ -445,6 +448,9 @@ static smoothclip::Presentation SmoothClipCanonicalSnapshot(
     _ignoreAnimationCallback = NO;
     _activeAnimationId = 0;
     _activeAnimationKind = 0;
+    _springPausedForInactivity = NO;
+    _pausedSpringHadMaskAnimation = NO;
+    _pausedSpringHadShadowAnimation = NO;
     smoothclip::clearVelocitySamples(_velocitySamples);
     // App-state transitions are observed by the registry itself (see
     // installApplicationStateObservers): the active flag is process-global,
@@ -927,6 +933,9 @@ static smoothclip::Presentation SmoothClipCanonicalSnapshot(
   _activeAnimationId = 0;
   _activeAnimationKind = 0;
   _animationDelegate = nil;
+  _springPausedForInactivity = NO;
+  _pausedSpringHadMaskAnimation = NO;
+  _pausedSpringHadShadowAnimation = NO;
 }
 
 - (CABasicAnimation *)basicAnimationForKeyPath:(NSString *)keyPath
@@ -1318,6 +1327,12 @@ static smoothclip::Presentation SmoothClipCanonicalSnapshot(
     maskAnimation.duration = group.duration;
   }
 
+  // An explicit media-time origin is required to pause and resume spring
+  // groups without touching the parent layer clock (which would also pause
+  // consumer animations in the clipped subtree).
+  if (sharedBeginTime <= 0) {
+    sharedBeginTime = CACurrentMediaTime();
+  }
   if (sharedBeginTime > 0) {
     // Each layer receives the same absolute media timestamp translated into
     // its local clock. Group participants therefore advance from one epoch
@@ -1343,6 +1358,9 @@ static smoothclip::Presentation SmoothClipCanonicalSnapshot(
   _animationDelegate.driverId = _driverId;
   _animationDelegate.animationId = _activeAnimationId;
   group.delegate = _animationDelegate;
+  _springPausedForInactivity = NO;
+  _pausedSpringHadMaskAnimation = NO;
+  _pausedSpringHadShadowAnimation = NO;
   [layer addAnimation:group forKey:@"smoothClip.geometry"];
   [_contentContainer.layer addAnimation:contentGroup
                                  forKey:@"smoothClip.content"];
@@ -1465,6 +1483,154 @@ static smoothclip::Presentation SmoothClipCanonicalSnapshot(
   }
 }
 
+- (BOOL)smoothClipPauseSpringAnimation:(int32_t)animationId
+                           atMediaTime:(CFTimeInterval)mediaTime {
+  if (_activeAnimationId != animationId || _activeAnimationKind != 2 ||
+      _springPausedForInactivity) {
+    return NO;
+  }
+
+  CALayer *geometryLayer = _clipContainer.layer;
+  CALayer *contentLayer = _contentContainer.layer;
+  CAAnimation *installedGeometry =
+      [geometryLayer animationForKey:@"smoothClip.geometry"];
+  CAAnimation *installedContent =
+      [contentLayer animationForKey:@"smoothClip.content"];
+  if (installedGeometry == nil || installedContent == nil) return NO;
+
+  auto pausedCopy = ^CAAnimation *(CALayer *layer, CAAnimation *installed) {
+    if (installed == nil) return (CAAnimation *)nil;
+    CAAnimation *paused = [installed copy];
+    const CFTimeInterval localNow =
+        [layer convertTime:mediaTime fromLayer:nil];
+    const CFTimeInterval elapsed = std::clamp(
+        localNow - installed.beginTime,
+        (CFTimeInterval)0,
+        installed.duration);
+    paused.speed = 0;
+    paused.timeOffset = elapsed;
+    paused.beginTime = 0;
+    return paused;
+  };
+
+  CAAnimation *geometry = pausedCopy(geometryLayer, installedGeometry);
+  CAAnimation *content = pausedCopy(contentLayer, installedContent);
+  CAAnimation *installedMask =
+      [_unequalCornerMask animationForKey:@"smoothClip.mask"];
+  CAAnimation *mask = pausedCopy(_unequalCornerMask, installedMask);
+  CAAnimation *installedShadow =
+      [_shadowLayer animationForKey:@"smoothClip.shadow"];
+  CAAnimation *shadow = pausedCopy(_shadowLayer, installedShadow);
+
+  _animationDelegate.invalidated = YES;
+  _ignoreAnimationCallback = YES;
+  [geometryLayer removeAnimationForKey:@"smoothClip.geometry"];
+  [contentLayer removeAnimationForKey:@"smoothClip.content"];
+  [_unequalCornerMask removeAnimationForKey:@"smoothClip.mask"];
+  [_shadowLayer removeAnimationForKey:@"smoothClip.shadow"];
+
+  _animationDelegate = [SmoothClipAnimationDelegate new];
+  _animationDelegate.view = self;
+  _animationDelegate.driverId = _driverId;
+  _animationDelegate.animationId = animationId;
+  geometry.delegate = _animationDelegate;
+  [geometryLayer addAnimation:geometry forKey:@"smoothClip.geometry"];
+  [contentLayer addAnimation:content forKey:@"smoothClip.content"];
+  if (mask != nil) {
+    [_unequalCornerMask addAnimation:mask forKey:@"smoothClip.mask"];
+  }
+  if (shadow != nil) {
+    [_shadowLayer addAnimation:shadow forKey:@"smoothClip.shadow"];
+  }
+  _ignoreAnimationCallback = NO;
+  _springPausedForInactivity = YES;
+  _pausedSpringHadMaskAnimation = mask != nil;
+  _pausedSpringHadShadowAnimation = shadow != nil;
+  return YES;
+}
+
+- (BOOL)smoothClipResumeSpringAnimation:(int32_t)animationId
+                            atMediaTime:(CFTimeInterval)mediaTime
+                             catchUpBy:(CFTimeInterval)catchUp {
+  if (_activeAnimationId != animationId || _activeAnimationKind != 2 ||
+      !_springPausedForInactivity) {
+    return NO;
+  }
+
+  CALayer *geometryLayer = _clipContainer.layer;
+  CALayer *contentLayer = _contentContainer.layer;
+  CAAnimation *installedGeometry =
+      [geometryLayer animationForKey:@"smoothClip.geometry"];
+  CAAnimation *installedContent =
+      [contentLayer animationForKey:@"smoothClip.content"];
+  CAAnimation *installedMask =
+      [_unequalCornerMask animationForKey:@"smoothClip.mask"];
+  CAAnimation *installedShadow =
+      [_shadowLayer animationForKey:@"smoothClip.shadow"];
+  if (installedGeometry == nil || installedContent == nil ||
+      (_pausedSpringHadMaskAnimation && installedMask == nil) ||
+      (_pausedSpringHadShadowAnimation && installedShadow == nil)) {
+    return NO;
+  }
+
+  auto resumedCopy = ^CAAnimation *(CALayer *layer, CAAnimation *installed) {
+    if (installed == nil) return (CAAnimation *)nil;
+    CAAnimation *resumed = [installed copy];
+    const CFTimeInterval localNow =
+        [layer convertTime:mediaTime fromLayer:nil];
+    const CFTimeInterval resumedTime = std::min(
+        installed.duration,
+        std::max((CFTimeInterval)0, installed.timeOffset + catchUp));
+    resumed.speed = 1;
+    resumed.timeOffset = 0;
+    resumed.beginTime = localNow - resumedTime;
+    return resumed;
+  };
+
+  CAAnimation *geometry = resumedCopy(geometryLayer, installedGeometry);
+  CAAnimation *content = resumedCopy(contentLayer, installedContent);
+  CAAnimation *mask = resumedCopy(_unequalCornerMask, installedMask);
+  CAAnimation *shadow = resumedCopy(_shadowLayer, installedShadow);
+
+  _animationDelegate.invalidated = YES;
+  _ignoreAnimationCallback = YES;
+  [geometryLayer removeAnimationForKey:@"smoothClip.geometry"];
+  [contentLayer removeAnimationForKey:@"smoothClip.content"];
+  [_unequalCornerMask removeAnimationForKey:@"smoothClip.mask"];
+  [_shadowLayer removeAnimationForKey:@"smoothClip.shadow"];
+
+  _animationDelegate = [SmoothClipAnimationDelegate new];
+  _animationDelegate.view = self;
+  _animationDelegate.driverId = _driverId;
+  _animationDelegate.animationId = animationId;
+  geometry.delegate = _animationDelegate;
+  [geometryLayer addAnimation:geometry forKey:@"smoothClip.geometry"];
+  [contentLayer addAnimation:content forKey:@"smoothClip.content"];
+  if (mask != nil) {
+    [_unequalCornerMask addAnimation:mask forKey:@"smoothClip.mask"];
+  }
+  if (shadow != nil) {
+    [_shadowLayer addAnimation:shadow forKey:@"smoothClip.shadow"];
+  }
+  _ignoreAnimationCallback = NO;
+  _springPausedForInactivity = NO;
+  _pausedSpringHadMaskAnimation = NO;
+  _pausedSpringHadShadowAnimation = NO;
+  return YES;
+}
+
+- (BOOL)smoothClipHasInstalledAnimation:(int32_t)animationId {
+  return _activeAnimationId == animationId &&
+      [_clipContainer.layer animationForKey:@"smoothClip.geometry"] != nil &&
+      [_contentContainer.layer animationForKey:@"smoothClip.content"] != nil &&
+      (!_springPausedForInactivity ||
+       (!_pausedSpringHadMaskAnimation ||
+        [_unequalCornerMask animationForKey:@"smoothClip.mask"] != nil)) &&
+      (!_springPausedForInactivity ||
+       (!_pausedSpringHadShadowAnimation ||
+        [_shadowLayer animationForKey:@"smoothClip.shadow"] != nil));
+}
+
 - (void)smoothClipAnimationDidStopWithDriverId:(uint64_t)driverId
                                     animationId:(int32_t)animationId
                                        finished:(BOOL)finished {
@@ -1472,6 +1638,9 @@ static smoothclip::Presentation SmoothClipCanonicalSnapshot(
   _activeAnimationId = 0;
   _activeAnimationKind = 0;
   _animationDelegate = nil;
+  _springPausedForInactivity = NO;
+  _pausedSpringHadMaskAnimation = NO;
+  _pausedSpringHadShadowAnimation = NO;
   [_unequalCornerMask removeAnimationForKey:@"smoothClip.mask"];
   [_shadowLayer removeAnimationForKey:@"smoothClip.shadow"];
   [self applyStaticCornerRepresentation:[self canonicalGeometryValue]];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-smooth-clip-view",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Layout-free animated rounded clipping for React Native Fabric",
   "main": "./lib/module/index.js",
   "module": "./lib/module/index.js",