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

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+## [0.4.3](https://github.com/kbrattli/react-native-smooth-clip-view/releases/tag/v0.4.3) — 2026-09-11
+
+### Rotate and fade the whole clip
+
+Animate rotation and opacity alongside clip geometry on iOS and Android. The
+aperture, its content, and its shadow move and fade together inside the fixed
+host, using the existing controller and atomic group APIs.
+
+- **Rotation:** pass degree or radian strings such as `'12deg'` or `'0.2rad'`.
+  Rotation is clockwise around the current aperture center, after content
+  translation and scale. Angles interpolate numerically, so `'720deg'` animates
+  two full turns from zero. Interruption snapshots preserve those turns.
+- **Group opacity:** set `opacity` to fade content and shadow together, including
+  overlapping children. Finite values clamp to `[0, 1]`; spring rendering clamps
+  opacity while preserving the spring's internal motion state.
+- **Animation continuity:** rotation and opacity participate in timing and
+  spring animations, cancellation snapshots, and background spring pause/resume.
+  Explicit spring velocity applies to these channels too.
+- **Touch and accessibility:** hit testing follows the rotated aperture, including
+  clips rotated back into the viewport. Fully transparent content accepts no new
+  touches and is hidden from accessibility.
+- **Rendering:** appearance updates use native compositor properties without
+  Yoga layout work or rebuilding unchanged clipping paths. Translucent groups
+  may require offscreen compositing.
+- **Types and validation:** export `ClipRotation`, include rotation and opacity in
+  canonical presentations, and reject malformed angles or nonfinite values
+  atomically. Add JavaScript and native regression coverage for these behaviors.
+
+### Usage and upgrade notes
+
+`rotation` defaults to `'0deg'` and `opacity` to `1`. Presentations are complete:
+omitting either field resets it to its default. Snapshots return rotation in
+radians. See [Rotate and fade a clip](./README.md#rotate-and-fade-a-clip) for a
+controller example.
+
+**Rebuild your native app after upgrading**, and run `pod install` on iOS. The
+native presentation protocol has changed; JavaScript from 0.4.3 must run with the
+matching native library, rather than an older binary updated only through OTA.
+
+[All changes since 0.4.2](https://github.com/kbrattli/react-native-smooth-clip-view/compare/v0.4.2...v0.4.3)
+
+Earlier release notes are available on [GitHub Releases](https://github.com/kbrattli/react-native-smooth-clip-view/releases).

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
 
@@ -134,9 +134,37 @@ defaults match Reanimated 4.5: mass `4`, stiffness `900`, damping `120`, and
 relative energy threshold `6e-9`. A spring is rejected when its resolved native
 trajectory could make `contentScale` nonpositive.
 
+`velocity` is a shared initial progress velocity in inverse seconds, defaulting
+to `0`. Each changing channel starts with velocity proportional to its remaining
+distance: `velocity * (target - start)`. This includes rotation (in radians) and
+opacity. Public controllers and groups do not automatically inherit gesture
+velocity; starting a new spring after `beginInteraction()` still defaults to `0`
+unless `velocity` is supplied. Pausing and resuming an existing native spring
+preserves its internal motion state; public snapshots return clamped opacity.
+
+The internal native standalone path also supports inherited velocity. Its
+projection uses only clip position, size, corner radii, and content translation.
+Rotation, opacity, content scale, and shadow channels do not contribute to that
+projection. The resulting normalized velocity can drive all changing channels,
+including rotation and opacity, without mixing their units into the projection.
+Rotation/opacity-only motion therefore supplies no inherited velocity.
+
 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
@@ -176,6 +204,15 @@ APIs share validation, run ownership, and completion behavior.
 - Corner-overlap scaling follows CSS rules against the requested rectangle.
 - `contentTranslateX`, `contentTranslateY`, and positive `contentScale` animate
   with the aperture.
+- `rotation` accepts degree or radian strings (for example, `'12deg'` or
+  `'0.2rad'`) and defaults to `'0deg'`. It rotates the aperture, content, and
+  shadow together, clockwise around the current aperture center. Existing
+  content translation and scale happen before this rotation. The host stays
+  fixed and crops the rotated result.
+- `opacity` defaults to `1` and fades the aperture's content and shadow as one
+  group. Finite values clamp to `[0, 1]`; malformed angles and nonfinite values
+  reject the complete presentation. Spring opacity is clamped for rendering
+  without clamping its internal spring state.
 - Circular and continuous curves and independent corner radii are supported.
 - One outset `boxShadow` is supported. It escapes the aperture but not the host.
 - A fully off-host aperture is not touchable, even when only its shadow overlaps.
@@ -185,6 +222,52 @@ APIs share validation, run ownership, and completion behavior.
 Use `getSmoothClipCapabilities()` when a consumer needs to decide whether a
 complex native path can be promoted on the current platform.
 
+### Rotate and fade a clip
+
+Rotation and opacity are presentation fields, so they use the same controller
+and group methods as geometry. For example, start a tilted, translucent card
+and animate it upright:
+
+```ts
+const clip = useSmoothClipController({
+  clip: { x: 24, y: 80, width: 240, height: 320, radius: 24 },
+  contentTranslateX: 0,
+  contentTranslateY: 0,
+  rotation: '-12deg',
+  opacity: 0.4,
+});
+
+// Attach this controller to <SmoothClipView controller={clip}> as above.
+const reveal = () =>
+  clip.react.animateTo(
+    {
+      clip: { x: 24, y: 80, width: 240, height: 320, radius: 24 },
+      contentTranslateX: 0,
+      contentTranslateY: 0,
+      rotation: '0deg',
+      opacity: 1,
+    },
+    { type: 'spring', stiffness: 180, damping: 22 }
+  );
+```
+
+For gesture-driven updates, supply the same fields from a UI-runtime worklet:
+
+```ts
+clip.ui.setFrame({ ...frame, rotation: '12deg', opacity: 0.5 });
+```
+
+Angles interpolate numerically, so `'720deg'` requests two full turns from zero;
+there is no automatic shortest-path wrapping. Interruption snapshots preserve
+full turns and return rotation as a radian string. Each presentation is complete:
+omitting rotation or opacity resets that field to its default. At zero opacity,
+the content admits no new touches and is hidden from accessibility.
+
+When upgrading to **0.4.3**, rebuild the native app (and run `pod install` on
+iOS). The native presentation protocol includes new rotation and opacity
+channels, so a JavaScript-only OTA update cannot upgrade an older native build.
+See the [changelog](./CHANGELOG.md) for release details.
+
 ## Performance contract
 
 - One worklet-to-native call per `ui.setFrame`, or per group batch.
@@ -192,6 +275,10 @@ complex native path can be promoted on the current platform.
 - The shadow-disabled rendering path keeps no shadow drawing resources.
 - The fixed host is the maximum rendering viewport; consumers should size it to
   the region in which content and shadow may appear.
+- Rotation and opacity update native compositor properties without Yoga work
+  or rebuilding unchanged clipping paths. Correctly fading overlapping children
+  may require offscreen compositing; large translucent groups can cost more GPU
+  time than opaque ones. No rasterization or software layer is forced.
 
 ## License
 

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

@@ -22,7 +22,7 @@ struct JSmoothClipView : facebook::jni::JavaClass<JSmoothClipView> {
       double contentTranslateXPx,
       double contentTranslateYPx,
       double contentScale,
-      const Shadow &shadowPx) const;
+      const Shadow &shadowPx, double rotation, double opacity) const;
   void setAutonomousMotion(bool active) const;
 };
 
@@ -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

@@ -27,7 +27,7 @@ namespace smoothclip {
 namespace {
 
 constexpr double kMaxSafeJavaScriptInteger = 9007199254740991.0;
-constexpr size_t kPresentationStride = 21;
+constexpr size_t kPresentationStride = 23;
 constexpr size_t kSnapshotStride = kPresentationStride + 1;
 constexpr size_t kMotionEntryStride = kPresentationStride * 2 + 2;
 
@@ -61,7 +61,8 @@ bool finiteBasePresentation(const Presentation &presentation) {
       std::isfinite(presentation.contentTranslateX) &&
       std::isfinite(presentation.contentTranslateY) &&
       std::isfinite(presentation.contentScale) &&
-      presentation.contentScale > 0;
+      presentation.contentScale > 0 &&
+      std::isfinite(presentation.rotation) && std::isfinite(presentation.opacity);
 }
 
 bool finitePresentation(const Presentation &presentation) {
@@ -154,7 +155,7 @@ bool presentationAt(
       Shadow{
           packet[12] == 1.0,
           packet[13], packet[14], packet[15], packet[16],
-          packet[17], packet[18], packet[19], packet[20]}};
+          packet[17], packet[18], packet[19], packet[20]}, packet[21], packet[22]};
   return finitePresentation(result);
 }
 
@@ -190,6 +191,8 @@ void appendPresentation(
   result.setValueAtIndex(runtime, offset++, presentation.shadow.offsetY);
   result.setValueAtIndex(runtime, offset++, presentation.shadow.blurRadius);
   result.setValueAtIndex(runtime, offset++, presentation.shadow.spreadDistance);
+  result.setValueAtIndex(runtime, offset++, presentation.rotation);
+  result.setValueAtIndex(runtime, offset++, presentation.opacity);
 }
 
 Array presentationArray(Runtime &runtime, const Presentation &presentation) {
@@ -551,9 +554,9 @@ void installBindings(
       });
 
   setHostFunction(
-      runtime, bindings, "setClipFrameScalars", 22,
+      runtime, bindings, "setClipFrameScalars", 24,
       [](Runtime &, const Value &, const Value *args, size_t count) -> Value {
-        if (count < 22) return Value::undefined();
+        if (count < 24) return Value::undefined();
         const double driverId = args[0].asNumber();
         Geometry geometry{
             args[1].asNumber(), args[2].asNumber(), args[3].asNumber(),
@@ -584,7 +587,7 @@ void installBindings(
                 args[19].asNumber(),
                 args[20].asNumber(),
                 args[21].asNumber(),
-            }};
+            }, args[22].asNumber(), args[23].asNumber()};
         if (validDriverId(driverId) && validCurve(args[9].asNumber()) &&
             finitePresentation(presentation)) {
           setPresentation(
@@ -828,6 +831,8 @@ void nativeRegisterView(
     jdouble shadowOffsetY,
     jdouble shadowBlurRadius,
     jdouble shadowSpreadDistance,
+    jdouble rotation,
+    jdouble opacity,
     jdouble density,
     jdouble widthPx,
     jdouble heightPx,
@@ -842,7 +847,8 @@ void nativeRegisterView(
       !std::isfinite(shadowBlue) || !std::isfinite(shadowAlpha) ||
       !std::isfinite(shadowOffsetX) ||
       !std::isfinite(shadowOffsetY) || !std::isfinite(shadowBlurRadius) ||
-      !std::isfinite(shadowSpreadDistance) || contentScale <= 0 ||
+      !std::isfinite(shadowSpreadDistance) ||
+      !std::isfinite(rotation) || !std::isfinite(opacity) || contentScale <= 0 ||
       shadowRed < 0 || shadowRed > 1 || shadowGreen < 0 || shadowGreen > 1 ||
       shadowBlue < 0 || shadowBlue > 1 || shadowAlpha < 0 || shadowAlpha > 1 ||
       shadowBlurRadius < 0 ||
@@ -874,7 +880,7 @@ void nativeRegisterView(
       static_cast<uint64_t>(driverId),
       view,
       smoothclip::Presentation{
-          geometry, contentTranslateX, contentTranslateY, contentScale, shadow},
+          geometry, contentTranslateX, contentTranslateY, contentScale, shadow, rotation, opacity},
       density,
       widthPx,
       heightPx,
@@ -918,6 +924,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 +954,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.
@@ -448,7 +458,7 @@ void deliverToView(const ViewEntry &entry, const Presentation &presentation) {
       translateX,
       translateY,
       presentation.contentScale,
-      shadowPx);
+      shadowPx, presentation.rotation, presentation.opacity);
 }
 
 void applyToViews(DriverState &state, const Presentation &presentation) {
@@ -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);
@@ -1630,7 +1705,7 @@ void JSmoothClipView::applyClip(const Presentation &presentation) const {
               jdouble,
               jdouble,
               jdouble,
-              jdouble)>("setClipPresentationDip");
+              jdouble, jdouble, jdouble)>("setClipPresentationDip");
   method(
       self(),
       presentation.clip.x,
@@ -1657,7 +1732,7 @@ void JSmoothClipView::applyClip(const Presentation &presentation) const {
       presentation.shadow.offsetX,
       presentation.shadow.offsetY,
       presentation.shadow.blurRadius,
-      presentation.shadow.spreadDistance);
+      presentation.shadow.spreadDistance, presentation.rotation, presentation.opacity);
 }
 
 void JSmoothClipView::applyClipPx(
@@ -1665,7 +1740,7 @@ void JSmoothClipView::applyClipPx(
     double contentTranslateXPx,
     double contentTranslateYPx,
     double contentScale,
-    const Shadow &shadowPx) const {
+    const Shadow &shadowPx, double rotation, double opacity) const {
   static const auto method =
       javaClassStatic()
           ->getMethod<void(
@@ -1689,7 +1764,7 @@ void JSmoothClipView::applyClipPx(
               jfloat,
               jfloat,
               jfloat,
-              jfloat)>("setClipPresentationPx");
+              jfloat, jdouble, jfloat)>("setClipPresentationPx");
   method(
       self(),
       static_cast<jfloat>(clip.left),
@@ -1712,7 +1787,7 @@ void JSmoothClipView::applyClipPx(
       static_cast<jfloat>(shadowPx.offsetX),
       static_cast<jfloat>(shadowPx.offsetY),
       static_cast<jfloat>(shadowPx.blurRadius),
-      static_cast<jfloat>(shadowPx.spreadDistance));
+      static_cast<jfloat>(shadowPx.spreadDistance), rotation, static_cast<jfloat>(opacity));
 }
 
 void JSmoothClipView::setAutonomousMotion(bool active) const {

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

@@ -240,3 +240,26 @@ internal fun clipAccessibility(
     } else {
         requestedAccessibility
     }
+
+/** Conservative for rounded corners, exact for the rotated bounding rectangle. */
+internal fun rotatedRectIntersectsHost(
+    left: Double, top: Double, right: Double, bottom: Double,
+    pivotX: Double, pivotY: Double, rotation: Double, hostWidth: Double, hostHeight: Double,
+): Boolean {
+    if (right <= left || bottom <= top || hostWidth <= 0 || hostHeight <= 0) return false
+    if (rotation == 0.0) return right > 0 && bottom > 0 && left < hostWidth && top < hostHeight
+    val c = kotlin.math.cos(rotation)
+    val s = kotlin.math.sin(rotation)
+    val dx = (left + right) / 2 - pivotX
+    val dy = (top + bottom) / 2 - pivotY
+    val x = pivotX + c * dx - s * dy - hostWidth / 2
+    val y = pivotY + s * dx + c * dy - hostHeight / 2
+    val hw = (right - left) / 2
+    val hh = (bottom - top) / 2
+    val ac = kotlin.math.abs(c)
+    val ass = kotlin.math.abs(s)
+    return kotlin.math.abs(x) < hostWidth / 2 + ac * hw + ass * hh &&
+        kotlin.math.abs(y) < hostHeight / 2 + ass * hw + ac * hh &&
+        kotlin.math.abs(c * x + s * y) < hw + ac * hostWidth / 2 + ass * hostHeight / 2 &&
+        kotlin.math.abs(-s * x + c * y) < hh + ass * hostWidth / 2 + ac * hostHeight / 2
+}

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

@@ -43,6 +43,8 @@ internal object SmoothClipBindings {
         shadowOffsetY: Double,
         shadowBlurRadius: Double,
         shadowSpreadDistance: Double,
+        rotation: Double,
+        opacity: Double,
         density: Double,
         widthPx: Double,
         heightPx: Double,
@@ -77,6 +79,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 +103,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
@@ -104,6 +140,8 @@ class SmoothClipModule(context: ReactApplicationContext) :
         shadowOffsetY: Double,
         shadowBlurRadius: Double,
         shadowSpreadDistance: Double,
+        rotation: Double,
+        opacity: Double,
     ) = Unit
 
     override fun beginInteraction(driverId: Double): WritableArray =