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

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

@@ -1,7 +1,8 @@
 #include "SmoothClipAndroid.h"
+#include "SmoothClipAnimationId.h"
+#include "SmoothClipAnimationCurve.h"
 #include "SmoothClipVelocityTracker.h"
 
-#include <android/choreographer.h>
 #include <fbjni/fbjni.h>
 
 #include <algorithm>
@@ -25,7 +26,22 @@ using facebook::jni::global_ref;
 
 enum class Ownership { Interactive, Native };
 enum class AnimationKind { Timing, Spring, Keyframes };
-
+enum class ViewParticipation { Deferred, Active, Suspended };
+
+// Load-bearing invariant, not just a convenience clock: advance()'s frame-clock
+// anchor compares this value ABSOLUTELY against a choreographer frame stamp
+// (std::min), so the two must share an epoch. They do — bionic's steady_clock,
+// System.nanoTime() behind Choreographer#frameTimeNanos, and the
+// SystemClock.uptimeMillis() Reanimated stamps its own animations with are all
+// CLOCK_MONOTONIC since boot. (The anchor this replaced subtracted two samples
+// of this clock and was epoch-independent; the min() is not.)
+//
+// Breaking that invariant fails silently and asymmetrically. A frame axis
+// running BEHIND the wall axis degrades quietly: min() always adopts the frame
+// stamp and animations lose only their sub-frame start offset. A frame axis
+// running AHEAD is fatal: min() always keeps startedAtS, the first fraction
+// (frame - startedAtS)/duration clamps to 1, and every animation completes on
+// its first frame.
 double nowSeconds() {
   return std::chrono::duration<double>(
              std::chrono::steady_clock::now().time_since_epoch())
@@ -40,26 +56,28 @@ struct ActiveAnimation {
   Presentation current{{0, 0, 0, 0, 0}, 0, 0};
   TimingAnimation timing{};
   SpringAnimation spring{};
-  std::vector<Keyframe> keyframes;
+  // Owns the keyframes and their precomputed monotone-cubic tangents; the
+  // tangent solve happens on reset(), never per frame.
+  KeyframeCurve 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{};
   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.
+  // False while the animation is latched, and held out of animatingDrivers()
+  // so it cannot tick. Two ways in: built before any host view could display
+  // (pre-registration, or a detached/unsized host), or re-latched by
+  // unregisterViewAndroid when the last DISPLAYABLE host left mid-flight.
+  // Started by whichever lifecycle/geometry update first sees a displayable
+  // entry; each rebases the clock through startLatchedAnimation.
   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.
+  // startedAtS stamp clears it so a re-latched resume re-anchors too — except
+  // a start that carried the JS-captured Reanimated stamp, which arrives
+  // pre-anchored (see startAnimation) and must not be min()'d again.
   bool frameClockAnchored = false;
 };
 
@@ -71,6 +89,8 @@ struct ViewEntry {
   double density = 0;
   double hostWidthPx = 0;
   double hostHeightPx = 0;
+  bool lifecycleVisible = false;
+  ViewParticipation participation = ViewParticipation::Deferred;
 };
 
 struct DriverState {
@@ -79,7 +99,6 @@ struct DriverState {
   Ownership ownership = Ownership::Interactive;
   std::vector<ViewEntry> views;
   std::optional<ActiveAnimation> animation;
-  int32_t nextAnimationId = 0;
   // Set by destroyDriver while views are still registered (StrictMode effect
   // replay, hosts mounted in another subtree). The entry is erased when the
   // last view leaves and revived by a take-ownership setPresentation.
@@ -131,7 +150,7 @@ struct JLooper : facebook::jni::JavaClass<JLooper> {
 std::atomic<pid_t> gMainThreadId{0};
 
 // The registry, the frame loop, and every view mutation are main-thread only:
-// AChoreographer_getInstance is per-thread, and binding the loop to the JS
+// Choreographer.getInstance() is per-thread, and binding the loop to the JS
 // thread would race Fabric mounting and mutate views off-main. The worklets
 // UI runtime executes on the main thread, so supported usage always passes;
 // direct off-main calls fail defined instead of racing.
@@ -155,72 +174,47 @@ bool isOnMainThread() {
 
 // --- Frame loop -----------------------------------------------------------
 
+// fbjni handle for the Kotlin frame-loop bridge. The loop posts through the
+// Java Choreographer (CALLBACK_ANIMATION) rather than the NDK AChoreographer:
+// the NDK instance is a separate frame source on the main Looper whose
+// ordering against the Java Choreographer's traversal (draw) phase is
+// undefined, so advances landing after the traversal presented one vsync
+// late — a randomly flipping ±1-frame phase between the clip and Reanimated
+// content. Posting into the same doFrame pass as Reanimated makes every
+// advance precede the draw by construction. It also retires the 32-bit
+// truncated-timestamp fallback: Java frameTimeNanos is a jlong everywhere.
+//
+// doCallbacks() extracts by wall-now rather than by frame time, so a post
+// issued from an earlier phase of a frame already in flight (CALLBACK_INPUT —
+// a gesture end that starts an animation) runs in that same doFrame instead
+// of the next one. Harmless (the fraction is ~0 and the write dedupes in
+// Kotlin) and one frame cheaper at the handoff than the NDK path allowed.
+struct JSmoothClipBindings : facebook::jni::JavaClass<JSmoothClipBindings> {
+  static constexpr auto kJavaDescriptor =
+      "Lcom/smoothclipview/SmoothClipBindings;";
+};
+
 bool gFrameScheduled = false;
 void onFrameImpl(double now);
-void onFrameLegacy(long frameTimeNanos, void *data);
 
 void scheduleFrame() {
   if (gFrameScheduled) return;
   // Defensive: never bind the per-thread choreographer to a non-main thread.
   if (!isOnMainThread()) return;
-  AChoreographer *choreographer = AChoreographer_getInstance();
-  if (choreographer == nullptr) return;
+  static const auto scheduleMethod =
+      JSmoothClipBindings::javaClassStatic()->getStaticMethod<void()>(
+          "scheduleFrame");
+  scheduleMethod(JSmoothClipBindings::javaClassStatic());
+  // Set only after a successful post: if the up-call ever threw with the flag
+  // already true, the loop would be dead until process restart.
   gFrameScheduled = true;
-  // AChoreographer_postFrameCallback64 (API 29+) only matters on 32-bit ABIs,
-  // where `long` truncates the timestamp; onFrameLegacy falls back to the
-  // clock there, so the legacy entry point covers every case.
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated-declarations"
-  AChoreographer_postFrameCallback(choreographer, &onFrameLegacy, nullptr);
-#pragma clang diagnostic pop
 }
 
 // --- Math (ported from SmoothClipRegistry.kt so both platforms match) -----
-
-double clamp01(double value) { return std::min(1.0, std::max(0.0, value)); }
-
-double cubicBezier(
-    double x1,
-    double y1,
-    double x2,
-    double y2,
-    double input) {
-  double low = 0;
-  double high = 1;
-  for (int iteration = 0; iteration < 14; iteration += 1) {
-    const double t = (low + high) / 2;
-    const double inverse = 1 - t;
-    const double x = 3 * inverse * inverse * t * x1 +
-        3 * inverse * t * t * x2 + t * t * t;
-    if (x < input) {
-      low = t;
-    } else {
-      high = t;
-    }
-  }
-  const double t = (low + high) / 2;
-  const double inverse = 1 - t;
-  return 3 * inverse * inverse * t * y1 + 3 * inverse * t * t * y2 +
-      t * t * t;
-}
-
-// Presentation <-> per-channel array (x, y, width, height, radius, tx, ty).
-std::array<double, 7> toChannels(const Presentation &presentation) {
-  return {presentation.clip.x,
-          presentation.clip.y,
-          presentation.clip.width,
-          presentation.clip.height,
-          presentation.clip.radius,
-          presentation.contentTranslateX,
-          presentation.contentTranslateY};
-}
-
-Presentation fromChannels(const std::array<double, 7> &channels) {
-  return Presentation{
-      {channels[0], channels[1], channels[2], channels[3], channels[4]},
-      channels[5],
-      channels[6]};
-}
+//
+// clamp01, toChannels/fromChannels, interpolate, the frame-clock anchor and the
+// keyframe curve now live in cpp/SmoothClipAnimationCurve.h so a test binary can
+// reach them without linking fbjni; ios/tests pins their behavior.
 
 // Springs settle below these per-channel thresholds (DIP and DIP/s).
 constexpr double kSpringSettleDisplacement = 0.05;
@@ -228,13 +222,6 @@ constexpr double kSpringSettleVelocity = 1.0;
 // Settle-based termination is backed by a hard cap so a pathological
 // configuration cannot run the frame loop forever.
 constexpr double kSpringMaxDurationS = 10.0;
-// Fixed slack for the post-stall run-ahead guard in advance(). The lead it
-// bounds is a latency DIFFERENTIAL — the anchor frame's dispatch latency
-// minus the current frame's — so the constant is refresh-rate independent
-// (it is not one vsync period; at 120 Hz it spans two). 17 ms keeps the
-// guard silent through normal callback jitter while capping post-stall
-// run-ahead at one 60 Hz frame of curve time.
-constexpr double kMaxFrameLeadS = 0.017;
 
 // Semi-implicit Euler per channel, substepped: one frame-sized step is only
 // stable for omega*dt < 2, and accepted stiffness/mass ratios exceed that at
@@ -285,37 +272,6 @@ bool advanceSpring(ActiveAnimation &animation, double now) {
   return settled || now - animation.startedAtS >= kSpringMaxDurationS;
 }
 
-Presentation interpolate(
-    const Presentation &from,
-    const Presentation &to,
-    double progress) {
-  const auto mix = [progress](double start, double end) {
-    return start + (end - start) * progress;
-  };
-  return Presentation{
-      {mix(from.clip.x, to.clip.x),
-       mix(from.clip.y, to.clip.y),
-       mix(from.clip.width, to.clip.width),
-       mix(from.clip.height, to.clip.height),
-       mix(from.clip.radius, to.clip.radius)},
-      mix(from.contentTranslateX, to.contentTranslateX),
-      mix(from.contentTranslateY, to.contentTranslateY)};
-}
-
-Presentation interpolateKeyframes(
-    const std::vector<Keyframe> &frames,
-    double progress) {
-  size_t upper = 1;
-  while (upper < frames.size() - 1 && progress > frames[upper].offset) {
-    upper += 1;
-  }
-  const Keyframe &lower = frames[upper - 1];
-  const Keyframe &higher = frames[upper];
-  const double span = higher.offset - lower.offset;
-  const double local = span <= 0 ? 1.0 : (progress - lower.offset) / span;
-  return interpolate(lower.presentation, higher.presentation, clamp01(local));
-}
-
 bool systemAnimatorsEnabled() {
   static const auto valueAnimatorClass =
       facebook::jni::findClassStatic("android/animation/ValueAnimator");
@@ -339,14 +295,6 @@ void emitCompletion(uint64_t driverId, int32_t animationId, bool finished) {
   }
 }
 
-int32_t allocateAnimationId(DriverState &state) {
-  state.nextAnimationId =
-      state.nextAnimationId == std::numeric_limits<int32_t>::max()
-      ? 1
-      : state.nextAnimationId + 1;
-  return state.nextAnimationId;
-}
-
 // Terminal per-frame delivery: scale DIP -> px and normalize against the
 // pushed host metrics in C++, so the JNI call carries final pixel floats and
 // the Kotlin side reduces to field stores + invalidateOutline().
@@ -398,6 +346,9 @@ std::vector<uint64_t> &animatingDrivers() {
 // erase/recreate cycle would let one frame integrate the animation twice.
 void clearActiveAnimation(uint64_t driverId, DriverState &state) {
   state.animation.reset();
+  for (ViewEntry &entry : state.views) {
+    entry.participation = ViewParticipation::Deferred;
+  }
   auto &active = animatingDrivers();
   active.erase(
       std::remove(active.begin(), active.end(), driverId), active.end());
@@ -437,7 +388,7 @@ Presentation prepareAnimation(
 // no one can see (the transparentModal mount pattern).
 bool entryDisplayable(const ViewEntry &entry) {
   return entry.hostWidthPx > 0 && entry.hostHeightPx > 0 &&
-      entry.view->isViewAttachedToWindow();
+      entry.lifecycleVisible;
 }
 
 bool anyDisplayableView(const DriverState &state) {
@@ -454,7 +405,6 @@ void startLatchedAnimation(uint64_t driverId, DriverState &state) {
   animation.started = true;
   animation.startedAtS = nowSeconds();
   animation.lastFrameS = animation.startedAtS;
-  animation.wallStartedAtS = animation.startedAtS;
   // Load-bearing for re-latch resumes: unregisterViewAndroid rewrites this
   // ActiveAnimation in place, so a stale anchor would replay the fraction-0
   // first frame the anchor exists to remove.
@@ -463,6 +413,11 @@ void startLatchedAnimation(uint64_t driverId, DriverState &state) {
   if (std::find(active.begin(), active.end(), driverId) == active.end()) {
     active.push_back(driverId);
   }
+  for (ViewEntry &entry : state.views) {
+    if (entryDisplayable(entry)) {
+      entry.participation = ViewParticipation::Active;
+    }
+  }
   applyToViews(state, animation.start);
   scheduleFrame();
 }
@@ -470,11 +425,21 @@ void startLatchedAnimation(uint64_t driverId, DriverState &state) {
 int32_t startAnimation(
     uint64_t driverId,
     DriverState &state,
-    ActiveAnimation animation) {
-  animation.startedAtS = nowSeconds();
-  animation.lastFrameS = animation.startedAtS;
-  animation.wallStartedAtS = animation.startedAtS;
-  animation.frameClockAnchored = false;
+    ActiveAnimation animation,
+    double startedAtHintS) {
+  // With a JS-captured hint the start stamp is Reanimated's own
+  // (`__frameTimestamp || _getAnimationTimestamp()`, read in the worklet that
+  // issued this call), already on the axis min() only approximates — so the
+  // animation arrives pre-anchored and advance() must not min() it against
+  // the dispatching frame, which for a CALLBACK_INPUT start is EARLIER than
+  // the call and would re-open the intra-frame lead the hint closes. Without
+  // a hint (NaN: latch-less legacy callers, tests, iOS ignoring the field)
+  // this reduces exactly to the old nowSeconds() + min() anchor path.
+  const double wallNow = nowSeconds();
+  const StartStamp stamp = resolveStartStamp(startedAtHintS, wallNow);
+  animation.startedAtS = stamp.startedAtS;
+  animation.lastFrameS = stamp.startedAtS;
+  animation.frameClockAnchored = stamp.frameClockAnchored;
   // 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
@@ -482,6 +447,11 @@ int32_t startAnimation(
   animation.current = animation.start;
   animation.started = anyDisplayableView(state);
   state.animation = std::move(animation);
+  for (ViewEntry &entry : state.views) {
+    entry.participation = state.animation->started && entryDisplayable(entry)
+        ? ViewParticipation::Active
+        : ViewParticipation::Deferred;
+  }
   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,
@@ -499,51 +469,117 @@ int32_t startAnimation(
   return state.animation->id;
 }
 
+void relatchIfNoDisplayable(uint64_t driverId, DriverState &state) {
+  if (!state.animation.has_value() || !state.animation->started ||
+      anyDisplayableView(state)) {
+    return;
+  }
+  auto &animation = *state.animation;
+  for (ViewEntry &entry : state.views) {
+    if (entry.participation == ViewParticipation::Active) {
+      entry.participation = ViewParticipation::Suspended;
+    }
+  }
+
+  if (animation.kind == AnimationKind::Timing) {
+    const TimingContinuation continuation = timingContinuationAtFrame(
+        animation.timing,
+        animation.start,
+        animation.target,
+        animation.lastFrameS,
+        animation.startedAtS,
+        animation.durationS);
+    animation.current = continuation.start;
+    animation.timing = continuation.animation;
+    animation.durationS = continuation.animation.durationMs / 1000.0;
+  } else if (animation.kind == AnimationKind::Keyframes) {
+    const KeyframeContinuation continuation = keyframeContinuationAtFrame(
+        animation.keyframes.frames(),
+        animation.current,
+        animation.target,
+        animation.lastFrameS,
+        animation.startedAtS,
+        animation.durationS);
+    animation.current = continuation.start;
+    animation.keyframes.reset(continuation.frames);
+    animation.durationS = continuation.durationMs / 1000.0;
+  }
+
+  if (state.destroyed ||
+      (animation.kind != AnimationKind::Spring && animation.durationS <= 0)) {
+    state.ownership = Ownership::Interactive;
+    finishActive(driverId, state, false);
+    return;
+  }
+
+  animation.start = animation.current;
+  animation.started = false;
+  animation.frameClockAnchored = false;
+  auto &active = animatingDrivers();
+  active.erase(
+      std::remove(active.begin(), active.end(), driverId), active.end());
+}
+
+void reconcileViewDisplayability(
+    uint64_t driverId,
+    DriverState &state,
+    ViewEntry &entry) {
+  if (!state.animation.has_value()) return;
+  if (!state.animation->started) {
+    if (entryDisplayable(entry)) startLatchedAnimation(driverId, state);
+    return;
+  }
+
+  if (entryDisplayable(entry)) {
+    if (entry.participation != ViewParticipation::Active) {
+      entry.participation = ViewParticipation::Active;
+      deliverToView(entry, state.animation->current);
+    }
+  } else if (entry.participation == ViewParticipation::Active) {
+    entry.participation = ViewParticipation::Suspended;
+  }
+  relatchIfNoDisplayable(driverId, state);
+}
+
 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;
+    // This is the stamp-less/latch fallback. Worklet-issued animations carry
+    // Reanimated's exact `__frameTimestamp || _getAnimationTimestamp()` value
+    // and arrive pre-anchored, so they skip this approximation — including the
+    // CALLBACK_INPUT case where the current frame stamp predates the call.
+    // Here startedAtS/lastFrameS hold nowSeconds() sampled at native latch
+    // attach or by an older caller, while `now` is the frame's vsync stamp on
+    // the same CLOCK_MONOTONIC timebase. Taking the earlier stamp prevents a
+    // mid-frame native start from duplicating fraction zero.
+    //
+    // Deliberately NOT a wall-elapsed rebase (`now - (nowSeconds() -
+    // startedAtS)`): that bakes THIS frame's dispatch latency into the curve
+    // for the animation's whole duration, de-phasing the clip from parallel
+    // Reanimated content by however much main-thread work happened to run
+    // before us on frame one — worst on the first frame of a heavy
+    // transition, which is exactly when it is sampled. Catching up after a
+    // stall needs no help here either: Choreographer#doFrame snaps a late
+    // frameTimeNanos forward to within one frame interval of now (jitter
+    // correction), for every CALLBACK_ANIMATION client at once, so the clip
+    // and the content stall and catch up together.
+    animation.startedAtS = anchorStartTime(animation.startedAtS, now);
     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);
   } else {
+    // This is the frame whose presentation is delivered below. Lifecycle
+    // re-latch must trim from this timestamp, never from a later wall sample.
+    animation.lastFrameS = now;
     const double fraction =
-        animation.durationS <= 0
-        ? 1.0
-        : clamp01((now - animation.startedAtS) / animation.durationS);
+        timingFraction(now, animation.startedAtS, animation.durationS);
     if (animation.kind == AnimationKind::Keyframes) {
-      animation.current = interpolateKeyframes(animation.keyframes, fraction);
+      animation.current = animation.keyframes.evaluate(fraction);
     } else {
       const double eased = cubicBezier(
           animation.timing.controlPoint1X,
@@ -561,7 +597,13 @@ void advance(uint64_t driverId, DriverState &state, double now) {
 
   if (done) {
     const int32_t animationId = animation.id;
-    const bool finished = animation.finished;
+    bool finished = animation.finished;
+    for (const ViewEntry &entry : state.views) {
+      if (entry.participation == ViewParticipation::Suspended) {
+        finished = false;
+        break;
+      }
+    }
     const Presentation target = animation.target;
     clearActiveAnimation(driverId, state);
     state.latest = target;
@@ -593,26 +635,27 @@ void onFrameImpl(double now) {
   if (!animatingDrivers().empty()) scheduleFrame();
 }
 
-void onFrameLegacy(long frameTimeNanos, void * /*data*/) {
-  // An fbjni exception must not unwind out of a C callback (std::terminate).
-  // Clear it, keep the loop scheduled, and let the next frame re-scan.
+} // namespace
+
+// Advances the frame loop; reached from SmoothClipBindings.nativeOnFrame
+// inside Choreographer#doFrame. Nothing may unwind back into doFrame — fbjni
+// would rethrow it as a Java exception and take down the main thread. Clear
+// any pending JNI exception, keep the loop scheduled, and let the next frame
+// re-scan.
+void onFrameAndroid(double frameTimeS) {
   try {
-#if defined(__LP64__) || (defined(__SIZEOF_POINTER__) && __SIZEOF_POINTER__ == 8)
-    onFrameImpl(static_cast<double>(frameTimeNanos) / 1e9);
-#else
-    // 32-bit `long` truncates the nanosecond timestamp; fall back to the
-    // clock.
-    onFrameImpl(nowSeconds());
-#endif
+    onFrameImpl(frameTimeS);
   } catch (...) {
     JNIEnv *env = facebook::jni::Environment::current();
     if (env != nullptr && env->ExceptionCheck()) env->ExceptionClear();
-    scheduleFrame();
+    try {
+      scheduleFrame();
+    } catch (...) {
+      // gFrameScheduled stays false; the next animation start re-schedules.
+    }
   }
 }
 
-} // namespace
-
 // --- Public smoothclip:: interface (shared with iOS via SmoothClipRegistry.h)
 
 void setCompletionCallback(const void *owner, CompletionCallback callback) {
@@ -631,7 +674,8 @@ void clearCompletionCallback(const void *owner) {
 void setPresentation(
     uint64_t driverId,
     Presentation presentation,
-    bool takeOwnership) {
+    bool takeOwnership,
+    bool overridePendingAnimation) {
   if (!isOnMainThread()) return;
   auto iterator = registry().find(driverId);
   if (!takeOwnership) {
@@ -647,13 +691,11 @@ 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) {
+    // Passive seeds and public setters must not displace newer pending intent.
+    // The fused animation.from write is different: it is the caller's newest,
+    // authoritative start and explicitly opts in to cancelling the old latch.
+    if (state.animation.has_value() && !state.animation->started &&
+        !overridePendingAnimation) {
       return;
     }
     finishActive(driverId, state, false);
@@ -681,12 +723,8 @@ Presentation beginInteraction(uint64_t driverId) {
   state.latest = current;
   state.hasLatest = true;
   state.ownership = Ownership::Interactive;
-  // Plain record, not a reset — iOS parity (smoothClipFreezePresentation
-  // records the frozen value). Pairing the frozen mid-flight presentation
-  // with the last real sample lets a grab-and-instant-refling inherit
-  // bounded recent motion instead of launching dead; an unchanged value
-  // dedupes to a no-op and ages out through the staleness guard.
-  recordVelocitySample(state.samples, toChannels(current), nowSeconds());
+  // The frozen frame came from native animation movement, not an interactive
+  // write. Do not let it become a later `initialVelocity: inherit` sample.
   applyToViews(state, current);
   emitCompletion(driverId, animationId, false);
   return current;
@@ -699,10 +737,15 @@ int32_t animateTiming(
     TimingAnimation animation) {
   if (!isOnMainThread()) return 0;
   auto iterator = registry().find(driverId);
-  if (iterator == registry().end()) return 0;
+  if (iterator == registry().end()) {
+    if (!start.hasInteractiveStart) return 0;
+    iterator = registry().try_emplace(driverId).first;
+    iterator->second.latest = start.interactiveStart;
+    iterator->second.hasLatest = true;
+  }
   auto &state = iterator->second;
   state.destroyed = false;
-  const int32_t animationId = allocateAnimationId(state);
+  const int32_t animationId = allocateAnimationId();
   const Presentation resolvedStart =
       prepareAnimation(driverId, state, start, presentation);
   if (shouldReduceMotion(animation.reduceMotion) || animation.durationMs <= 0) {
@@ -717,7 +760,7 @@ int32_t animateTiming(
   active.start = resolvedStart;
   active.target = presentation;
   active.durationS = animation.durationMs / 1000.0;
-  return startAnimation(driverId, state, std::move(active));
+  return startAnimation(driverId, state, std::move(active), start.startedAtHintS);
 }
 
 int32_t animateSpring(
@@ -727,10 +770,15 @@ int32_t animateSpring(
     SpringAnimation animation) {
   if (!isOnMainThread()) return 0;
   auto iterator = registry().find(driverId);
-  if (iterator == registry().end()) return 0;
+  if (iterator == registry().end()) {
+    if (!start.hasInteractiveStart) return 0;
+    iterator = registry().try_emplace(driverId).first;
+    iterator->second.latest = start.interactiveStart;
+    iterator->second.hasLatest = true;
+  }
   auto &state = iterator->second;
   state.destroyed = false;
-  const int32_t animationId = allocateAnimationId(state);
+  const int32_t animationId = allocateAnimationId();
   // Scalar velocity along the current-to-target trajectory; each channel is
   // seeded with velocity·displacement to match the iOS CASpringAnimation
   // per-keypath behavior.
@@ -760,7 +808,7 @@ int32_t animateSpring(
     active.springVelocity[index] =
         velocity * (targetChannels[index] - startChannels[index]);
   }
-  return startAnimation(driverId, state, std::move(active));
+  return startAnimation(driverId, state, std::move(active), start.startedAtHintS);
 }
 
 int32_t animateKeyframes(
@@ -772,10 +820,15 @@ int32_t animateKeyframes(
     int32_t reduceMotion) {
   if (!isOnMainThread()) return 0;
   auto iterator = registry().find(driverId);
-  if (iterator == registry().end()) return 0;
+  if (iterator == registry().end()) {
+    if (!start.hasInteractiveStart) return 0;
+    iterator = registry().try_emplace(driverId).first;
+    iterator->second.latest = start.interactiveStart;
+    iterator->second.hasLatest = true;
+  }
   auto &state = iterator->second;
   state.destroyed = false;
-  const int32_t animationId = allocateAnimationId(state);
+  const int32_t animationId = allocateAnimationId();
   const Presentation resolvedStart =
       prepareAnimation(driverId, state, start, presentation);
   if (shouldReduceMotion(reduceMotion) || durationMs <= 0 ||
@@ -787,18 +840,18 @@ int32_t animateKeyframes(
   ActiveAnimation active;
   active.id = animationId;
   active.kind = AnimationKind::Keyframes;
-  active.keyframes = std::move(keyframes);
+  active.keyframes.reset(std::move(keyframes));
   active.start = resolvedStart;
   active.target = presentation;
   active.durationS = durationMs / 1000.0;
-  return startAnimation(driverId, state, std::move(active));
+  return startAnimation(driverId, state, std::move(active), start.startedAtHintS);
 }
 
 int32_t rejectAnimation(uint64_t driverId) {
   if (!isOnMainThread()) return 0;
   auto iterator = registry().find(driverId);
   if (iterator == registry().end()) return 0;
-  const int32_t animationId = allocateAnimationId(iterator->second);
+  const int32_t animationId = allocateAnimationId();
   emitCompletion(driverId, animationId, false);
   return animationId;
 }
@@ -837,6 +890,11 @@ void destroyDriver(uint64_t driverId) {
   auto &state = iterator->second;
   state.ownership = Ownership::Interactive;
   finishActive(driverId, state, false);
+  // A destroyed driver's interaction history must not seed a revived
+  // incarnation: the revival seed would otherwise pair with these samples and
+  // refresh the staleness clock with motion no finger produced. (iOS clears
+  // its per-view histories at the same point.)
+  state.samples = VelocitySampleHistory{};
   if (state.views.empty()) {
     registry().erase(iterator);
   } else {
@@ -850,12 +908,6 @@ 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()
@@ -899,7 +951,8 @@ void registerViewAndroid(
     Presentation initialPresentation,
     double density,
     double hostWidthPx,
-    double hostHeightPx) {
+    double hostHeightPx,
+    bool lifecycleVisible) {
   auto &state = registry()[driverId];
   state.destroyed = false;
   if (!state.hasLatest) {
@@ -915,32 +968,24 @@ void registerViewAndroid(
       existing.density = density;
       existing.hostWidthPx = hostWidthPx;
       existing.hostHeightPx = hostHeightPx;
+      existing.lifecycleVisible = lifecycleVisible;
       deliverToView(existing, visible);
-      if (state.animation.has_value() && !state.animation->started &&
-          entryDisplayable(existing)) {
-        startLatchedAnimation(driverId, state);
-      }
+      reconcileViewDisplayability(driverId, state, existing);
       return;
     }
   }
   ViewEntry entry{
-      facebook::jni::make_global(view), density, hostWidthPx, hostHeightPx};
+      facebook::jni::make_global(view),
+      density,
+      hostWidthPx,
+      hostHeightPx,
+      lifecycleVisible,
+      ViewParticipation::Deferred};
   // `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);
-  }
+  reconcileViewDisplayability(driverId, state, state.views.back());
 }
 
 void setViewHostGeometryAndroid(
@@ -965,29 +1010,24 @@ 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);
-    }
+    reconcileViewDisplayability(driverId, state, entry);
     return;
   }
 }
 
-void viewBecameDisplayableAndroid(
+void setViewLifecycleVisibilityAndroid(
     uint64_t driverId,
-    alias_ref<JSmoothClipView> view) {
+    alias_ref<JSmoothClipView> view,
+    bool lifecycleVisible) {
   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);
-    }
+    entry.lifecycleVisible = lifecycleVisible;
+    reconcileViewDisplayability(driverId, state, entry);
     return;
   }
 }
@@ -999,9 +1039,12 @@ void unregisterViewAndroid(
   if (iterator == registry().end()) return;
   auto &state = iterator->second;
   bool removed = false;
+  bool removedParticipant = false;
   JNIEnv *env = facebook::jni::Environment::current();
   for (auto view_it = state.views.begin(); view_it != state.views.end();) {
     if (env->IsSameObject(view_it->view.get(), view.get())) {
+      removedParticipant = removedParticipant ||
+          view_it->participation != ViewParticipation::Deferred;
       view_it = state.views.erase(view_it);
       removed = true;
     } else {
@@ -1009,64 +1052,24 @@ void unregisterViewAndroid(
     }
   }
   if (removed && state.animation.has_value()) {
-    state.animation->finished = 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());
-      }
+    // Only a host that actually joined (or is unresolved after suspension)
+    // affects completion. A detached/unsized registration that stayed deferred
+    // never installed or rendered this animation.
+    if (removedParticipant) state.animation->finished = false;
+    if (!isOnMainThread()) {
+      // Blast-radius reduction, NOT a synchronization fix — be clear about
+      // which. Both call sites (SmoothClipViewManager.onAfterUpdateTransaction
+      // and onDropViewInstance) are Fabric mount operations, so this branch is
+      // unreachable in supported usage; the erase above and participant-based
+      // `finished` write are still unsynchronized if that ever stops holding. The erase
+      // cannot be skipped — dropping it would leak this view's global_ref for
+      // the process lifetime — but everything below can be, and should be: it
+      // mutates animatingDrivers(), the vector the choreographer callback walks
+      // on the main thread. Record the unfinished flag and leave the animation
+      // for the next main-thread event (attach, host geometry, destroy) to
+      // resolve.
+    } else {
+      relatchIfNoDisplayable(driverId, state);
     }
   }
   if (state.destroyed && state.views.empty()) {