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

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

@@ -5,6 +5,7 @@ import android.graphics.BlurMaskFilter
 import android.graphics.Canvas
 import android.graphics.Color
 import android.graphics.Outline
+import android.graphics.Matrix
 import android.graphics.Paint
 import android.graphics.Path
 import android.graphics.Region
@@ -20,6 +21,8 @@ import com.facebook.react.views.view.ReactViewGroup
 import kotlin.math.roundToInt
 import kotlin.math.abs
 import kotlin.math.pow
+import kotlin.math.cos
+import kotlin.math.sin
 
 class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
     private val clipPath = Path()
@@ -41,6 +44,16 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
                 }
             }
         }
+    // One compositing group; arbitrary React children may overlap when faded.
+    internal val presentationContainer = object : ReactViewGroup(context) {
+        override fun hasOverlappingRendering(): Boolean = true
+        override fun dispatchDraw(canvas: Canvas) {
+            drawBoxShadow(canvas)
+            super.dispatchDraw(canvas)
+        }
+    }
+    private var requestedRotation = 0.0
+    private var requestedOpacity = 1f
     internal val contentContainer = ReactViewGroup(context)
     private var requestedX = 0f
     private var requestedY = 0f
@@ -78,6 +91,9 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
     private var requestedImportantForAccessibility = IMPORTANT_FOR_ACCESSIBILITY_AUTO
     private var autonomousMotion = false
     private var acceptingTouchStream = false
+    private var forwardingOverflowTouchStream = false
+    private val inversePresentationMatrix = Matrix()
+    private val touchPoint = FloatArray(2)
 
     /** Driver this view is registered with in the native registry (0 = none). */
     internal var boundDriverId: Double = 0.0
@@ -104,7 +120,8 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
 
     init {
         clipContainer.addView(contentContainer)
-        super.addView(clipContainer)
+        presentationContainer.addView(clipContainer)
+        super.addView(presentationContainer)
         if (supportsPathOutlineClipping) {
             clipContainer.outlineProvider = clipOutlineProvider
             clipContainer.clipToOutline = true
@@ -139,6 +156,8 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         shadowOffsetY: Double = 0.0,
         shadowBlurRadius: Double = 0.0,
         shadowSpreadDistance: Double = 0.0,
+        rotation: Double = 0.0,
+        opacity: Double = 1.0,
     ) {
         if (!x.isFinite() || !y.isFinite() || !width.isFinite() ||
             !height.isFinite() || !topLeftRadius.isFinite() ||
@@ -149,7 +168,7 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
             !shadowBlue.isFinite() || !shadowAlpha.isFinite() ||
             !shadowOffsetX.isFinite() ||
             !shadowOffsetY.isFinite() || !shadowBlurRadius.isFinite() ||
-            !shadowSpreadDistance.isFinite() || contentScale <= 0.0 ||
+            !shadowSpreadDistance.isFinite() || !rotation.isFinite() || !opacity.isFinite() || contentScale <= 0.0 ||
             shadowRed !in 0.0..1.0 || shadowGreen !in 0.0..1.0 ||
             shadowBlue !in 0.0..1.0 || shadowAlpha !in 0.0..1.0 ||
             shadowBlurRadius < 0.0 ||
@@ -197,6 +216,8 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         requestedCurveCode = curveCode
         requestedContentTranslateX = nextContentTranslateX
         requestedContentTranslateY = nextContentTranslateY
+        requestedRotation = rotation
+        requestedOpacity = opacity.coerceIn(0.0, 1.0).toFloat()
         requestedContentScale = nextContentScale
         storeShadow(
             shadowEnabled,
@@ -236,6 +257,8 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         shadowOffsetY: Float = 0f,
         shadowBlurRadius: Float = 0f,
         shadowSpreadDistance: Float = 0f,
+        rotation: Double = 0.0,
+        opacity: Float = 1f,
     ) {
         if (!left.isFinite() || !top.isFinite() || !right.isFinite() ||
             !bottom.isFinite() || !topLeftRadius.isFinite() ||
@@ -246,7 +269,7 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
             !shadowBlue.isFinite() || !shadowAlpha.isFinite() ||
             !shadowOffsetX.isFinite() ||
             !shadowOffsetY.isFinite() || !shadowBlurRadius.isFinite() ||
-            !shadowSpreadDistance.isFinite() || contentScale <= 0f ||
+            !shadowSpreadDistance.isFinite() || !rotation.isFinite() || !opacity.isFinite() || contentScale <= 0f ||
             shadowRed !in 0f..1f || shadowGreen !in 0f..1f ||
             shadowBlue !in 0f..1f || shadowAlpha !in 0f..1f ||
             shadowBlurRadius < 0f ||
@@ -259,6 +282,8 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         try {
             requestedContentTranslateX = contentTranslateX
             requestedContentTranslateY = contentTranslateY
+            requestedRotation = rotation
+            requestedOpacity = opacity.coerceIn(0f, 1f)
             requestedContentScale = contentScale
             storeShadow(
                 shadowEnabled,
@@ -342,14 +367,14 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         requestedShadowBlurRadius = blurRadius
         requestedShadowSpreadDistance = spreadDistance
         if (!isVisible) {
-            if (wasVisible) invalidate()
+            if (wasVisible) presentationContainer.invalidate()
             return
         }
         if (paintChanged || boxShadowPaint == null) updateBoxShadowPaint()
         if (pathChanged || !wasVisible || boxShadowPath == null) {
             rebuildBoxShadowPath()
         }
-        if (paintChanged || pathChanged || !wasVisible) invalidate()
+        if (paintChanged || pathChanged || !wasVisible) presentationContainer.invalidate()
     }
 
     private fun updateBoxShadowPaint() {
@@ -414,28 +439,31 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         val hostSaveCount = canvas.save()
         canvas.clipRect(0f, 0f, width.toFloat(), height.toFloat())
         try {
-            val shadowPath = boxShadowPath
-            val shadowPaint = boxShadowPaint
-            if (requestedShadowEnabled && !clipIsEmpty &&
-                requestedShadowAlpha > 0f && shadowPath != null &&
-                shadowPaint != null && !shadowPath.isEmpty
-            ) {
-                val apertureSaveCount = canvas.save()
-                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-                    canvas.clipOutPath(clipPath)
-                } else {
-                    @Suppress("DEPRECATION")
-                    canvas.clipPath(clipPath, Region.Op.DIFFERENCE)
-                }
-                canvas.drawPath(shadowPath, shadowPaint)
-                canvas.restoreToCount(apertureSaveCount)
-            }
             super.dispatchDraw(canvas)
         } finally {
             canvas.restoreToCount(hostSaveCount)
         }
     }
 
+    private fun drawBoxShadow(canvas: Canvas) {
+        val shadowPath = boxShadowPath
+        val shadowPaint = boxShadowPaint
+        if (requestedShadowEnabled && !clipIsEmpty &&
+            requestedShadowAlpha > 0f && shadowPath != null &&
+            shadowPaint != null && !shadowPath.isEmpty
+        ) {
+            val apertureSaveCount = canvas.save()
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                canvas.clipOutPath(clipPath)
+            } else {
+                @Suppress("DEPRECATION")
+                canvas.clipPath(clipPath, Region.Op.DIFFERENCE)
+            }
+            canvas.drawPath(shadowPath, shadowPaint)
+            canvas.restoreToCount(apertureSaveCount)
+        }
+    }
+
     private fun applyCanonicalClipPx(
         left: Float,
         top: Float,
@@ -470,10 +498,12 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         applyContentTransform()
 
         clipIsEmpty = isEmpty
+        applyPresentationTransform()
         reapplyClipPresentation()
 
         if (!geometryChanged) return
 
+        updateOverflowInsets()
         clipPath.reset()
         if (!isEmpty) {
             if (curveCode == CLIP_CURVE_CIRCULAR && radiiAreUniform) {
@@ -507,7 +537,29 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         } else {
             clipContainer.invalidate()
         }
-        if (requestedShadowEnabled) invalidate()
+        if (requestedShadowEnabled) presentationContainer.invalidate()
+    }
+
+    private fun updateOverflowInsets() {
+        // React Native's touch-target walk also needs to see the unrotated overflow.
+        val left = kotlin.math.floor(minOf(0f, clipLeft).toDouble()).toInt()
+        val top = kotlin.math.floor(minOf(0f, clipTop).toDouble()).toInt()
+        val right = kotlin.math.floor(minOf(0f, width - clipRight).toDouble()).toInt()
+        val bottom = kotlin.math.floor(minOf(0f, height - clipBottom).toDouble()).toInt()
+        presentationContainer.setOverflowInset(left, top, right, bottom)
+        clipContainer.setOverflowInset(left, top, right, bottom)
+    }
+
+    private fun applyPresentationTransform() {
+        // The pivot is immaterial at zero rotation; avoid dirtying a stationary parent.
+        val cx = if (requestedRotation == 0.0) 0f else (clipLeft + clipRight) / 2f
+        val cy = if (requestedRotation == 0.0) 0f else (clipTop + clipBottom) / 2f
+        // Keep unwrapped doubles in the registry. Only the render transform is periodic.
+        val degrees = Math.toDegrees(requestedRotation % (2 * Math.PI)).toFloat()
+        if (presentationContainer.pivotX != cx) presentationContainer.pivotX = cx
+        if (presentationContainer.pivotY != cy) presentationContainer.pivotY = cy
+        if (presentationContainer.rotation != degrees) presentationContainer.rotation = degrees
+        if (presentationContainer.alpha != requestedOpacity) presentationContainer.alpha = requestedOpacity
     }
 
     private fun applyContentTransform() {
@@ -525,8 +577,10 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
 
     override fun onSizeChanged(w: Int, h: Int, oldw: Int, oldh: Int) {
         super.onSizeChanged(w, h, oldw, oldh)
+        presentationContainer.layout(0, 0, w, h)
         clipContainer.layout(0, 0, w, h)
         contentContainer.layout(0, 0, w, h)
+        updateOverflowInsets()
         applyContentTransform()
         if (boundDriverId != 0.0) {
             // Host metrics only gate lifecycle readiness. Redelivery remains
@@ -602,7 +656,14 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
     private fun containsRoundedPoint(x: Float, y: Float): Boolean {
         // Reuse the exact path supplied to the Outline. Hit testing therefore
         // follows the rendered aperture, including continuous corners.
-        return !clipIsEmpty && containsPathPoint(clipPath, x, y)
+        if (clipIsEmpty || requestedOpacity <= 0f) return false
+        val cx = (clipLeft + clipRight) / 2.0
+        val cy = (clipTop + clipBottom) / 2.0
+        val c = cos(requestedRotation)
+        val sn = sin(requestedRotation)
+        val localX = cx + c * (x - cx) + sn * (y - cy)
+        val localY = cy - sn * (x - cx) + c * (y - cy)
+        return containsPathPoint(clipPath, localX.toFloat(), localY.toFloat())
     }
 
     override fun dispatchTouchEvent(event: MotionEvent): Boolean {
@@ -611,12 +672,34 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
             // The aperture gates admission only. Once accepted, the stream
             // belongs to Android until its real UP or CANCEL arrives.
             clearTouchState()
-            if (!containsRoundedPoint(event.x, event.y)) return false
+            if (event.x < 0 || event.y < 0 || event.x >= width || event.y >= height ||
+                !containsRoundedPoint(event.x, event.y)) return false
             acceptingTouchStream = true
+            presentationContainer.matrix.invert(inversePresentationMatrix)
+            touchPoint[0] = event.x
+            touchPoint[1] = event.y
+            inversePresentationMatrix.mapPoints(touchPoint)
+            forwardingOverflowTouchStream = touchPoint[0] < 0 || touchPoint[1] < 0 ||
+                touchPoint[0] >= width || touchPoint[1] >= height
         }
 
         if (!acceptingTouchStream) return false
-        val result = super.dispatchTouchEvent(event)
+        // ViewGroup's native dispatch rejects children outside their layout bounds,
+        // even when clipChildren=false. Bypass only the internal presentation wrapper
+        // for an overflow stream; the clip container still dispatches to transformed
+        // content normally. Retain this route through the real UP/CANCEL.
+        val result = if (forwardingOverflowTouchStream) {
+            presentationContainer.matrix.invert(inversePresentationMatrix)
+            val localEvent = MotionEvent.obtain(event)
+            try {
+                localEvent.transform(inversePresentationMatrix)
+                clipContainer.dispatchTouchEvent(localEvent)
+            } finally {
+                localEvent.recycle()
+            }
+        } else {
+            super.dispatchTouchEvent(event)
+        }
         if ((action == MotionEvent.ACTION_DOWN && !result) ||
             action == MotionEvent.ACTION_CANCEL || action == MotionEvent.ACTION_UP
         ) {
@@ -627,6 +710,7 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
 
     private fun clearTouchState() {
         acceptingTouchStream = false
+        forwardingOverflowTouchStream = false
     }
 
     fun setRequestedImportantForAccessibility(value: Int) {
@@ -644,14 +728,14 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
     fun reapplyClipPresentation() {
         val apertureVisible = apertureIntersectsHost()
         val expectedVisibility = renderVisibility(
-            apertureVisible || shadowIntersectsHost(),
+            requestedOpacity > 0f && (apertureVisible || shadowIntersectsHost()),
         )
         if (visibility != expectedVisibility) {
             visibility = expectedVisibility
         }
 
         val expectedAccessibility = clipAccessibility(
-            autonomousMotion || !apertureVisible,
+            autonomousMotion || !apertureVisible || requestedOpacity <= 0f,
             requestedImportantForAccessibility,
         )
         if (importantForAccessibility != expectedAccessibility) {
@@ -660,8 +744,11 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
     }
 
     private fun apertureIntersectsHost(): Boolean =
-        !clipIsEmpty && clipRight > 0f && clipBottom > 0f &&
-            clipLeft < width.toFloat() && clipTop < height.toFloat()
+        !clipIsEmpty && rotatedRectIntersectsHost(
+            clipLeft.toDouble(), clipTop.toDouble(), clipRight.toDouble(), clipBottom.toDouble(),
+            (clipLeft + clipRight) / 2.0, (clipTop + clipBottom) / 2.0,
+            requestedRotation, width.toDouble(), height.toDouble(),
+        )
 
     private fun shadowIntersectsHost(): Boolean {
         if (clipIsEmpty || !requestedShadowEnabled || requestedShadowAlpha <= 0f) {
@@ -677,9 +764,12 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         // CSS blur is specified as a diameter-like radius. Expanding by the
         // full value is conservative and prevents culling a faint blur tail.
         val blurOutset = requestedShadowBlurRadius
-        return pathRight + blurOutset > 0f && pathBottom + blurOutset > 0f &&
-            pathLeft - blurOutset < width.toFloat() &&
-            pathTop - blurOutset < height.toFloat()
+        return rotatedRectIntersectsHost(
+            (pathLeft - blurOutset).toDouble(), (pathTop - blurOutset).toDouble(),
+            (pathRight + blurOutset).toDouble(), (pathBottom + blurOutset).toDouble(),
+            (clipLeft + clipRight) / 2.0, (clipTop + clipBottom) / 2.0,
+            requestedRotation, width.toDouble(), height.toDouble(),
+        )
     }
 
     fun resetClipState() {
@@ -697,6 +787,8 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         requestedContentTranslateX = 0f
         requestedContentTranslateY = 0f
         requestedContentScale = 1f
+        requestedRotation = 0.0
+        requestedOpacity = 1f
         requestedShadowEnabled = false
         requestedShadowRed = 0f
         requestedShadowGreen = 0f

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

@@ -37,6 +37,8 @@ class SmoothClipViewManager : ViewGroupManager<SmoothClipView>(),
         var shadowOffsetY: Double = 0.0,
         var shadowBlurRadius: Double = 0.0,
         var shadowSpreadDistance: Double = 0.0,
+        var rotation: Double = 0.0,
+        var opacity: Double = 1.0,
         var driverId: Double = 0.0,
         // Whether any prop setter ran in the current update transaction.
         var dirty: Boolean = false,
@@ -173,6 +175,12 @@ class SmoothClipViewManager : ViewGroupManager<SmoothClipView>(),
     @ReactProp(name = "initialClipBoxShadowSpreadDistance")
     override fun setInitialClipBoxShadowSpreadDistance(view: SmoothClipView, value: Double) { pending(view).shadowSpreadDistance = value }
 
+    @ReactProp(name = "initialRotation")
+    override fun setInitialRotation(view: SmoothClipView, value: Double) { pending(view).rotation = value }
+
+    @ReactProp(name = "initialOpacity", defaultDouble = 1.0)
+    override fun setInitialOpacity(view: SmoothClipView, value: Double) { pending(view).opacity = value }
+
     override fun setClipPresentation(
         view: SmoothClipView,
         x: Double,
@@ -196,6 +204,8 @@ class SmoothClipViewManager : ViewGroupManager<SmoothClipView>(),
         shadowOffsetY: Double,
         shadowBlurRadius: Double,
         shadowSpreadDistance: Double,
+        rotation: Double,
+        opacity: Double,
     ) {
         view.commandIsAuthoritative = true
         view.setClipPresentationDip(
@@ -220,6 +230,8 @@ class SmoothClipViewManager : ViewGroupManager<SmoothClipView>(),
             shadowOffsetY,
             shadowBlurRadius,
             shadowSpreadDistance,
+            rotation,
+            opacity,
         )
     }
 
@@ -262,6 +274,8 @@ class SmoothClipViewManager : ViewGroupManager<SmoothClipView>(),
                     initial.shadowOffsetY,
                     initial.shadowBlurRadius,
                     initial.shadowSpreadDistance,
+                    initial.rotation,
+                    initial.opacity,
                     view.densityScale(),
                     view.width.toDouble(),
                     view.height.toDouble(),
@@ -292,6 +306,8 @@ class SmoothClipViewManager : ViewGroupManager<SmoothClipView>(),
                     initial.shadowOffsetY,
                     initial.shadowBlurRadius,
                     initial.shadowSpreadDistance,
+                    initial.rotation,
+                    initial.opacity,
                 )
         } else {
             view.reapplyClipPresentation()

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(
@@ -130,10 +138,10 @@ inline double cubicBezier(
 
 // --- Presentation channels ------------------------------------------------
 
-// The first eleven channels are geometry/content; the final eight are shadow.
+// The first thirteen channels are geometry/content/appearance; the final eight are shadow.
 // Curve and shadow presence are categorical and stay outside the scalar array.
-constexpr std::size_t kBaseChannelCount = 11;
-constexpr std::size_t kChannelCount = 19;
+constexpr std::size_t kBaseChannelCount = 13;
+constexpr std::size_t kChannelCount = 21;
 using Channels = std::array<double, kChannelCount>;
 
 inline double resolvedRadius(double overrideValue, double shorthand) {
@@ -169,6 +177,8 @@ inline Channels toChannels(const Presentation &presentation) {
           presentation.contentTranslateX,
           presentation.contentTranslateY,
           presentation.contentScale,
+          presentation.rotation,
+          presentation.opacity,
           presentation.shadow.red,
           presentation.shadow.green,
           presentation.shadow.blue,
@@ -211,6 +221,7 @@ inline bool canonicalizePresentation(Presentation &presentation) {
   CanonicalClip clip;
   if (!SmoothClipCanonicalize(presentation.clip, clip)) return false;
   presentation.clip = SmoothClipGeometry(clip);
+  presentation.opacity = clamp01(presentation.opacity);
   return true;
 }
 
@@ -436,16 +447,16 @@ inline Presentation fromChannels(
   geometry.curve = curve;
   Shadow shadow{
       shadowEnabled,
-      std::clamp(channels[11], 0.0, 1.0),
-      std::clamp(channels[12], 0.0, 1.0),
       std::clamp(channels[13], 0.0, 1.0),
       std::clamp(channels[14], 0.0, 1.0),
-      channels[15],
-      channels[16],
-      std::max(0.0, channels[17]),
-      channels[18]};
+      std::clamp(channels[15], 0.0, 1.0),
+      std::clamp(channels[16], 0.0, 1.0),
+      channels[17],
+      channels[18],
+      std::max(0.0, channels[19]),
+      channels[20]};
   return Presentation{
-      geometry, channels[8], channels[9], channels[10], shadow};
+      geometry, channels[8], channels[9], channels[10], shadow, channels[11], clamp01(channels[12])};
 }
 
 inline Presentation interpolate(

package/cpp/SmoothClipRegistry.h

@@ -44,6 +44,8 @@ struct Presentation {
   double contentTranslateY;
   double contentScale = 1.0;
   Shadow shadow{};
+  double rotation = 0; // Unwrapped radians, clockwise in host coordinates.
+  double opacity = 1;
 };
 
 struct TimingAnimation {

package/cpp/SmoothClipSharedGeometry.h

@@ -156,4 +156,24 @@ inline Geometry SmoothClipGeometry(const CanonicalClip &clip) {
   return geometry;
 }
 
+// Exact rectangle/host SAT; conservative for rounded corners, as before rotation.
+inline bool rotatedRectIntersectsHost(double x, double y, double width, double height,
+                                     double rotation, double hostWidth, double hostHeight) {
+  if (width <= 0 || height <= 0 || hostWidth <= 0 || hostHeight <= 0) return false;
+  if (rotation == 0) return x + width > 0 && y + height > 0 && x < hostWidth && y < hostHeight;
+  const double c = std::cos(rotation), s = std::sin(rotation);
+  const double ac = std::abs(c), as = std::abs(s);
+  const double dx = x + width / 2 - hostWidth / 2;
+  const double dy = y + height / 2 - hostHeight / 2;
+  return std::abs(dx) < hostWidth / 2 + ac * width / 2 + as * height / 2 &&
+      std::abs(dy) < hostHeight / 2 + as * width / 2 + ac * height / 2 &&
+      std::abs(c * dx + s * dy) < width / 2 + ac * hostWidth / 2 + as * hostHeight / 2 &&
+      std::abs(-s * dx + c * dy) < height / 2 + as * hostWidth / 2 + ac * hostHeight / 2;
+}
+
+inline double unwrapRotation(double principal, double reference) {
+  constexpr double turn = 6.28318530717958647692;
+  return principal + std::round((reference - principal) / turn) * turn;
+}
+
 } // namespace smoothclip

package/cpp/SmoothClipVelocityTracker.h

@@ -11,6 +11,12 @@ namespace smoothclip {
 // the four radius channels contributes one quarter of the uniform-radius weight.
 // Both platforms record raw canonical geometry, including off-host coordinates.
 // The projection only needs both samples and the target in the same space.
+// Rotation, opacity, and shadow channels are deliberately absent: their units
+// must not enter this geometry/translation projection. Appearance-only motion
+// cannot supply inherited velocity. The resulting normalized scalar can still
+// seed every changing animation channel, including rotation and opacity.
+// This inheritance path is internal to standalone native animations; public
+// controllers/groups use an explicit progress velocity, defaulting to zero.
 // Shared by ios/SmoothClipView.mm and android/.../SmoothClipRegistry.cpp; a
 // behavior change here changes both platforms.
 struct VelocitySampleHistory {