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

package/README.md

@@ -198,6 +198,13 @@ const gesture = Gesture.Pan()
   `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
+  `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/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
@@ -457,17 +461,23 @@ Presentation prepareAnimation(
 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 = !state.views.empty();
   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.
+    return state.animation->id;
+  }
   auto &active = animatingDrivers();
   if (std::find(active.begin(), active.end(), driverId) == active.end()) {
     active.push_back(driverId);
@@ -652,7 +662,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 +705,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 +736,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) {
@@ -839,6 +849,9 @@ 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;
@@ -850,8 +863,27 @@ void registerViewAndroid(
   }
   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) {
+    // Start the latched animation: rebase the clock so the first frame
+    // integrates from now, not from the pre-mount animateTo call.
+    // 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();
+  }
 }
 
 void setViewHostGeometryAndroid(

package/ios/SmoothClipRegistry.mm

@@ -58,6 +58,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,7 +174,12 @@ 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];
@@ -224,9 +233,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
@@ -303,8 +319,10 @@ void registerView(
     state.latest = initialPresentation;
     state.hasLatest = true;
   }
+  const bool hasAnimation = state.animation.has_value();
+  const bool startsLatch = hasAnimation && !state.animation->started;
   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 +339,10 @@ void registerView(
     visible = reference != nil
         ? [reference smoothClipCurrentPresentation]
         : state.animation->start;
+  } else if (startsLatch) {
+    // 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,8 +350,16 @@ void registerView(
     state.views.push_back(key);
   }
   [view smoothClipApplyPresentation:visible];
-  if (!shouldReplay || !state.animation.has_value()) return;
+  if (startsLatch) {
+    // Start the latched animation: rebase the join clock before any elapsed
+    // math runs (dispatch below and the first-layout joinActiveAnimation).
+    state.animation->startedAt = CACurrentMediaTime();
+    state.animation->started = true;
+  }
+  if (!(shouldReplay || startsLatch)) return;
 
+  // The participant insert inside the join is also what keeps unregisterView
+  // orphan-safe for a mount-then-unmount before first layout.
   dispatchActiveAnimationJoin(state, view, key, visible);
 }
 
@@ -339,6 +369,10 @@ bool joinActiveAnimation(uint64_t driverId, SmoothClipView *view) {
   if (iterator == registry().end()) return false;
   auto &state = iterator->second;
   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()) {
@@ -500,10 +534,13 @@ int32_t animateTiming(
   active.durationMs = animation.durationMs;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
+  active.started = !state.views.empty();
   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 yet (animateTo raced the mount). Ownership stays
+    // Native — the pending animation owns rendering intent — and the first
+    // registerView rebases startedAt and starts it. The non-zero id is still
+    // returned synchronously so the JS side does not treat this as rejection.
     return animationId;
   }
 #if defined(SMOOTH_CLIP_ENABLE_SIGNPOSTS) && SMOOTH_CLIP_ENABLE_SIGNPOSTS
@@ -549,10 +586,10 @@ int32_t animateSpring(
   active.spring = animation;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
+  active.started = !state.views.empty();
   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 registerView — see animateTiming.
     return animationId;
   }
 #if defined(SMOOTH_CLIP_ENABLE_SIGNPOSTS) && SMOOTH_CLIP_ENABLE_SIGNPOSTS
@@ -600,10 +637,10 @@ int32_t animateKeyframes(
   active.durationMs = durationMs;
   active.startedAt = CACurrentMediaTime();
   active.participants.insert(state.views.begin(), state.views.end());
+  active.started = !state.views.empty();
   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 registerView — see animateTiming.
     return animationId;
   }
   for (const ViewKey key : state.views) {

package/package.json

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