react-native-smooth-clip-view 0.2.2 → 0.2.5

package/README.md

@@ -2,14 +2,13 @@
 
 [![npm version](https://img.shields.io/npm/v/react-native-smooth-clip-view.svg)](https://www.npmjs.com/package/react-native-smooth-clip-view)
 
-Layout-free animated rounded clipping for React Native Fabric.
+## High-performance geometry animations for React Native
 
-`SmoothClipView` keeps a fixed maximum Yoga footprint while a reusable driver
-updates only the native clipping layer. It is
-useful for expanding cards, sheets, maps, media, zoom transitions, and other reveals where
-animating layout width and height cause lag because of yoga/fabric calculating layout every frame.
+`react-native-smooth-clip-view` lets you animate `x`, `y`, `width`, `height`, and `borderRadius` with Reanimated without triggering expensive layout work on every frame.
 
-In other words, it makes animating width height on Reanimated a cheap operation.
+Instead of resizing the Yoga layout, `SmoothClipView` keeps a fixed footprint and updates only the native clipping layer. This makes geometry-heavy animations smooth and inexpensive—even for shared-element transitions, zoom transitions, expanding cards, reveals, sheets, maps, and media.
+
+Use it for transitions that previously struggled with performance when animating layout dimensions directly.
 
 ## Requirements
 
@@ -141,10 +140,16 @@ const gesture = Gesture.Pan()
     // bookkeeping. Assigning driver.presentation.value also works.
     driver.ui.setScalars(clip.x, clip.y, clip.width, clip.height, clip.radius, 0, 0);
   })
-  .onEnd(() => {
+  .onEnd((event) => {
+    // The release event is fresher than the last onUpdate (on Android,
+    // ACTION_UP carries a position no MOVE ever delivered). Pass the final
+    // geometry as `from` so the animation starts from exactly that value —
+    // it fuses a setScalars hot write with the handoff in one call.
+    const clip = geometryForDrag(dragStart.value, event.translationY);
     driver.ui.animateTo(createClipPresentation(expandedClip), {
       type: 'spring',
       initialVelocity: 'inherit',
+      from: createClipPresentation(clip),
     });
   });
 ```
@@ -175,32 +180,65 @@ const gesture = Gesture.Pan()
   streams such as gestures. `driver.presentation.value` is stale after hot
   writes by design; `beginInteraction()` remains the source of truth for
   visible geometry, and `animateTo()` after hot writes starts from the native
-  registry's latest value rather than the stale SharedValue. Do not interleave
-  `setScalars` with `presentation.value` writes on the same driver.
+  registry's latest value rather than the stale SharedValue. To start from a
+  value fresher than the last hot write (a gesture's release sample), pass it
+  as `animation.from` — `animateTo` then performs the hot write and the
+  handoff in one call. Do not interleave `setScalars` with
+  `presentation.value` writes on the same driver.
 - Spring `initialVelocity` is one normalized scalar along the current-to-target
   trajectory, in units of the remaining distance per second (`1` covers the
   remaining distance in one second). Every geometry channel continues with the
   same normalized rate, so grab/release preserves the felt direction and
   speed. `'inherit'` (the default) estimates the scalar from the last two
   interactive samples on iOS and Android; samples older than 100 ms — and the
-  web fallback — fall back to zero.
+  web fallback — fall back to zero. Two writes landing inside the same frame
+  (< 4 ms apart, e.g. a release-sample `from` seed right after the last drag
+  write) coalesce into one sample, and an identical re-write is ignored, so a
+  fused handoff can neither zero nor inflate the inherited velocity.
+  `beginInteraction()` records the frozen presentation as a plain sample on
+  both platforms, so a grab-and-instant-refling inherits bounded recent
+  motion (the staleness guard still zeroes a stale pair) instead of
+  launching dead.
 - `driver.react` exposes `beginInteraction`, `set`, `animateTo`, and `cancel`
   as Promises (`setScalars` is UI-worklet-only). React code never blocks
   waiting for main/UI-thread work. An immediate animation request resolves
   before its completion callback is delivered.
 - `animateTo()` transfers ownership to native animation. Timing uses
-  cubic Bézier control points; springs accept mass, stiffness, damping, and an
+  cubic Bézier control points — `ClipEasings` exports exact-form presets
+  (`easeOutCubic` = `Easing.out(Easing.cubic)` etc.) so a parallel Reanimated
+  animation can run the identical curve without hand-deriving it; springs
+  accept mass, stiffness, damping, and an
   explicit normalized velocity or `'inherit'` (the default). Keyframes accept
-  validated, monotonically increasing offsets from zero through one.
+  validated, monotonically increasing offsets from zero through one; there is
+  deliberately no keyframe easing field — playback is linear between offsets
+  and the frames encode the curve, which also expresses per-channel-nonlinear
+  paths that no single time-warp could reproduce. Every
+  kind accepts an optional `from` presentation — a fused take-ownership hot
+  write issued immediately before the handoff, so the animation starts from
+  exactly that value (pass `frames[0].presentation` for keyframes, which
+  interpolate absolutely). A non-finite `from` rejects the whole call; against
+  a held pending-animation latch the seed is dropped — the latch is newer
+  intent, and nothing is displayable yet anyway. `from` behaves the same on
+  both platforms (it is driver-layer, not native): on iOS the seed stops any
+  running Core Animation and writes the model layer first; keyframes then
+  start exactly at `from`, while timing/spring sample their from-value off
+  the presentation layer — the last committed frame, at most one frame
+  behind `from` — identical to the explicit two-call pattern.
 - `cancel()` freezes visible presentation by default. Pass `'target'` as its
   behavior to jump to the requested endpoint.
 - `options.onAnimationComplete` fires exactly once per animation with its ID
   and `finished` state, including cancellation, replacement, and native-side
-  rejection (`animateTo` then returns `0` and one `finished: false` completion
-  is delivered). Unmounting the last host mid-flight does not complete the
+  rejection (`animateTo` then returns a fresh non-zero id whose single
+  `finished: false` completion follows — key completion handling by the
+  returned id, never by `0`). `animateTo` returns `0` — and delivers no
+  completion — only when the driver entry no longer exists (destroyed) or the
+  call ran off the main thread. Unmounting the last host mid-flight does not complete the
   animation: the remainder is re-latched and the next displayable host resumes
   it, so the completion arrives when it finishes there — or unfinished on
   replacement, cancellation, `beginInteraction()`, or driver destruction.
+  With multiple hosts on one driver, unregistering any participant mid-flight
+  makes the eventual completion `finished: false` — `finished: true` means
+  every participant ran the animation to its end.
 - An `animateTo` issued before any host view can produce a visible frame (for
   example from an effect in the same commit that mounts the host, or inside a
   modal route whose subtree attaches to its window late) is held pending and

package/android/CMakeLists.txt

@@ -16,6 +16,10 @@ file(GLOB smoothclip_SOURCES CONFIGURE_DEPENDS
 
 add_library(smoothclipview SHARED ${smoothclip_SOURCES})
 
+# 16 KB page-size support for NDKs where ANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES
+# is unavailable (< r26.3) or ignored.
+target_link_options(smoothclipview PRIVATE "-Wl,-z,max-page-size=16384")
+
 # C++20, RTTI, exceptions and React Native macros.
 include("${REACT_NATIVE_DIR}/ReactCommon/cmake-utils/react-native-flags.cmake")
 target_compile_reactnative_options(smoothclipview PUBLIC)

package/android/build.gradle

@@ -86,6 +86,7 @@ android {
       cmake {
         cppFlags "-O2", "-frtti", "-fexceptions", "-Wall", "-std=c++20"
         arguments "-DANDROID_STL=c++_shared",
+                  "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON",
                   "-DREACT_NATIVE_DIR=${reactNativeRootDir}"
         abiFilters(*reactNativeArchitectures())
       }

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

@@ -1,4 +1,5 @@
 #include "SmoothClipAndroid.h"
+#include "SmoothClipVelocityTracker.h"
 
 #include <android/choreographer.h>
 #include <fbjni/fbjni.h>
@@ -42,6 +43,11 @@ struct ActiveAnimation {
   std::vector<Keyframe> keyframes;
   double durationS = 0;
   double startedAtS = 0;
+  // Wall-clock twin of startedAtS: stamped together with it, NEVER rebased
+  // by the frame-clock anchor. Readers that need honest wall elapsed (the
+  // unregister re-latch remainder, the run-ahead guard) use this; the
+  // animation curve itself paces on the anchored startedAtS frame axis.
+  double wallStartedAtS = 0;
   // Integrated spring state (channels: x, y, width, height, radius, tx, ty).
   std::array<double, 7> springPosition{};
   std::array<double, 7> springVelocity{};
@@ -51,6 +57,10 @@ struct ActiveAnimation {
   // registered, held un-rendered (and out of animatingDrivers()) until the
   // first registerViewAndroid rebases the clock and starts it.
   bool started = false;
+  // False until the first advance() translates the wall-clock start stamp
+  // onto the choreographer frame-time axis (elapsed-preserving). Every
+  // startedAtS stamp clears it so a re-latched resume re-anchors too.
+  bool frameClockAnchored = false;
 };
 
 // Per-view fanout state. Density and host metrics are pushed from Kotlin at
@@ -75,12 +85,9 @@ struct DriverState {
   // last view leaves and revived by a take-ownership setPresentation.
   bool destroyed = false;
 
-  bool hasPreviousSample = false;
-  bool hasLatestSample = false;
-  Presentation previousSample{{0, 0, 0, 0, 0}, 0, 0};
-  Presentation latestSample{{0, 0, 0, 0, 0}, 0, 0};
-  double previousSampleTimeS = 0;
-  double latestSampleTimeS = 0;
+  // 'inherit' velocity samples; recording/coalescing/projection live in the
+  // shared cpp/SmoothClipVelocityTracker.h (behavior-paired with iOS).
+  VelocitySampleHistory samples;
 };
 
 struct CompletionSink {
@@ -221,6 +228,13 @@ constexpr double kSpringSettleVelocity = 1.0;
 // Settle-based termination is backed by a hard cap so a pathological
 // configuration cannot run the frame loop forever.
 constexpr double kSpringMaxDurationS = 10.0;
+// Fixed slack for the post-stall run-ahead guard in advance(). The lead it
+// bounds is a latency DIFFERENTIAL — the anchor frame's dispatch latency
+// minus the current frame's — so the constant is refresh-rate independent
+// (it is not one vsync period; at 120 Hz it spans two). 17 ms keeps the
+// guard silent through normal callback jitter while capping post-stall
+// run-ahead at one 60 Hz frame of curve time.
+constexpr double kMaxFrameLeadS = 0.017;
 
 // Semi-implicit Euler per channel, substepped: one frame-sized step is only
 // stable for omega*dt < 2, and accepted stiffness/mass ratios exceed that at
@@ -367,46 +381,6 @@ void applyToViews(DriverState &state, const Presentation &presentation) {
   }
 }
 
-void recordInteractiveSample(DriverState &state, const Presentation &presentation) {
-  state.hasPreviousSample = state.hasLatestSample;
-  state.previousSample = state.latestSample;
-  state.previousSampleTimeS = state.latestSampleTimeS;
-  state.hasLatestSample = true;
-  state.latestSample = presentation;
-  state.latestSampleTimeS = nowSeconds();
-}
-
-double inheritedVelocity(DriverState &state, const Presentation &target) {
-  if (!state.hasPreviousSample || !state.hasLatestSample) return 0;
-  const double elapsed = state.latestSampleTimeS - state.previousSampleTimeS;
-  if (elapsed <= 0 || nowSeconds() - state.latestSampleTimeS > 0.1) return 0;
-  const double sample[7] = {
-      state.latestSample.clip.x - state.previousSample.clip.x,
-      state.latestSample.clip.y - state.previousSample.clip.y,
-      state.latestSample.clip.width - state.previousSample.clip.width,
-      state.latestSample.clip.height - state.previousSample.clip.height,
-      state.latestSample.clip.radius - state.previousSample.clip.radius,
-      state.latestSample.contentTranslateX - state.previousSample.contentTranslateX,
-      state.latestSample.contentTranslateY - state.previousSample.contentTranslateY};
-  const double destination[7] = {
-      target.clip.x - state.latestSample.clip.x,
-      target.clip.y - state.latestSample.clip.y,
-      target.clip.width - state.latestSample.clip.width,
-      target.clip.height - state.latestSample.clip.height,
-      target.clip.radius - state.latestSample.clip.radius,
-      target.contentTranslateX - state.latestSample.contentTranslateX,
-      target.contentTranslateY - state.latestSample.contentTranslateY};
-  double numerator = 0;
-  double denominator = 0;
-  for (int index = 0; index < 7; index += 1) {
-    numerator += sample[index] * destination[index];
-    denominator += destination[index] * destination[index];
-  }
-  if (denominator <= 1e-12) return 0;
-  const double result = numerator / elapsed / denominator;
-  return std::isfinite(result) ? result : 0;
-}
-
 void applyPresentation(DriverState &state, const Presentation &presentation) {
   state.latest = presentation;
   state.hasLatest = true;
@@ -480,6 +454,11 @@ void startLatchedAnimation(uint64_t driverId, DriverState &state) {
   animation.started = true;
   animation.startedAtS = nowSeconds();
   animation.lastFrameS = animation.startedAtS;
+  animation.wallStartedAtS = animation.startedAtS;
+  // Load-bearing for re-latch resumes: unregisterViewAndroid rewrites this
+  // ActiveAnimation in place, so a stale anchor would replay the fraction-0
+  // first frame the anchor exists to remove.
+  animation.frameClockAnchored = false;
   auto &active = animatingDrivers();
   if (std::find(active.begin(), active.end(), driverId) == active.end()) {
     active.push_back(driverId);
@@ -494,6 +473,8 @@ int32_t startAnimation(
     ActiveAnimation animation) {
   animation.startedAtS = nowSeconds();
   animation.lastFrameS = animation.startedAtS;
+  animation.wallStartedAtS = animation.startedAtS;
+  animation.frameClockAnchored = false;
   // current = start even while latched is load-bearing: cancelAnimation,
   // beginInteraction, prepareAnimation's visibleBefore and registerView's
   // visible all read animation->current, giving a never-rendered latch
@@ -521,6 +502,38 @@ int32_t startAnimation(
 void advance(uint64_t driverId, DriverState &state, double now) {
   ActiveAnimation &animation = *state.animation;
 
+  if (!animation.frameClockAnchored) {
+    // startedAtS/lastFrameS hold nowSeconds() sampled mid-frame at the
+    // animateTo call / latch attach, but `now` is the frame's vsync
+    // timestamp — the same CLOCK_MONOTONIC timebase at an earlier sampling
+    // point. Un-anchored, the first fraction clamps to 0 and re-renders the
+    // start (1-2 duplicated frames at every interactive→animateTo handoff).
+    // Re-anchor onto the frame-time axis keeping the real elapsed time, so
+    // the first rendered frame advances honestly and later frames pace on
+    // vsync. On the 32-bit path `now` is itself nowSeconds() → ~identity.
+    const double wallElapsedS =
+        std::max(0.0, nowSeconds() - animation.startedAtS);
+    animation.startedAtS = now - wallElapsedS;
+    animation.lastFrameS = animation.startedAtS;
+    animation.frameClockAnchored = true;
+    // wallStartedAtS deliberately keeps the wall axis through this rebase.
+  }
+
+  // Run-ahead guard: the anchor's one-time shift bakes the first callback's
+  // dispatch latency into the frame axis. If a stalled handoff anchored
+  // against a stale frame stamp and later stamps catch up to real time, the
+  // frame axis leads wall time by up to the stall length and the animation
+  // completes early. Re-anchor forward when the lead exceeds one vsync of
+  // slack; on calm frames the condition (first callback's latency exceeding
+  // this frame's by > 17 ms) cannot hold, so the hot path is unchanged, and
+  // the 32-bit path (frame axis == wall axis) never fires it. lastFrameS is
+  // deliberately untouched: springs pace on dt, already clamped to 64 ms.
+  const double wallElapsedNowS =
+      std::max(0.0, nowSeconds() - animation.wallStartedAtS);
+  if (now - animation.startedAtS > wallElapsedNowS + kMaxFrameLeadS) {
+    animation.startedAtS = now - wallElapsedNowS;
+  }
+
   bool done = false;
   if (animation.kind == AnimationKind::Spring) {
     done = advanceSpring(animation, now);
@@ -648,7 +661,7 @@ void setPresentation(
   state.latest = presentation;
   state.hasLatest = true;
   state.ownership = Ownership::Interactive;
-  recordInteractiveSample(state, presentation);
+  recordVelocitySample(state.samples, toChannels(presentation), nowSeconds());
   applyToViews(state, presentation);
 }
 
@@ -668,10 +681,12 @@ Presentation beginInteraction(uint64_t driverId) {
   state.latest = current;
   state.hasLatest = true;
   state.ownership = Ownership::Interactive;
-  state.hasPreviousSample = false;
-  state.hasLatestSample = true;
-  state.latestSample = current;
-  state.latestSampleTimeS = nowSeconds();
+  // Plain record, not a reset — iOS parity (smoothClipFreezePresentation
+  // records the frozen value). Pairing the frozen mid-flight presentation
+  // with the last real sample lets a grab-and-instant-refling inherit
+  // bounded recent motion instead of launching dead; an unchanged value
+  // dedupes to a no-op and ages out through the staleness guard.
+  recordVelocitySample(state.samples, toChannels(current), nowSeconds());
   applyToViews(state, current);
   emitCompletion(driverId, animationId, false);
   return current;
@@ -720,7 +735,7 @@ int32_t animateSpring(
   // seeded with velocity·displacement to match the iOS CASpringAnimation
   // per-keypath behavior.
   const double velocity = animation.inheritVelocity
-      ? inheritedVelocity(state, presentation)
+      ? inheritedVelocity(state.samples, toChannels(presentation), nowSeconds())
       : animation.initialVelocity;
   const Presentation resolvedStart =
       prepareAnimation(driverId, state, start, presentation);
@@ -1001,7 +1016,11 @@ void unregisterViewAndroid(
       // it). Completing it here would betray the pending intent.
     } else if (state.views.empty()) {
       auto &animation = *state.animation;
-      const double elapsedS = nowSeconds() - animation.startedAtS;
+      // wallStartedAtS, not startedAtS: post-anchor the latter lives on the
+      // shifted frame axis and would overstate elapsed by the first
+      // callback's dispatch latency, shortening the resumed remainder and
+      // advancing the keyframe rebase past the rendered position.
+      const double elapsedS = nowSeconds() - animation.wallStartedAtS;
       const double remainingS = std::max(0.0, animation.durationS - elapsedS);
       const bool canResume = !state.destroyed &&
           (animation.kind == AnimationKind::Spring || remainingS > 0);

package/cpp/SmoothClipVelocityTracker.h

@@ -0,0 +1,101 @@
+#pragma once
+
+#include <array>
+#include <cmath>
+
+namespace smoothclip {
+
+// The two most recent interactive samples used by `initialVelocity: 'inherit'`.
+// Channels are the seven presentation scalars (x, y, width, height, radius,
+// contentTranslateX, contentTranslateY) but the tracker is value-agnostic:
+// iOS records normalized (host-clamped) geometry, Android raw DIP — the
+// projection only needs both samples and the target in the same space.
+// Shared by ios/SmoothClipView.mm and android/.../SmoothClipRegistry.cpp; a
+// behavior change here changes both platforms.
+struct VelocitySampleHistory {
+  bool hasPrevious = false;
+  bool hasLatest = false;
+  std::array<double, 7> previous{};
+  std::array<double, 7> latest{};
+  double previousTimeS = 0;
+  double latestTimeS = 0;
+};
+
+// Two records closer than this are one observation of the same frame (an
+// ACTION_UP adoption or an animateTo `from` seed lands in the same input
+// batch as the last drag write, ~1 ms apart). The window sits well above
+// batch spacing and below the 8.33 ms 120 Hz frame, so legitimate
+// consecutive-frame samples never coalesce.
+inline constexpr double kSampleCoalesceWindowS = 0.004;
+// A latest sample older than this no longer describes the finger; 'inherit'
+// yields zero instead of replaying stale motion.
+inline constexpr double kVelocityStalenessS = 0.1;
+
+inline void recordVelocitySample(
+    VelocitySampleHistory &history,
+    const std::array<double, 7> &channels,
+    double nowS) {
+  if (history.hasLatest && channels == history.latest) {
+    // Identical re-record (a `from` seed equal to the last interactive
+    // write): keep the pair and its timestamps, so the last real motion
+    // still ages out through the staleness guard instead of zeroing the
+    // sample deltas.
+    return;
+  }
+  if (history.hasLatest &&
+      nowS - history.latestTimeS < kSampleCoalesceWindowS) {
+    // Same-frame re-record: replace the latest sample in place instead of
+    // rotating, so the surviving pair spans a real frame interval. Rotating
+    // here would divide the extra sub-frame displacement by microseconds and
+    // explode the inherited velocity.
+    history.latest = channels;
+    history.latestTimeS = nowS;
+    return;
+  }
+  history.hasPrevious = history.hasLatest;
+  history.previous = history.latest;
+  history.previousTimeS = history.latestTimeS;
+  history.hasLatest = true;
+  history.latest = channels;
+  history.latestTimeS = nowS;
+}
+
+// beginInteraction on both platforms records the frozen presentation as a
+// plain sample: a grab mid-animation pairs the frozen value with the last
+// real sample, so an instant refling inherits bounded recent motion instead
+// of launching dead, and a grab at an unchanged value dedupes to a no-op
+// whose staleness keeps aging. There is deliberately no reset primitive —
+// the 100 ms staleness guard is the forgetting mechanism.
+
+inline void clearVelocitySamples(VelocitySampleHistory &history) {
+  history = VelocitySampleHistory{};
+}
+
+// Normalized velocity of the recorded motion projected onto the
+// latest→target trajectory, in units of remaining-distance per second
+// (1 covers the remaining distance in one second) — the CASpringAnimation
+// initialVelocity convention. iOS passes the scalar unchanged per keypath;
+// Android seeds each integrator channel with scalar·displacement.
+inline double inheritedVelocity(
+    const VelocitySampleHistory &history,
+    const std::array<double, 7> &target,
+    double nowS) {
+  if (!history.hasPrevious || !history.hasLatest) return 0;
+  const double elapsed = history.latestTimeS - history.previousTimeS;
+  if (elapsed <= 0 || nowS - history.latestTimeS > kVelocityStalenessS) {
+    return 0;
+  }
+  double numerator = 0;
+  double denominator = 0;
+  for (int index = 0; index < 7; index += 1) {
+    const double sampleDelta = history.latest[index] - history.previous[index];
+    const double destinationDelta = target[index] - history.latest[index];
+    numerator += sampleDelta * destinationDelta;
+    denominator += destinationDelta * destinationDelta;
+  }
+  if (denominator <= 1e-12) return 0;
+  const double result = numerator / elapsed / denominator;
+  return std::isfinite(result) ? result : 0;
+}
+
+} // namespace smoothclip

package/ios/SmoothClipView.mm

@@ -3,6 +3,8 @@
 #import "SmoothClipGeometry.h"
 #import "SmoothClipViewRegistry.h"
 
+#include "SmoothClipVelocityTracker.h"
+
 #import <QuartzCore/QuartzCore.h>
 #import <React/RCTConversions.h>
 #import <React/RCTFabricComponentsPlugins.h>
@@ -48,6 +50,17 @@ using namespace facebook::react;
                                        finished:(BOOL)finished;
 @end
 
+static std::array<double, 7> SmoothClipVelocityChannels(
+    CGRect rect, CGFloat radius, CGPoint contentTranslation) {
+  return {CGRectGetMinX(rect),
+          CGRectGetMinY(rect),
+          CGRectGetWidth(rect),
+          CGRectGetHeight(rect),
+          radius,
+          contentTranslation.x,
+          contentTranslation.y};
+}
+
 @implementation SmoothClipView {
   SmoothClipContainerView *_clipContainer;
   SmoothClipContainerView *_contentContainer;
@@ -82,16 +95,10 @@ using namespace facebook::react;
   CGPoint _pausedContentTranslation;
   CFTimeInterval _pausedRemaining;
 
-  BOOL _hasPreviousInteractiveSample;
-  BOOL _hasInteractiveSample;
-  CGRect _previousInteractiveRect;
-  CGRect _interactiveRect;
-  CGFloat _previousInteractiveRadius;
-  CGFloat _interactiveRadius;
-  CGPoint _previousInteractiveContentTranslation;
-  CGPoint _interactiveContentTranslation;
-  CFTimeInterval _previousInteractiveTime;
-  CFTimeInterval _interactiveTime;
+  // 'inherit' velocity samples (normalized geometry, per view); recording/
+  // coalescing/projection live in the shared cpp/SmoothClipVelocityTracker.h
+  // (behavior-paired with Android's per-driver history).
+  smoothclip::VelocitySampleHistory _velocitySamples;
 }
 
 + (ComponentDescriptorProvider)componentDescriptorProvider {
@@ -144,8 +151,7 @@ using namespace facebook::react;
     _activeAnimationKind = 0;
     _pendingAnimationInstall = NO;
     _animationPaused = NO;
-    _hasPreviousInteractiveSample = NO;
-    _hasInteractiveSample = NO;
+    smoothclip::clearVelocitySamples(_velocitySamples);
     [[NSNotificationCenter defaultCenter]
         addObserver:self
            selector:@selector(applicationWillResignActive)
@@ -305,71 +311,24 @@ using namespace facebook::react;
 - (void)recordInteractiveRect:(CGRect)rect
                        radius:(CGFloat)radius
            contentTranslation:(CGPoint)contentTranslation {
-  if (_hasInteractiveSample &&
-      CGRectEqualToRect(_interactiveRect, rect) &&
-      _interactiveRadius == radius &&
-      CGPointEqualToPoint(
-          _interactiveContentTranslation, contentTranslation)) {
-    return;
-  }
-  if (_hasInteractiveSample) {
-    _hasPreviousInteractiveSample = YES;
-    _previousInteractiveRect = _interactiveRect;
-    _previousInteractiveRadius = _interactiveRadius;
-    _previousInteractiveContentTranslation =
-        _interactiveContentTranslation;
-    _previousInteractiveTime = _interactiveTime;
-  }
-  _hasInteractiveSample = YES;
-  _interactiveRect = rect;
-  _interactiveRadius = radius;
-  _interactiveContentTranslation = contentTranslation;
-  _interactiveTime = CACurrentMediaTime();
+  // Identical-value dedupe and same-frame coalescing live in the shared
+  // tracker; coalescing keeps a distinct re-record issued sub-frame after
+  // the last one (e.g. a fused animateTo `from` seed at gesture release)
+  // from exploding the inherited velocity.
+  smoothclip::recordVelocitySample(
+      _velocitySamples,
+      SmoothClipVelocityChannels(rect, radius, contentTranslation),
+      CACurrentMediaTime());
 }
 
 - (CGFloat)inheritedVelocityToRect:(CGRect)target
                             radius:(CGFloat)targetRadius
                 contentTranslation:(CGPoint)targetContentTranslation {
-  if (!_hasPreviousInteractiveSample || !_hasInteractiveSample) return 0;
-  const CFTimeInterval elapsed =
-      _interactiveTime - _previousInteractiveTime;
-  if (elapsed <= 0 || CACurrentMediaTime() - _interactiveTime > 0.1) return 0;
-
-  const CGFloat current[] = {
-      CGRectGetMinX(_interactiveRect),
-      CGRectGetMinY(_interactiveRect),
-      CGRectGetWidth(_interactiveRect),
-      CGRectGetHeight(_interactiveRect),
-      _interactiveRadius,
-      _interactiveContentTranslation.x,
-      _interactiveContentTranslation.y};
-  const CGFloat previous[] = {
-      CGRectGetMinX(_previousInteractiveRect),
-      CGRectGetMinY(_previousInteractiveRect),
-      CGRectGetWidth(_previousInteractiveRect),
-      CGRectGetHeight(_previousInteractiveRect),
-      _previousInteractiveRadius,
-      _previousInteractiveContentTranslation.x,
-      _previousInteractiveContentTranslation.y};
-  const CGFloat destination[] = {
-      CGRectGetMinX(target),
-      CGRectGetMinY(target),
-      CGRectGetWidth(target),
-      CGRectGetHeight(target),
-      targetRadius,
-      targetContentTranslation.x,
-      targetContentTranslation.y};
-  double numerator = 0;
-  double denominator = 0;
-  for (NSUInteger index = 0; index < 7; index += 1) {
-    const double velocity = (current[index] - previous[index]) / elapsed;
-    const double displacement = destination[index] - current[index];
-    numerator += velocity * displacement;
-    denominator += displacement * displacement;
-  }
-  if (denominator <= DBL_EPSILON) return 0;
-  const double result = numerator / denominator;
-  return isfinite(result) ? result : 0;
+  return smoothclip::inheritedVelocity(
+      _velocitySamples,
+      SmoothClipVelocityChannels(
+          target, targetRadius, targetContentTranslation),
+      CACurrentMediaTime());
 }
 
 - (void)smoothClipApplyPresentation:(smoothclip::Presentation)presentation {
@@ -1113,8 +1072,7 @@ using namespace facebook::react;
   [self stopLayerAnimationWithoutCallback];
   _pendingAnimationInstall = NO;
   _animationPaused = NO;
-  _hasPreviousInteractiveSample = NO;
-  _hasInteractiveSample = NO;
+  smoothclip::clearVelocitySamples(_velocitySamples);
   [super prepareForRecycle];
   _requestedClip = CGRectZero;
   _normalizedClip = CGRectZero;

package/lib/module/drivers.android.js

@@ -1,4 +1,6 @@
 "use strict";
 
-export { useSmoothClipDriver } from "./drivers.ios.js";
+// Platform re-export only — the implementation is shared with iOS.
+// Edit drivers.native.ts, not this file.
+export { useSmoothClipDriver } from "./drivers.native.js";
 //# sourceMappingURL=drivers.android.js.map

package/lib/module/drivers.android.js.map

@@ -1 +1 @@
-{"version":3,"names":["useSmoothClipDriver"],"sourceRoot":"../../src","sources":["drivers.android.ts"],"mappings":";;AAAA,SAASA,mBAAmB,QAAQ,kBAAe","ignoreList":[]}
+{"version":3,"names":["useSmoothClipDriver"],"sourceRoot":"../../src","sources":["drivers.android.ts"],"mappings":";;AAAA;AACA;AACA,SAASA,mBAAmB,QAAQ,qBAAkB","ignoreList":[]}