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

package/README.md

@@ -141,10 +141,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,35 +181,64 @@ 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.
 - `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. 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 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).
-- An `animateTo` issued before any host view has registered (for example from
-  an effect in the same commit that mounts the host, or inside a modal route
-  that attaches late) is held pending and starts with its full duration when
-  the first view registers. If no view ever registers, the pending animation
-  survives until it is replaced, cancelled, overridden by a take-ownership
-  write, or the driver is destroyed — at which point its single
+- `options.onAnimationComplete` fires exactly once per animation with its ID
+  and `finished` state, including cancellation, replacement, and native-side
+  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.
+- 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

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/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

@@ -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,10 @@ 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;
+// One vsync of slack for the post-stall run-ahead guard in advance():
+// frame-axis elapsed may lead wall elapsed by at most this much before the
+// animation is re-anchored onto honest wall 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 +378,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;
@@ -458,24 +429,62 @@ 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;
+  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);
+  }
+  applyToViews(state, animation.start);
+  scheduleFrame();
+}
+
 int32_t startAnimation(
     uint64_t driverId,
     DriverState &state,
     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
   // freeze-at-start / replace-from-start semantics with no extra branches.
   animation.current = animation.start;
-  animation.started = !state.views.empty();
+  animation.started = anyDisplayableView(state);
   state.animation = std::move(animation);
   if (!state.animation->started) {
-    // Latch: no host view yet (animateTo raced the mount). The first
-    // registerViewAndroid 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.
+    // 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();
@@ -490,6 +499,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);
@@ -603,12 +644,21 @@ 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;
   state.hasLatest = true;
   state.ownership = Ownership::Interactive;
-  recordInteractiveSample(state, presentation);
+  recordVelocitySample(state.samples, toChannels(presentation), nowSeconds());
   applyToViews(state, presentation);
 }
 
@@ -628,10 +678,7 @@ 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();
+  resetVelocitySamples(state.samples, toChannels(current), nowSeconds());
   applyToViews(state, current);
   emitCompletion(driverId, animationId, false);
   return current;
@@ -680,7 +727,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);
@@ -795,6 +842,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()
@@ -849,15 +902,16 @@ void registerViewAndroid(
       ? state.animation->current
       : state.latest;
   JNIEnv *env = facebook::jni::Environment::current();
-  // The existing-view branch below is unreachable while an animation is
-  // latched (a latch implies views was empty at animate time), so only the
-  // new-view path needs to start latches.
   for (auto &existing : state.views) {
     if (env->IsSameObject(existing.view.get(), view.get())) {
       existing.density = density;
       existing.hostWidthPx = hostWidthPx;
       existing.hostHeightPx = hostHeightPx;
       deliverToView(existing, visible);
+      if (state.animation.has_value() && !state.animation->started &&
+          entryDisplayable(existing)) {
+        startLatchedAnimation(driverId, state);
+      }
       return;
     }
   }
@@ -867,22 +921,17 @@ void registerViewAndroid(
   // 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) {
+  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.
+    // 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.
-    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);
-    }
-    scheduleFrame();
+    startLatchedAnimation(driverId, state);
   }
 }
 
@@ -908,6 +957,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;
   }
 }
@@ -930,11 +1002,63 @@ 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;
+      // 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);
+      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) {