react-native-smooth-clip-view 0.2.1 → 0.2.4

package/cpp/SmoothClipVelocityTracker.h

@@ -0,0 +1,106 @@
+#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 semantics: history restarts from a single fresh sample;
+// one more record is needed before 'inherit' can measure motion.
+inline void resetVelocitySamples(
+    VelocitySampleHistory &history,
+    const std::array<double, 7> &channels,
+    double nowS) {
+  history.hasPrevious = false;
+  history.hasLatest = true;
+  history.latest = channels;
+  history.latestTimeS = nowS;
+}
+
+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/SmoothClipRegistry.mm

@@ -35,6 +35,8 @@
                         animationId:(int32_t)animationId;
 - (void)smoothClipCancelAnimationUsingTarget:(BOOL)useTarget;
 - (BOOL)smoothClipIsJoinable;
+- (BOOL)smoothClipCanDisplay;
+- (BOOL)smoothClipHasPendingInstall;
 @end
 
 namespace smoothclip {
@@ -182,8 +184,12 @@ Presentation canonicalFrozenPresentation(DriverState &state) {
       : state.latest;
   bool hasCanonical = false;
   for (const ViewKey key : state.views) {
-    const Presentation frozen = [viewForKey(key) smoothClipFreezePresentation];
-    if (!hasCanonical) {
+    // Freeze every view (the teardown side effect must reach all of them),
+    // but only a laid-out view may define the canonical geometry — an
+    // unlaid-out one reports {0,0,0,0} and would collapse the clip.
+    SmoothClipView *candidate = viewForKey(key);
+    const Presentation frozen = [candidate smoothClipFreezePresentation];
+    if (!hasCanonical && [candidate smoothClipIsJoinable]) {
       canonical = frozen;
       hasCanonical = true;
     }
@@ -286,6 +292,33 @@ void dispatchActiveAnimationJoin(
   }
 }
 
+// An animation may only start once a registered view can actually produce a
+// visible frame. A CA animation committed while its layer tree is detached
+// from the render tree (a transparentModal subtree before UIKit presents its
+// view controller) is removed at the attach commit with finished=NO, which
+// snaps the layer to its model values — the animation's target.
+bool anyDisplayableView(const DriverState &state) {
+  for (const ViewKey key : state.views) {
+    if ([viewForKey(key) smoothClipCanDisplay]) return true;
+  }
+  return false;
+}
+
+// Starts a latched animation: rebases the clock so no progress was burned
+// while no view could display, then dispatches the join to every registered
+// view. Views that still cannot display defer their install per-view and
+// resume via viewBecameDisplayable.
+void startLatchedAnimation(DriverState &state) {
+  state.animation->startedAt = CACurrentMediaTime();
+  state.animation->started = true;
+  const Presentation start = state.animation->start;
+  for (const ViewKey key : state.views) {
+    SmoothClipView *participant = viewForKey(key);
+    [participant smoothClipApplyPresentation:start];
+    dispatchActiveAnimationJoin(state, participant, key, start);
+  }
+}
+
 } // namespace
 
 void setCompletionCallback(
@@ -320,7 +353,12 @@ void registerView(
     state.hasLatest = true;
   }
   const bool hasAnimation = state.animation.has_value();
-  const bool startsLatch = hasAnimation && !state.animation->started;
+  const bool hasLatch = hasAnimation && !state.animation->started;
+  // A latch may only start once this view can produce a visible frame; a
+  // registration from a detached subtree (transparentModal before its view
+  // controller is presented) keeps the latch held and viewBecameDisplayable
+  // starts it inside the attach commit.
+  const bool startsLatch = hasLatch && [view smoothClipCanDisplay];
   const bool shouldReplay =
       hasAnimation && state.animation->started && !state.views.empty();
   Presentation visible = state.latest;
@@ -339,7 +377,7 @@ void registerView(
     visible = reference != nil
         ? [reference smoothClipCurrentPresentation]
         : state.animation->start;
-  } else if (startsLatch) {
+  } else if (hasLatch) {
     // state.latest already holds the latch's TARGET; applying it here is
     // exactly the jump this path exists to avoid.
     visible = state.animation->start;
@@ -351,28 +389,56 @@ void registerView(
   }
   [view smoothClipApplyPresentation:visible];
   if (startsLatch) {
-    // Start the latched animation: rebase the join clock before any elapsed
-    // math runs (dispatch below and the first-layout joinActiveAnimation).
-    state.animation->startedAt = CACurrentMediaTime();
-    state.animation->started = true;
+    // Rebases the join clock and dispatches to every registered view (the
+    // participant inserts inside the joins also keep unregisterView
+    // orphan-safe for a mount-then-unmount before first layout).
+    startLatchedAnimation(state);
+    return;
   }
-  if (!(shouldReplay || startsLatch)) return;
-
-  // The participant insert inside the join is also what keeps unregisterView
-  // orphan-safe for a mount-then-unmount before first layout.
+  if (!shouldReplay) return;
   dispatchActiveAnimationJoin(state, view, key, visible);
 }
 
+void viewBecameDisplayable(uint64_t driverId, SmoothClipView *view) {
+  NSCAssert(NSThread.isMainThread, @"SmoothClip registry is main-thread only");
+  auto iterator = registry().find(driverId);
+  if (iterator == registry().end()) return;
+  auto &state = iterator->second;
+  if (!state.animation.has_value()) return;
+  const ViewKey key = keyForView(view);
+  if (std::find(state.views.begin(), state.views.end(), key) ==
+      state.views.end()) {
+    return;
+  }
+  if (!state.animation->started) {
+    if (![view smoothClipCanDisplay]) return;
+    startLatchedAnimation(state);
+    return;
+  }
+  // A running animation whose install this view deferred while it could not
+  // display: resume through the standard mid-flight join (original clock —
+  // late joiners stay in sync with peers that were already rendering).
+  if ([view smoothClipHasPendingInstall]) {
+    joinActiveAnimation(driverId, view);
+  }
+}
+
 bool joinActiveAnimation(uint64_t driverId, SmoothClipView *view) {
   NSCAssert(NSThread.isMainThread, @"SmoothClip registry is main-thread only");
   auto iterator = registry().find(driverId);
-  if (iterator == registry().end()) return false;
+  if (iterator == registry().end()) {
+    return false;
+  }
   auto &state = iterator->second;
-  if (!state.animation.has_value() || state.views.empty()) return false;
+  if (!state.animation.has_value() || state.views.empty()) {
+    return false;
+  }
   // Unreachable in the normal flow (a pending install implies the animation
   // was dispatched, which implies started), but a join must never compute
   // elapsed time against an un-rebased latch clock.
-  if (!state.animation->started) return false;
+  if (!state.animation->started) {
+    return false;
+  }
   const ViewKey key = keyForView(view);
   if (std::find(state.views.begin(), state.views.end(), key) ==
       state.views.end()) {
@@ -408,11 +474,50 @@ void unregisterView(uint64_t driverId, SmoothClipView *view) {
       state.animation->participants.erase(key) > 0) {
     state.animation->finished = false;
     if (state.animation->participants.empty()) {
-      // The animation ends here; without releasing ownership a host that
-      // remounts on this driver later would drop every interactive update.
-      state.ownership = Ownership::Interactive;
-      emitCompletion(
-          driverId, state, state.animation->animationId, false);
+      auto &active = *state.animation;
+      const double elapsedMs =
+          (CACurrentMediaTime() - active.startedAt) * 1000.0;
+      const double remainingMs = MAX(0, active.durationMs - elapsedMs);
+      const bool canResume = !state.destroyed &&
+          (active.kind == AnimationKind::Spring || remainingMs > 0);
+      if (!canResume) {
+        // The animation ends here; without releasing ownership a host that
+        // remounts on this driver later would drop every interactive update.
+        state.ownership = Ownership::Interactive;
+        emitCompletion(driverId, state, active.animationId, false);
+      } else {
+        // The last rendering host left mid-flight (remount, screen swap).
+        // Completing here would leave `latest` at the target and statically
+        // snap any re-registering host straight to it. Re-latch instead:
+        // freeze the remaining animation at the departing view's visible
+        // geometry so the next displayable host resumes it with the true
+        // remaining time. Ownership stays Native — the pending animation
+        // still owns rendering intent; destroyDriver cancels a latch that
+        // never finds a host, so the completion cannot hang.
+        const Presentation visible = [view smoothClipIsJoinable]
+            ? [view smoothClipCurrentPresentation]
+            : active.start;
+        if (active.kind == AnimationKind::Timing) {
+          active.durationMs = remainingMs;
+          active.timing.durationMs = remainingMs;
+        } else if (active.kind == AnimationKind::Keyframes) {
+          const double progress = active.durationMs <= 0
+              ? 1
+              : MIN(1, MAX(0, elapsedMs / active.durationMs));
+          std::vector<Keyframe> remaining;
+          remaining.push_back({0, visible});
+          for (const Keyframe &frame : active.keyframes) {
+            if (frame.offset <= progress) continue;
+            const double offset = (frame.offset - progress) / (1 - progress);
+            remaining.push_back({offset, frame.presentation});
+          }
+          if (remaining.size() == 1) remaining.push_back({1, state.latest});
+          active.keyframes = std::move(remaining);
+          active.durationMs = remainingMs;
+        }
+        active.start = visible;
+        active.started = false;
+      }
     }
   }
   state.views.erase(
@@ -469,6 +574,21 @@ void setPresentation(
   }
   if (takeOwnership) {
     state.destroyed = false;
+    // A held latch is strictly newer intent than this write: the latch was
+    // created after whatever value the caller read (the hook's seed replays
+    // a SharedValue that an earlier animateTo already advanced to its
+    // target). Cancelling it here would seed the target and turn the pending
+    // animation into a static jump. Callers that want to override a latch
+    // cancel it explicitly first.
+    if (state.animation.has_value() && !state.animation->started) {
+#if defined(SMOOTH_CLIP_ENABLE_SIGNPOSTS) && SMOOTH_CLIP_ENABLE_SIGNPOSTS
+      if (signpostsEnabled) {
+        os_signpost_interval_end(
+            signpostLog(), identifier, "lookup-fanout", "ignored=held-latch");
+      }
+#endif
+      return;
+    }
     cancelActive(driverId, state, false);
   }
   applyPresentation(state, presentation);
@@ -514,7 +634,9 @@ int32_t animateTiming(
     // documented rejection sentinel.
     return 0;
   }  auto iterator = registry().find(driverId);
-  if (iterator == registry().end()) return 0;
+  if (iterator == registry().end()) {
+    return 0;
+  }
   auto &state = iterator->second;
   state.destroyed = false;
   const int32_t animationId = allocateAnimationId(state);
@@ -534,13 +656,15 @@ int32_t animateTiming(
   active.durationMs = animation.durationMs;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
-  active.started = !state.views.empty();
+  active.started = anyDisplayableView(state);
   state.animation = std::move(active);
   if (!state.animation->started) {
-    // Latch: no host view yet (animateTo raced the mount). Ownership stays
+    // Latch: no host view can display yet (animateTo raced the mount, or the
+    // host sits in a detached subtree awaiting presentation). Ownership stays
     // Native — the pending animation owns rendering intent — and the first
-    // registerView rebases startedAt and starts it. The non-zero id is still
-    // returned synchronously so the JS side does not treat this as rejection.
+    // displayable registration/attach rebases startedAt and starts it. The
+    // non-zero id is still returned synchronously so the JS side does not
+    // treat this as rejection.
     return animationId;
   }
 #if defined(SMOOTH_CLIP_ENABLE_SIGNPOSTS) && SMOOTH_CLIP_ENABLE_SIGNPOSTS
@@ -586,10 +710,10 @@ int32_t animateSpring(
   active.spring = animation;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
-  active.started = !state.views.empty();
+  active.started = anyDisplayableView(state);
   state.animation = std::move(active);
   if (!state.animation->started) {
-    // Latched until the first registerView — see animateTiming.
+    // Latched until the first displayable view — see animateTiming.
     return animationId;
   }
 #if defined(SMOOTH_CLIP_ENABLE_SIGNPOSTS) && SMOOTH_CLIP_ENABLE_SIGNPOSTS
@@ -637,10 +761,10 @@ int32_t animateKeyframes(
   active.durationMs = durationMs;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
-  active.started = !state.views.empty();
+  active.started = anyDisplayableView(state);
   state.animation = std::move(active);
   if (!state.animation->started) {
-    // Latched until the first registerView — see animateTiming.
+    // Latched until the first displayable view — see animateTiming.
     return animationId;
   }
   for (const ViewKey key : state.views) {

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)
@@ -167,6 +173,13 @@ using namespace facebook::react;
   }
 }
 
+- (void)didMoveToWindow {
+  [super didMoveToWindow];
+  if (_driverId != 0 && [self smoothClipCanDisplay]) {
+    smoothclip::viewBecameDisplayable(_driverId, self);
+  }
+}
+
 - (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
                           index:(NSInteger)index {
   NSAssert(childComponentView.superview == nil,
@@ -298,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 {
@@ -403,6 +369,17 @@ using namespace facebook::react;
   return _hasLayout;
 }
 
+- (BOOL)smoothClipCanDisplay {
+  // A CA animation committed while this view's layer tree is detached from
+  // the render tree does not survive the later attach commit; installs and
+  // latch starts must wait until a frame can actually be produced.
+  return _hasLayout && self.window != nil;
+}
+
+- (BOOL)smoothClipHasPendingInstall {
+  return _pendingAnimationInstall;
+}
+
 - (smoothclip::Presentation)smoothClipFreezePresentation {
   const smoothclip::Presentation visible =
       [self smoothClipCurrentPresentation];
@@ -647,7 +624,7 @@ using namespace facebook::react;
 }
 
 - (void)startAnimationToRequestedGeometryWithDuration:(CFTimeInterval)duration {
-  if (!_hasLayout) {
+  if (![self smoothClipCanDisplay]) {
     _pendingAnimationInstall = YES;
     return;
   }
@@ -720,7 +697,7 @@ using namespace facebook::react;
   [self storeRequestedPresentation:presentation];
   _activeAnimationKind = 3;
   _activeAnimationId = animationId;
-  if (!_hasLayout) {
+  if (![self smoothClipCanDisplay]) {
     _pendingAnimationInstall = YES;
     return;
   }
@@ -937,8 +914,14 @@ using namespace facebook::react;
     // the true remaining duration instead of jumping to the target.
     [super updateLayoutMetrics:layoutMetrics oldLayoutMetrics:oldLayoutMetrics];
     _hasLayout = YES;
-    _pendingAnimationInstall = NO;
     [self layoutContentContainer];
+    if (self.window == nil) {
+      // Still detached (transparentModal subtree before presentation): an
+      // install here would not survive the attach commit. Keep the install
+      // pending; didMoveToWindow completes it.
+      return;
+    }
+    _pendingAnimationInstall = NO;
     if (!smoothclip::joinActiveAnimation(_driverId, self)) {
       // The animation finished or was cancelled while awaiting layout.
       _activeAnimationId = 0;
@@ -984,6 +967,14 @@ using namespace facebook::react;
       [self writeLayerRect:paused.rect radius:paused.radius];
     }
   } else if (wasAnimating) {
+    if (![self smoothClipCanDisplay]) {
+      // Relayout while detached, with an animation dispatched to this view
+      // (a transparentModal subtree resized before presentation): an install
+      // from this commit would not survive the attach commit. Keep the
+      // install deferred; didMoveToWindow completes it via the registry join.
+      _pendingAnimationInstall = YES;
+      return;
+    }
     const int32_t animationId = _activeAnimationId;
     const NSInteger animationKind = _activeAnimationKind;
     [self stopLayerAnimationWithoutCallback];
@@ -1081,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/ios/SmoothClipViewRegistry.h

@@ -16,6 +16,14 @@ void unregisterView(uint64_t driverId, SmoothClipView *view);
 // install was deferred because it had no layout yet. Returns false when the
 // driver or its active animation no longer exists.
 bool joinActiveAnimation(uint64_t driverId, SmoothClipView *view);
+// Called when a registered view first becomes able to produce a visible
+// frame (has layout AND is attached to a window). Starts a latched animation
+// — rebasing its clock so no progress is burned while the view was
+// detached — or completes a deferred install for an already-running one.
+// A CA animation committed while the host's layer tree is detached (e.g. a
+// transparentModal subtree before its view controller is presented) does not
+// survive the attach commit; installs must therefore wait for this signal.
+void viewBecameDisplayable(uint64_t driverId, SmoothClipView *view);
 void viewAnimationDidStop(
     uint64_t driverId,
     int32_t animationId,

package/lib/module/drivers.ios.js

@@ -45,6 +45,11 @@ function reduceMotionCode(value) {
 function animationIsFinite(target, animation) {
   'worklet';
 
+  if (animation.from !== undefined && !isFiniteClipPresentation(animation.from)) {
+    // Silently dropping an invalid explicit start would re-open the exact
+    // stale-start handoff `from` exists to close — reject the whole call.
+    return false;
+  }
   if (animation.type === 'timing') {
     return Number.isFinite(animation.duration) && animation.controlPoints.every(Number.isFinite);
   }
@@ -165,6 +170,15 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       if (!isFiniteClipPresentation(target) || !animationIsFinite(target, animation)) {
         return rejectAnimationHostFunction(driverId);
       }
+      const from = animation.from;
+      if (from !== undefined) {
+        // Fused hot write: exactly setScalars(from…) issued immediately
+        // before the handoff, so native's latest value — the animation
+        // start below — is the caller's explicit presentation. Also
+        // re-grabs from a running animation, which the implicit
+        // interactive-start path would silently skip.
+        setScalarsOnUI(from.clip.x, from.clip.y, from.clip.width, from.clip.height, from.clip.radius, from.contentTranslateX, from.contentTranslateY);
+      }
 
       // After a setScalars hot write the SharedValue no longer matches what
       // is on screen; passing it as the start would snap the animation back.