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

package/README.md

@@ -194,10 +194,23 @@ const gesture = Gesture.Pan()
   validated, monotonically increasing offsets from zero through one.
 - `cancel()` freezes visible presentation by default. Pass `'target'` as its
   behavior to jump to the requested endpoint.
-- `options.onAnimationComplete` fires once per animation with its ID and
-  `finished` state, including cancellation, replacement, participant unmount,
-  and native-side rejection (`animateTo` then returns `0` and one
-  `finished: false` completion is delivered).
+- `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
+  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.
+- 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
+  starts with its full duration at the first displayable registration or
+  window attach. A pending animation owns the driver: take-ownership writes
+  (`set`, `setScalars`, the hook's seed) are dropped while it is held —
+  replace it with another `animateTo`, or cancel it via `beginInteraction()`
+  or `cancel()`. If no view ever becomes displayable, it survives until it is
+  replaced, cancelled, or the driver is destroyed — at which point its single
+  `finished: false` completion is delivered.
 
 Do not call `driver.ui` from React code — it throws on the React runtime; use
 `driver.react` there. During a native transition, `driver.presentation.value`

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

@@ -22,6 +22,7 @@ struct JSmoothClipView : facebook::jni::JavaClass<JSmoothClipView> {
       const NormalizedClip &clip,
       double contentTranslateXPx,
       double contentTranslateYPx) const;
+  bool isViewAttachedToWindow() const;
 };
 
 // Called from Kotlin (SmoothClipViewManager) on the UI thread when a Fabric
@@ -44,6 +45,13 @@ void setViewHostGeometryAndroid(
 void unregisterViewAndroid(
     uint64_t driverId,
     facebook::jni::alias_ref<JSmoothClipView> view);
+// Called from Kotlin when a registered view attaches to a window. A latched
+// animation may only start once a registered view can actually produce a
+// visible frame (attached AND has host geometry); otherwise its clock would
+// burn progress no one can see.
+void viewBecameDisplayableAndroid(
+    uint64_t driverId,
+    facebook::jni::alias_ref<JSmoothClipView> view);
 
 // Installs `global.__SmoothClipView` (worklet-callable host functions) into the
 // JS runtime and wires native animation completion delivery through the

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

@@ -406,6 +406,15 @@ void nativeUnregisterView(
   smoothclip::unregisterViewAndroid(static_cast<uint64_t>(driverId), view);
 }
 
+void nativeViewBecameDisplayable(
+    jni::alias_ref<jni::JObject>,
+    jdouble driverId,
+    jni::alias_ref<smoothclip::JSmoothClipView> view) {
+  if (driverId <= 0 || !std::isfinite(driverId)) return;
+  smoothclip::viewBecameDisplayableAndroid(
+      static_cast<uint64_t>(driverId), view);
+}
+
 void nativeInvalidate(jni::alias_ref<jni::JObject>) {
   smoothclip::invalidateBindings();
 }
@@ -422,6 +431,8 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
             makeNativeMethod(
                 "nativeSetViewHostGeometry", nativeSetViewHostGeometry),
             makeNativeMethod("nativeUnregisterView", nativeUnregisterView),
+            makeNativeMethod(
+                "nativeViewBecameDisplayable", nativeViewBecameDisplayable),
             makeNativeMethod("nativeInvalidate", nativeInvalidate),
         });
   });

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

@@ -47,6 +47,10 @@ struct ActiveAnimation {
   std::array<double, 7> springVelocity{};
   double lastFrameS = 0;
   bool finished = true;
+  // False while the animation is latched: built before any host view
+  // registered, held un-rendered (and out of animatingDrivers()) until the
+  // first registerViewAndroid rebases the clock and starts it.
+  bool started = false;
 };
 
 // Per-view fanout state. Density and host metrics are pushed from Kotlin at
@@ -454,20 +458,57 @@ Presentation prepareAnimation(
   return resolvedStart;
 }
 
+// A view can only render the animation once it is attached to a window and
+// has pushed real host geometry; a clock started before that burns progress
+// no one can see (the transparentModal mount pattern).
+bool entryDisplayable(const ViewEntry &entry) {
+  return entry.hostWidthPx > 0 && entry.hostHeightPx > 0 &&
+      entry.view->isViewAttachedToWindow();
+}
+
+bool anyDisplayableView(const DriverState &state) {
+  for (const ViewEntry &entry : state.views) {
+    if (entryDisplayable(entry)) return true;
+  }
+  return false;
+}
+
+// Starts a latched animation: rebases the clock so no progress was burned
+// while no view could display, then joins the choreographer loop.
+void startLatchedAnimation(uint64_t driverId, DriverState &state) {
+  auto &animation = *state.animation;
+  animation.started = true;
+  animation.startedAtS = nowSeconds();
+  animation.lastFrameS = animation.startedAtS;
+  auto &active = animatingDrivers();
+  if (std::find(active.begin(), active.end(), driverId) == active.end()) {
+    active.push_back(driverId);
+  }
+  applyToViews(state, animation.start);
+  scheduleFrame();
+}
+
 int32_t startAnimation(
     uint64_t driverId,
     DriverState &state,
-    ActiveAnimation animation,
-    const Presentation &target) {
-  if (state.views.empty()) {
-    applyPresentation(state, target);
-    emitCompletion(driverId, animation.id, true);
-    return animation.id;
-  }
+    ActiveAnimation animation) {
   animation.startedAtS = nowSeconds();
   animation.lastFrameS = animation.startedAtS;
+  // 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
+  // freeze-at-start / replace-from-start semantics with no extra branches.
   animation.current = animation.start;
+  animation.started = anyDisplayableView(state);
   state.animation = std::move(animation);
+  if (!state.animation->started) {
+    // Latch: no host view can display yet (animateTo raced the mount, or
+    // every host is detached/unsized). The first displayable registration,
+    // host-geometry push, or window attach rebases the clock, joins
+    // animatingDrivers() and schedules the frame loop. Non-zero id is still
+    // returned so the JS side does not treat this as rejection.
+    return state.animation->id;
+  }
   auto &active = animatingDrivers();
   if (std::find(active.begin(), active.end(), driverId) == active.end()) {
     active.push_back(driverId);
@@ -593,6 +634,15 @@ void setPresentation(
   if (!takeOwnership && state.ownership != Ownership::Interactive) return;
   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) {
+      return;
+    }
     finishActive(driverId, state, false);
   }
   state.latest = presentation;
@@ -652,7 +702,7 @@ int32_t animateTiming(
   active.start = resolvedStart;
   active.target = presentation;
   active.durationS = animation.durationMs / 1000.0;
-  return startAnimation(driverId, state, std::move(active), presentation);
+  return startAnimation(driverId, state, std::move(active));
 }
 
 int32_t animateSpring(
@@ -695,7 +745,7 @@ int32_t animateSpring(
     active.springVelocity[index] =
         velocity * (targetChannels[index] - startChannels[index]);
   }
-  return startAnimation(driverId, state, std::move(active), presentation);
+  return startAnimation(driverId, state, std::move(active));
 }
 
 int32_t animateKeyframes(
@@ -726,7 +776,7 @@ int32_t animateKeyframes(
   active.start = resolvedStart;
   active.target = presentation;
   active.durationS = durationMs / 1000.0;
-  return startAnimation(driverId, state, std::move(active), presentation);
+  return startAnimation(driverId, state, std::move(active));
 }
 
 int32_t rejectAnimation(uint64_t driverId) {
@@ -785,6 +835,12 @@ void destroyDriver(uint64_t driverId) {
 
 // --- Android view lifecycle ----------------------------------------------
 
+bool JSmoothClipView::isViewAttachedToWindow() const {
+  static const auto method =
+      javaClassStatic()->getMethod<jboolean()>("isAttachedToWindow");
+  return method(self());
+}
+
 void JSmoothClipView::applyClip(const Presentation &presentation) const {
   static const auto method =
       javaClassStatic()
@@ -845,13 +901,31 @@ void registerViewAndroid(
       existing.hostWidthPx = hostWidthPx;
       existing.hostHeightPx = hostHeightPx;
       deliverToView(existing, visible);
+      if (state.animation.has_value() && !state.animation->started &&
+          entryDisplayable(existing)) {
+        startLatchedAnimation(driverId, state);
+      }
       return;
     }
   }
   ViewEntry entry{
       facebook::jni::make_global(view), density, hostWidthPx, hostHeightPx};
+  // `visible` above already delivered animation->current (= start) to the
+  // registering view — the correct first frame for a latched animation.
   deliverToView(entry, visible);
   state.views.push_back(std::move(entry));
+  if (state.animation.has_value() && !state.animation->started &&
+      entryDisplayable(state.views.back())) {
+    // Start the latched animation: rebase the clock so the first frame
+    // integrates from now, not from the pre-mount animateTo call. Gated on
+    // displayability — a mount-time registration from a detached subtree
+    // holds the latch until window attach / first host geometry.
+    // Note this function has no isOnMainThread() guard (Kotlin calls it from
+    // the view's main-thread attach path); scheduleFrame() is itself
+    // main-thread-gated, so an off-main register cannot bind the
+    // choreographer to the wrong thread.
+    startLatchedAnimation(driverId, state);
+  }
 }
 
 void setViewHostGeometryAndroid(
@@ -876,6 +950,29 @@ void setViewHostGeometryAndroid(
           state.animation.has_value() ? state.animation->current
                                       : state.latest);
     }
+    if (state.animation.has_value() && !state.animation->started &&
+        entryDisplayable(entry)) {
+      // First real host geometry made this view displayable.
+      startLatchedAnimation(driverId, state);
+    }
+    return;
+  }
+}
+
+void viewBecameDisplayableAndroid(
+    uint64_t driverId,
+    alias_ref<JSmoothClipView> view) {
+  if (!isOnMainThread()) return;
+  auto iterator = registry().find(driverId);
+  if (iterator == registry().end()) return;
+  auto &state = iterator->second;
+  if (!state.animation.has_value() || state.animation->started) return;
+  JNIEnv *env = facebook::jni::Environment::current();
+  for (auto &entry : state.views) {
+    if (!env->IsSameObject(entry.view.get(), view.get())) continue;
+    if (entryDisplayable(entry)) {
+      startLatchedAnimation(driverId, state);
+    }
     return;
   }
 }
@@ -898,11 +995,59 @@ void unregisterViewAndroid(
   }
   if (removed && state.animation.has_value()) {
     state.animation->finished = false;
-    if (state.views.empty()) {
-      // The animation ends here; release ownership so a later remount's
-      // interactive updates are not dropped.
-      state.ownership = Ownership::Interactive;
-      finishActive(driverId, state, false);
+    if (state.views.empty() && !state.animation->started) {
+      // A held latch returns to its original zero-view state; the next
+      // displayable registration still starts it (or destroyDriver cancels
+      // it). Completing it here would betray the pending intent.
+    } else if (state.views.empty()) {
+      auto &animation = *state.animation;
+      const double elapsedS = nowSeconds() - animation.startedAtS;
+      const double remainingS = std::max(0.0, animation.durationS - elapsedS);
+      const bool canResume = !state.destroyed &&
+          (animation.kind == AnimationKind::Spring || remainingS > 0);
+      if (!canResume) {
+        // The animation ends here; release ownership so a later remount's
+        // interactive updates are not dropped.
+        state.ownership = Ownership::Interactive;
+        finishActive(driverId, state, 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 its current geometry so the
+        // next displayable host resumes it with the true remaining time.
+        // destroyDriver cancels a latch that never finds a host, so the
+        // completion cannot hang.
+        if (animation.kind == AnimationKind::Timing) {
+          animation.durationS = remainingS;
+        } else if (animation.kind == AnimationKind::Keyframes) {
+          const double progress = animation.durationS <= 0
+              ? 1.0
+              : clamp01(elapsedS / animation.durationS);
+          std::vector<Keyframe> remaining;
+          remaining.push_back({0, animation.current});
+          for (const Keyframe &frame : animation.keyframes) {
+            if (frame.offset <= progress) continue;
+            remaining.push_back(
+                {(frame.offset - progress) / (1 - progress),
+                 frame.presentation});
+          }
+          if (remaining.size() == 1) {
+            remaining.push_back({1, animation.target});
+          }
+          animation.keyframes = std::move(remaining);
+          animation.durationS = remainingS;
+        }
+        animation.start = animation.current;
+        animation.started = false;
+        // A held latch must not tick: leave animatingDrivers() without
+        // resetting the animation (the eager-removal rule the choreographer
+        // loop depends on).
+        auto &active = animatingDrivers();
+        active.erase(
+            std::remove(active.begin(), active.end(), driverId),
+            active.end());
+      }
     }
   }
   if (state.destroyed && state.views.empty()) {

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

@@ -47,6 +47,13 @@ internal object SmoothClipBindings {
 
     external fun nativeUnregisterView(driverId: Double, view: SmoothClipView)
 
+    /**
+     * Notifies the registry that a registered view attached to a window; a
+     * latched animation may only start once a view can produce a visible
+     * frame (attached and with real host geometry).
+     */
+    external fun nativeViewBecameDisplayable(driverId: Double, view: SmoothClipView)
+
     /**
      * Releases runtime-bound listener state during host teardown; must run
      * while the JS runtime is still alive (module invalidate).

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

@@ -232,6 +232,16 @@ class SmoothClipView(context: ThemedReactContext) : ReactViewGroup(context) {
         }
     }
 
+    override fun onAttachedToWindow() {
+        super.onAttachedToWindow()
+        if (boundDriverId != 0.0) {
+            // A latched animation may only start once this view can produce a
+            // visible frame; window attach is that signal for views that
+            // registered from a detached subtree.
+            SmoothClipBindings.nativeViewBecameDisplayable(boundDriverId, this)
+        }
+    }
+
     override fun onConfigurationChanged(newConfig: Configuration) {
         super.onConfigurationChanged(newConfig)
         if (boundDriverId != 0.0) {

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 {
@@ -58,6 +60,10 @@ struct ActiveAnimation {
   std::vector<Keyframe> keyframes;
   double durationMs = 0;
   CFTimeInterval startedAt = 0;
+  // False while the animation is latched: built before any host view
+  // registered, held un-rendered until the first registerView rebases
+  // startedAt and starts it. startedAt is only meaningful once started.
+  bool started = false;
 };
 
 struct DriverState {
@@ -170,11 +176,20 @@ int32_t allocateAnimationId(DriverState &state) {
 }
 
 Presentation canonicalFrozenPresentation(DriverState &state) {
-  Presentation canonical = state.latest;
+  // A latched animation never rendered, so state.latest already holds its
+  // target; freezing there would jump the clip. Freeze at the start instead.
+  Presentation canonical =
+      state.animation.has_value() && !state.animation->started
+      ? state.animation->start
+      : 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;
     }
@@ -224,9 +239,16 @@ void prepareAnimation(
 Presentation resolvedAnimationStart(
     const DriverState &state,
     const AnimationStart &start) {
-  return start.hasInteractiveStart && state.ownership == Ownership::Interactive
-      ? start.interactiveStart
-      : state.latest;
+  if (start.hasInteractiveStart && state.ownership == Ownership::Interactive) {
+    return start.interactiveStart;
+  }
+  // Replacing a latched animation (e.g. open→close before the host mounted):
+  // it never rendered, and state.latest is its target — start from where the
+  // clip actually is, the latch's own start.
+  if (state.animation.has_value() && !state.animation->started) {
+    return state.animation->start;
+  }
+  return state.latest;
 }
 
 // Installs the remaining part of the active animation on a view that joins
@@ -270,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(
@@ -303,8 +352,15 @@ void registerView(
     state.latest = initialPresentation;
     state.hasLatest = true;
   }
+  const bool hasAnimation = state.animation.has_value();
+  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 =
-      state.animation.has_value() && !state.views.empty();
+      hasAnimation && state.animation->started && !state.views.empty();
   Presentation visible = state.latest;
   if (shouldReplay) {
     // A registered peer that never laid out reports zero geometry; joining
@@ -321,6 +377,10 @@ void registerView(
     visible = reference != nil
         ? [reference smoothClipCurrentPresentation]
         : state.animation->start;
+  } 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;
   }
   const ViewKey key = keyForView(view);
   if (std::find(state.views.begin(), state.views.end(), key) ==
@@ -328,17 +388,57 @@ void registerView(
     state.views.push_back(key);
   }
   [view smoothClipApplyPresentation:visible];
-  if (!shouldReplay || !state.animation.has_value()) return;
-
+  if (startsLatch) {
+    // 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) 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;
+  }
   const ViewKey key = keyForView(view);
   if (std::find(state.views.begin(), state.views.end(), key) ==
       state.views.end()) {
@@ -374,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(
@@ -435,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);
@@ -480,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);
@@ -500,10 +656,15 @@ int32_t animateTiming(
   active.durationMs = animation.durationMs;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
+  active.started = anyDisplayableView(state);
   state.animation = std::move(active);
-  if (state.views.empty()) {
-    state.ownership = Ownership::Interactive;
-    emitCompletion(driverId, state, animationId, true);
+  if (!state.animation->started) {
+    // 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
+    // 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
@@ -549,10 +710,10 @@ int32_t animateSpring(
   active.spring = animation;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
+  active.started = anyDisplayableView(state);
   state.animation = std::move(active);
-  if (state.views.empty()) {
-    state.ownership = Ownership::Interactive;
-    emitCompletion(driverId, state, animationId, true);
+  if (!state.animation->started) {
+    // Latched until the first displayable view — see animateTiming.
     return animationId;
   }
 #if defined(SMOOTH_CLIP_ENABLE_SIGNPOSTS) && SMOOTH_CLIP_ENABLE_SIGNPOSTS
@@ -600,10 +761,10 @@ int32_t animateKeyframes(
   active.durationMs = durationMs;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
+  active.started = anyDisplayableView(state);
   state.animation = std::move(active);
-  if (state.views.empty()) {
-    state.ownership = Ownership::Interactive;
-    emitCompletion(driverId, state, animationId, true);
+  if (!state.animation->started) {
+    // Latched until the first displayable view — see animateTiming.
     return animationId;
   }
   for (const ViewKey key : state.views) {

package/ios/SmoothClipView.mm

@@ -167,6 +167,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,
@@ -403,6 +410,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 +665,7 @@ using namespace facebook::react;
 }
 
 - (void)startAnimationToRequestedGeometryWithDuration:(CFTimeInterval)duration {
-  if (!_hasLayout) {
+  if (![self smoothClipCanDisplay]) {
     _pendingAnimationInstall = YES;
     return;
   }
@@ -720,7 +738,7 @@ using namespace facebook::react;
   [self storeRequestedPresentation:presentation];
   _activeAnimationKind = 3;
   _activeAnimationId = animationId;
-  if (!_hasLayout) {
+  if (![self smoothClipCanDisplay]) {
     _pendingAnimationInstall = YES;
     return;
   }
@@ -937,8 +955,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 +1008,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];

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/package.json

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