react-native-smooth-clip-view 0.2.9 → 0.4.0

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

@@ -9,6 +9,7 @@
 #include <algorithm>
 #include <array>
 #include <atomic>
+#include <cassert>
 #include <chrono>
 #include <cmath>
 #include <limits>
@@ -26,8 +27,8 @@ using facebook::jni::alias_ref;
 using facebook::jni::global_ref;
 
 enum class Ownership { Interactive, Native };
-enum class AnimationKind { Timing, Spring, Keyframes };
-enum class ViewParticipation { Deferred, Active, Suspended };
+enum class AnimationKind { Timing, Spring };
+enum class ViewParticipation { Deferred, Active };
 
 // Load-bearing invariant, not just a convenience clock: advance()'s frame-clock
 // anchor compares this value ABSOLUTELY against a choreographer frame stamp
@@ -51,40 +52,35 @@ double nowSeconds() {
 
 struct ActiveAnimation {
   int32_t id = 0;
+  int32_t completionTag = 0;
   AnimationKind kind = AnimationKind::Timing;
   Presentation start{{0, 0, 0, 0, 0}, 0, 0};
   Presentation target{{0, 0, 0, 0, 0}, 0, 0};
   Presentation current{{0, 0, 0, 0, 0}, 0, 0};
   TimingAnimation timing{};
   SpringAnimation spring{};
-  // 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;
-  // Integrated spring state (channels: x, y, width, height, radius, tx, ty).
-  std::array<double, 7> springPosition{};
-  std::array<double, 7> springVelocity{};
+  // Integrated spring state. Shadow channels are skipped when neither endpoint
+  // has a visible shadow.
+  Channels springPosition{};
+  Channels springVelocity{};
+  std::size_t springChannelCount = kBaseChannelCount;
   double lastFrameS = 0;
-  bool finished = true;
-  // 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.
+  ScalarSpringState scalarSpring{0, 0};
+  // False only while a pre-ready animation waits for its first displayable
+  // host. Once started, host loss freezes the visible presentation.
   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 — except
-  // a start that carried the JS-captured Reanimated stamp, which arrives
+  // A start that carried the JS-captured Reanimated stamp arrives
   // pre-anchored (see startAnimation) and must not be min()'d again.
   bool frameClockAnchored = false;
 };
 
 // Per-view fanout state. Density and host metrics are pushed from Kotlin at
-// register time and on size/density changes; density 0 (not pushed yet) falls
-// back to DIP delivery through setClipPresentationDip.
+// register time and on size/density changes; density 0 falls back to DIP
+// delivery until physical host metrics arrive.
 struct ViewEntry {
   global_ref<JSmoothClipView> view;
   double density = 0;
@@ -104,6 +100,8 @@ struct DriverState {
   // replay, hosts mounted in another subtree). The entry is erased when the
   // last view leaves and revived by a take-ownership setPresentation.
   bool destroyed = false;
+  // Non-zero while this driver is an immutable member of one active group.
+  int32_t groupId = 0;
 
   // 'inherit' velocity samples; recording/coalescing/projection live in the
   // shared cpp/SmoothClipVelocityTracker.h (behavior-paired with iOS).
@@ -115,6 +113,34 @@ struct CompletionSink {
   CompletionCallback callback;
 };
 
+struct GroupCompletionSink {
+  const void *owner = nullptr;
+  GroupCompletionCallback callback;
+};
+
+struct GroupMemberAnimation {
+  uint64_t driverId = 0;
+  ActiveAnimation animation;
+};
+
+struct ActiveGroup {
+  uint64_t controllerId = 0;
+  int32_t id = 0;
+  int32_t completionTag = 0;
+  AnimationKind kind = AnimationKind::Timing;
+  TimingAnimation timing{};
+  SpringAnimation spring{};
+  ScalarSpringState scalarSpring{0, 0};
+  double durationS = 0;
+  double startedAtS = 0;
+  double lastFrameS = 0;
+  bool started = false;
+  bool frameClockAnchored = false;
+  std::vector<GroupMemberAnimation> members;
+};
+
+bool anyDisplayableView(const DriverState &state);
+
 std::unordered_map<uint64_t, DriverState> &registry() {
   static std::unordered_map<uint64_t, DriverState> value;
   return value;
@@ -125,6 +151,21 @@ CompletionSink &completionSink() {
   return sink;
 }
 
+GroupCompletionSink &groupCompletionSink() {
+  static GroupCompletionSink sink;
+  return sink;
+}
+
+std::unordered_map<int32_t, ActiveGroup> &groupRegistry() {
+  static std::unordered_map<int32_t, ActiveGroup> value;
+  return value;
+}
+
+std::vector<int32_t> &animatingGroups() {
+  static std::vector<int32_t> value;
+  return value;
+}
+
 // The sink is written from the JS thread (installBindings / invalidate) and
 // invoked on main. Invoking under the lock also keeps the owning bindings
 // state alive for the duration of the callback.
@@ -213,9 +254,16 @@ void scheduleFrame() {
 
 // --- Math (ported from SmoothClipRegistry.kt so both platforms match) -----
 //
-// 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.
+// clamp01, toChannels/fromChannels, interpolate, and the frame-clock anchor
+// live in cpp/SmoothClipAnimationCurve.h so a test binary can reach them
+// without linking fbjni; ios/tests pins their behavior.
+
+std::array<double, 11> velocityChannels(const Presentation &presentation) {
+  const Channels channels = toChannels(presentation);
+  std::array<double, 11> result{};
+  std::copy_n(channels.begin(), result.size(), result.begin());
+  return result;
+}
 
 // Springs settle below these per-channel thresholds (DIP and DIP/s).
 constexpr double kSpringSettleDisplacement = 0.05;
@@ -230,7 +278,9 @@ constexpr double kSpringMaxDurationS = 10.0;
 // stiffness/mass = 200k. Termination is settle-based: every channel must be
 // near its target and nearly stationary at the same time.
 bool advanceSpring(ActiveAnimation &animation, double now) {
-  const auto target = toChannels(animation.target);
+  const auto normalizedEndpoints = normalizeShadowEndpoints(
+      animation.start, animation.target);
+  const auto target = toChannels(normalizedEndpoints.second);
   double dt = now - animation.lastFrameS;
   animation.lastFrameS = now;
   if (dt < 0) dt = 0;
@@ -242,7 +292,7 @@ bool advanceSpring(ActiveAnimation &animation, double now) {
   while (dt > 0) {
     const double step = std::min(dt, kMaxStepS);
     dt -= step;
-    for (int index = 0; index < 7; index += 1) {
+    for (std::size_t index = 0; index < animation.springChannelCount; index += 1) {
       const double displacement =
           animation.springPosition[index] - target[index];
       const double acceleration =
@@ -254,7 +304,7 @@ bool advanceSpring(ActiveAnimation &animation, double now) {
     }
   }
   bool settled = true;
-  for (int index = 0; index < 7; index += 1) {
+  for (std::size_t index = 0; index < animation.springChannelCount; index += 1) {
     if (!std::isfinite(animation.springPosition[index]) ||
         !std::isfinite(animation.springVelocity[index])) {
       // A divergent configuration must never freeze the clip: end at target.
@@ -269,7 +319,14 @@ bool advanceSpring(ActiveAnimation &animation, double now) {
       settled = false;
     }
   }
-  animation.current = fromChannels(animation.springPosition);
+  animation.current = fromChannels(
+      animation.springPosition,
+      animation.start.clip.curve,
+      animation.start.shadow.enabled || animation.target.shadow.enabled);
+  if (!canonicalizePresentation(animation.current)) {
+    animation.current = animation.target;
+    return true;
+  }
   return settled || now - animation.startedAtS >= kSpringMaxDurationS;
 }
 
@@ -289,39 +346,109 @@ bool shouldReduceMotion(int32_t setting) {
 
 // --- State helpers --------------------------------------------------------
 
-void emitCompletion(uint64_t driverId, int32_t animationId, bool finished) {
+void emitCompletion(
+    uint64_t driverId,
+    int32_t animationId,
+    int32_t completionTag,
+    bool finished) {
   std::lock_guard<std::mutex> lock(completionSinkMutex());
   if (completionSink().callback) {
-    completionSink().callback(driverId, animationId, finished);
+    completionSink().callback(
+        driverId, animationId, completionTag, finished);
   }
 }
 
-// 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().
+void emitGroupCompletion(const ActiveGroup &group, bool finished) {
+  std::vector<DriverSnapshot> snapshots;
+  snapshots.reserve(group.members.size());
+  for (const GroupMemberAnimation &member : group.members) {
+    const auto iterator = registry().find(member.driverId);
+    if (iterator == registry().end() || iterator->second.destroyed) {
+      snapshots.push_back(
+          {member.driverId, unavailablePresentation(), false});
+    } else {
+      snapshots.push_back({
+          member.driverId,
+          iterator->second.latest,
+          anyDisplayableView(iterator->second),
+      });
+    }
+  }
+  std::lock_guard<std::mutex> lock(completionSinkMutex());
+  if (groupCompletionSink().callback) {
+    groupCompletionSink().callback(
+        group.controllerId,
+        group.id,
+        group.completionTag,
+        finished,
+        std::move(snapshots));
+  }
+}
+
+const GroupMemberAnimation *findGroupMember(
+    int32_t groupId,
+    uint64_t driverId) {
+  const auto groupIterator = groupRegistry().find(groupId);
+  if (groupIterator == groupRegistry().end()) return nullptr;
+  for (const GroupMemberAnimation &member : groupIterator->second.members) {
+    if (member.driverId == driverId) return &member;
+  }
+  return nullptr;
+}
+
+Presentation visiblePresentation(
+    uint64_t driverId,
+    const DriverState &state) {
+  if (state.groupId != 0) {
+    const GroupMemberAnimation *member =
+        findGroupMember(state.groupId, driverId);
+    if (member != nullptr) return member->animation.current;
+  }
+  return state.animation.has_value() ? state.animation->current : state.latest;
+}
+
+// Terminal per-frame delivery: scale canonical DIP geometry to pixels without
+// consulting host metrics. Each SmoothClipView applies the fixed viewport crop.
 void deliverToView(const ViewEntry &entry, const Presentation &presentation) {
   if (entry.density <= 0) {
     entry.view->applyClip(presentation);
     return;
   }
   const double density = entry.density;
-  NormalizedClip clip;
-  if (!SmoothClipNormalize(
+  CanonicalClip clip;
+  if (!SmoothClipCanonicalize(
           presentation.clip.x * density,
           presentation.clip.y * density,
           presentation.clip.width * density,
           presentation.clip.height * density,
           presentation.clip.radius * density,
-          entry.hostWidthPx,
-          entry.hostHeightPx,
+          presentation.clip.topLeftRadius * density,
+          presentation.clip.topRightRadius * density,
+          presentation.clip.bottomRightRadius * density,
+          presentation.clip.bottomLeftRadius * density,
+          presentation.clip.curve,
           clip)) {
     return;
   }
   const double translateX = presentation.contentTranslateX * density;
   const double translateY = presentation.contentTranslateY * density;
   // Atomic reject, mirroring the Kotlin DIP path's all-or-nothing gate.
-  if (!std::isfinite(translateX) || !std::isfinite(translateY)) return;
-  entry.view->applyClipPx(clip, translateX, translateY);
+  if (!std::isfinite(translateX) || !std::isfinite(translateY) ||
+      !std::isfinite(presentation.contentScale) ||
+      presentation.contentScale <= 0) {
+    return;
+  }
+  Shadow shadowPx = presentation.shadow;
+  shadowPx.offsetX *= density;
+  shadowPx.offsetY *= density;
+  shadowPx.blurRadius *= density;
+  shadowPx.spreadDistance *= density;
+  entry.view->applyClipPx(
+      clip,
+      translateX,
+      translateY,
+      presentation.contentScale,
+      shadowPx);
 }
 
 void applyToViews(DriverState &state, const Presentation &presentation) {
@@ -330,6 +457,22 @@ void applyToViews(DriverState &state, const Presentation &presentation) {
   }
 }
 
+void setAutonomousMotion(DriverState &state, bool active) {
+  for (const ViewEntry &entry : state.views) {
+    entry.view->setAutonomousMotion(active);
+  }
+}
+
+void applyAnimationFrameToViews(
+    DriverState &state,
+    const Presentation &presentation) {
+  for (const auto &entry : state.views) {
+    if (entry.participation == ViewParticipation::Active) {
+      deliverToView(entry, presentation);
+    }
+  }
+}
+
 void applyPresentation(DriverState &state, const Presentation &presentation) {
   state.latest = presentation;
   state.hasLatest = true;
@@ -346,6 +489,7 @@ std::vector<uint64_t> &animatingDrivers() {
 // visits animating drivers. Removal is eager: a stale id surviving a driver
 // erase/recreate cycle would let one frame integrate the animation twice.
 void clearActiveAnimation(uint64_t driverId, DriverState &state) {
+  setAutonomousMotion(state, false);
   state.animation.reset();
   for (ViewEntry &entry : state.views) {
     entry.participation = ViewParticipation::Deferred;
@@ -358,8 +502,9 @@ void clearActiveAnimation(uint64_t driverId, DriverState &state) {
 void finishActive(uint64_t driverId, DriverState &state, bool finished) {
   if (!state.animation.has_value()) return;
   const int32_t animationId = state.animation->id;
+  const int32_t completionTag = state.animation->completionTag;
   clearActiveAnimation(driverId, state);
-  emitCompletion(driverId, animationId, finished);
+  emitCompletion(driverId, animationId, completionTag, finished);
 }
 
 Presentation prepareAnimation(
@@ -369,8 +514,10 @@ Presentation prepareAnimation(
     Presentation target) {
   const Presentation visibleBefore =
       state.animation.has_value() ? state.animation->current : state.latest;
-  const bool acceptsInteractiveStart =
-      start.hasInteractiveStart && state.ownership == Ownership::Interactive;
+  // `from` is an explicit part of the replacement transaction and therefore
+  // overrides the sampled native frame even when the previous owner was a
+  // native animation/group.
+  const bool acceptsInteractiveStart = start.hasInteractiveStart;
   finishActive(driverId, state, false);
   const Presentation resolvedStart =
       acceptsInteractiveStart ? start.interactiveStart : visibleBefore;
@@ -399,16 +546,126 @@ bool anyDisplayableView(const DriverState &state) {
   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) {
+bool allGroupMembersReady(const ActiveGroup &group) {
+  for (const GroupMemberAnimation &member : group.members) {
+    const auto iterator = registry().find(member.driverId);
+    if (iterator == registry().end() || iterator->second.destroyed ||
+        !anyDisplayableView(iterator->second)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+void removeAnimatingGroup(int32_t groupId) {
+  auto &active = animatingGroups();
+  active.erase(std::remove(active.begin(), active.end(), groupId), active.end());
+}
+
+void applyGroupCurrent(const ActiveGroup &group) {
+  // Group readiness is the participation contract. Each controller owns one
+  // host, and host loss removes the group before another frame can advance.
+  for (const GroupMemberAnimation &member : group.members) {
+    const auto iterator = registry().find(member.driverId);
+    if (iterator != registry().end()) {
+      applyToViews(iterator->second, member.animation.current);
+    }
+  }
+}
+
+void startGroupFrameLoop(ActiveGroup &group) {
+  assert(group.started);
+  assert(allGroupMembersReady(group));
+  for (const GroupMemberAnimation &member : group.members) {
+    auto iterator = registry().find(member.driverId);
+    if (iterator != registry().end()) {
+      setAutonomousMotion(iterator->second, true);
+    }
+  }
+  auto &active = animatingGroups();
+  if (std::find(active.begin(), active.end(), group.id) == active.end()) {
+    active.push_back(group.id);
+  }
+  applyGroupCurrent(group);
+  scheduleFrame();
+}
+
+std::vector<DriverSnapshot> finishGroupImpl(
+    int32_t groupId,
+    bool useTarget,
+    bool finished) {
+  auto groupIterator = groupRegistry().find(groupId);
+  if (groupIterator == groupRegistry().end()) return {};
+  ActiveGroup group = std::move(groupIterator->second);
+  groupRegistry().erase(groupIterator);
+  removeAnimatingGroup(groupId);
+
+  std::vector<DriverSnapshot> snapshots;
+  snapshots.reserve(group.members.size());
+  for (GroupMemberAnimation &member : group.members) {
+    auto stateIterator = registry().find(member.driverId);
+    if (stateIterator == registry().end()) {
+      snapshots.push_back({member.driverId, unavailablePresentation(), false});
+      continue;
+    }
+    DriverState &state = stateIterator->second;
+    const Presentation result =
+        useTarget ? member.animation.target : member.animation.current;
+    state.groupId = 0;
+    state.latest = result;
+    state.hasLatest = true;
+    state.ownership = Ownership::Interactive;
+    setAutonomousMotion(state, false);
+    applyToViews(state, result);
+    snapshots.push_back(
+        {member.driverId, result, !state.destroyed && anyDisplayableView(state)});
+  }
+  emitGroupCompletion(group, finished);
+  return snapshots;
+}
+
+void startPendingGroup(ActiveGroup &group) {
+  const double now = nowSeconds();
+  group.started = true;
+  group.startedAtS = now;
+  group.lastFrameS = now;
+  group.frameClockAnchored = false;
+  for (GroupMemberAnimation &member : group.members) {
+    member.animation.startedAtS = now;
+    member.animation.lastFrameS = now;
+    member.animation.frameClockAnchored = false;
+  }
+  startGroupFrameLoop(group);
+}
+
+void reconcileGroupReadiness(uint64_t driverId) {
+  const auto stateIterator = registry().find(driverId);
+  if (stateIterator == registry().end() || stateIterator->second.groupId == 0) {
+    return;
+  }
+  const int32_t groupId = stateIterator->second.groupId;
+  auto groupIterator = groupRegistry().find(groupId);
+  if (groupIterator == groupRegistry().end()) {
+    stateIterator->second.groupId = 0;
+    return;
+  }
+  ActiveGroup &group = groupIterator->second;
+  const bool ready = allGroupMembersReady(group);
+  if (!group.started) {
+    if (ready) startPendingGroup(group);
+    return;
+  }
+  if (ready) return;
+  finishGroupImpl(groupId, false, false);
+}
+
+// Starts a pre-ready animation with its full duration, then joins the
+// choreographer loop.
+void startPendingAnimation(uint64_t driverId, DriverState &state) {
   auto &animation = *state.animation;
   animation.started = true;
   animation.startedAtS = nowSeconds();
   animation.lastFrameS = 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()) {
@@ -419,6 +676,7 @@ void startLatchedAnimation(uint64_t driverId, DriverState &state) {
       entry.participation = ViewParticipation::Active;
     }
   }
+  setAutonomousMotion(state, true);
   applyToViews(state, animation.start);
   scheduleFrame();
 }
@@ -434,16 +692,16 @@ int32_t startAnimation(
   // 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)
+  // a hint (NaN: unstamped 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,
+  // current = start while pre-ready is load-bearing: cancelAnimation,
   // beginInteraction, prepareAnimation's visibleBefore and registerView's
-  // visible all read animation->current, giving a never-rendered latch
+  // visible all read animation->current, giving a never-rendered pending-run
   // freeze-at-start / replace-from-start semantics with no extra branches.
   animation.current = animation.start;
   animation.started = anyDisplayableView(state);
@@ -454,9 +712,9 @@ int32_t startAnimation(
         : 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,
-    // host-geometry push, or window attach rebases the clock, joins
+    // No host can display yet (animateTo raced the mount, or the host is
+    // detached/unsized). The first displayable registration, host-geometry
+    // push, or window attach starts the full 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;
@@ -465,60 +723,23 @@ int32_t startAnimation(
   if (std::find(active.begin(), active.end(), driverId) == active.end()) {
     active.push_back(driverId);
   }
+  setAutonomousMotion(state, true);
   applyToViews(state, state.animation->start);
   scheduleFrame();
   return state.animation->id;
 }
 
-void relatchIfNoDisplayable(uint64_t driverId, DriverState &state) {
+void finishIfHostUnavailable(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());
+  const Presentation target = state.animation->target;
+  state.latest = target;
+  state.hasLatest = true;
+  state.ownership = Ownership::Interactive;
+  applyToViews(state, target);
+  finishActive(driverId, state, true);
 }
 
 void reconcileViewDisplayability(
@@ -527,7 +748,7 @@ void reconcileViewDisplayability(
     ViewEntry &entry) {
   if (!state.animation.has_value()) return;
   if (!state.animation->started) {
-    if (entryDisplayable(entry)) startLatchedAnimation(driverId, state);
+    if (entryDisplayable(entry)) startPendingAnimation(driverId, state);
     return;
   }
 
@@ -537,20 +758,20 @@ void reconcileViewDisplayability(
       deliverToView(entry, state.animation->current);
     }
   } else if (entry.participation == ViewParticipation::Active) {
-    entry.participation = ViewParticipation::Suspended;
+    entry.participation = ViewParticipation::Deferred;
   }
-  relatchIfNoDisplayable(driverId, state);
+  finishIfHostUnavailable(driverId, state);
 }
 
 void advance(uint64_t driverId, DriverState &state, double now) {
   ActiveAnimation &animation = *state.animation;
 
   if (!animation.frameClockAnchored) {
-    // This is the stamp-less/latch fallback. Worklet-issued animations carry
+    // This is the unstamped/pre-ready 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
+    // Here startedAtS/lastFrameS hold nowSeconds() sampled at native
     // 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.
@@ -574,44 +795,97 @@ void advance(uint64_t driverId, DriverState &state, double now) {
   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 =
         timingFraction(now, animation.startedAtS, animation.durationS);
-    if (animation.kind == AnimationKind::Keyframes) {
-      animation.current = animation.keyframes.evaluate(fraction);
-    } else {
-      const double eased = cubicBezier(
-          animation.timing.controlPoint1X,
-          animation.timing.controlPoint1Y,
-          animation.timing.controlPoint2X,
-          animation.timing.controlPoint2Y,
-          fraction);
-      animation.current = interpolate(animation.start, animation.target, eased);
+    const double eased = cubicBezier(
+        animation.timing.controlPoint1X,
+        animation.timing.controlPoint1Y,
+        animation.timing.controlPoint2X,
+        animation.timing.controlPoint2Y,
+        fraction);
+    animation.current = interpolate(animation.start, animation.target, eased);
+    const bool canonical = canonicalizePresentation(animation.current);
+    if (!canonical) {
+      animation.current = animation.target;
     }
-    done = fraction >= 1.0;
+    done = !canonical || fraction >= 1.0;
   }
   // The completion branch below fans out the exact target; applying the
   // integrated value too would double every JNI crossing on the final frame.
-  if (!done) applyToViews(state, animation.current);
+  if (!done) applyAnimationFrameToViews(state, animation.current);
 
   if (done) {
     const int32_t animationId = animation.id;
-    bool finished = animation.finished;
-    for (const ViewEntry &entry : state.views) {
-      if (entry.participation == ViewParticipation::Suspended) {
-        finished = false;
-        break;
-      }
-    }
+    const int32_t completionTag = animation.completionTag;
     const Presentation target = animation.target;
     clearActiveAnimation(driverId, state);
     state.latest = target;
     state.hasLatest = true;
     state.ownership = Ownership::Interactive;
     applyToViews(state, target);
-    emitCompletion(driverId, animationId, finished);
+    emitCompletion(driverId, animationId, completionTag, true);
+  }
+}
+
+void advanceGroup(int32_t groupId, ActiveGroup &group, double now) {
+  if (!group.frameClockAnchored) {
+    group.startedAtS = anchorStartTime(group.startedAtS, now);
+    group.lastFrameS = group.startedAtS;
+    group.frameClockAnchored = true;
+    for (GroupMemberAnimation &member : group.members) {
+      member.animation.startedAtS = group.startedAtS;
+      member.animation.lastFrameS = group.startedAtS;
+      member.animation.frameClockAnchored = true;
+    }
+  }
+
+  bool done = false;
+  if (group.kind == AnimationKind::Spring) {
+    const double deltaTime = now - group.lastFrameS;
+    group.lastFrameS = now;
+    group.scalarSpring = advanceScalarSpring(
+        group.scalarSpring, group.spring, deltaTime);
+    done = now - group.startedAtS >= kSpringMaxDurationS ||
+        relativeSpringEnergy(group.scalarSpring, group.spring) <=
+            group.spring.energyThreshold;
+    for (GroupMemberAnimation &member : group.members) {
+      member.animation.current = interpolate(
+          member.animation.start,
+          member.animation.target,
+          done ? 1.0 : group.scalarSpring.position);
+      if (!canonicalizePresentation(member.animation.current)) {
+        member.animation.current = member.animation.target;
+        done = true;
+      }
+    }
+  } else {
+    group.lastFrameS = now;
+    const double fraction =
+        timingFraction(now, group.startedAtS, group.durationS);
+    const double eased = cubicBezier(
+        group.timing.controlPoint1X,
+        group.timing.controlPoint1Y,
+        group.timing.controlPoint2X,
+        group.timing.controlPoint2Y,
+        fraction);
+    bool canonical = true;
+    for (GroupMemberAnimation &member : group.members) {
+      member.animation.lastFrameS = now;
+      member.animation.current = interpolate(
+          member.animation.start, member.animation.target, eased);
+      if (!canonicalizePresentation(member.animation.current)) {
+        member.animation.current = member.animation.target;
+        canonical = false;
+      }
+    }
+    done = !canonical || fraction >= 1.0;
+  }
+
+  if (done) {
+    finishGroupImpl(groupId, true, true);
+  } else {
+    applyGroupCurrent(group);
   }
 }
 
@@ -634,7 +908,14 @@ void onFrameImpl(double now) {
     }
     advance(driverId, iterator->second, now);
   }
-  if (!animatingDrivers().empty()) scheduleFrame();
+  static std::vector<int32_t> groupScratch;
+  groupScratch = animatingGroups();
+  for (const int32_t groupId : groupScratch) {
+    auto iterator = groupRegistry().find(groupId);
+    if (iterator == groupRegistry().end() || !iterator->second.started) continue;
+    advanceGroup(groupId, iterator->second, now);
+  }
+  if (!animatingDrivers().empty() || !animatingGroups().empty()) scheduleFrame();
 }
 
 } // namespace
@@ -673,6 +954,353 @@ void clearCompletionCallback(const void *owner) {
   completionSink().callback = nullptr;
 }
 
+void setGroupCompletionCallback(
+    const void *owner,
+    GroupCompletionCallback callback) {
+  std::lock_guard<std::mutex> lock(completionSinkMutex());
+  groupCompletionSink().owner = owner;
+  groupCompletionSink().callback = std::move(callback);
+}
+
+void clearGroupCompletionCallback(const void *owner) {
+  std::lock_guard<std::mutex> lock(completionSinkMutex());
+  if (groupCompletionSink().owner != owner) return;
+  groupCompletionSink().owner = nullptr;
+  groupCompletionSink().callback = nullptr;
+}
+
+Presentation snapshotCurrent(uint64_t driverId) {
+  if (!isOnMainThread()) return unavailablePresentation();
+  const auto iterator = registry().find(driverId);
+  if (iterator == registry().end() || iterator->second.destroyed ||
+      !iterator->second.hasLatest) {
+    return unavailablePresentation();
+  }
+  return visiblePresentation(driverId, iterator->second);
+}
+
+Presentation snapshotCurrentAndroid(uint64_t driverId) {
+  return snapshotCurrent(driverId);
+}
+
+std::vector<DriverSnapshot> snapshotGroup(
+    const std::vector<uint64_t> &driverIds) {
+  std::vector<DriverSnapshot> snapshots;
+  snapshots.reserve(driverIds.size());
+  if (!isOnMainThread()) return snapshots;
+  for (const uint64_t driverId : driverIds) {
+    const auto iterator = registry().find(driverId);
+    if (iterator == registry().end() || iterator->second.destroyed ||
+        !iterator->second.hasLatest) {
+      snapshots.push_back({driverId, unavailablePresentation(), false});
+      continue;
+    }
+    const DriverState &state = iterator->second;
+    snapshots.push_back(
+        {driverId, visiblePresentation(driverId, state),
+         anyDisplayableView(state)});
+  }
+  return snapshots;
+}
+
+std::vector<DriverSnapshot> beginGroupInteraction(
+    const std::vector<uint64_t> &driverIds) {
+  if (!isOnMainThread()) return {};
+  std::vector<uint64_t> unique;
+  unique.reserve(driverIds.size());
+  for (const uint64_t driverId : driverIds) {
+    if (driverId == 0 ||
+        std::find(unique.begin(), unique.end(), driverId) != unique.end()) {
+      return {};
+    }
+    const auto iterator = registry().find(driverId);
+    if (iterator == registry().end() || iterator->second.destroyed ||
+        !iterator->second.hasLatest) {
+      return snapshotGroup(driverIds);
+    }
+    unique.push_back(driverId);
+  }
+
+  std::vector<int32_t> groupsToCancel;
+  for (const uint64_t driverId : driverIds) {
+    const int32_t groupId = registry().at(driverId).groupId;
+    if (groupId != 0 &&
+        std::find(groupsToCancel.begin(), groupsToCancel.end(), groupId) ==
+            groupsToCancel.end()) {
+      groupsToCancel.push_back(groupId);
+    }
+  }
+  for (const int32_t groupId : groupsToCancel) {
+    finishGroupImpl(groupId, false, false);
+  }
+  for (const uint64_t driverId : driverIds) {
+    DriverState &state = registry().at(driverId);
+    if (state.animation.has_value()) {
+      const int32_t animationId = state.animation->id;
+      const int32_t completionTag = state.animation->completionTag;
+      const Presentation current = state.animation->current;
+      clearActiveAnimation(driverId, state);
+      state.latest = current;
+      state.hasLatest = true;
+      applyToViews(state, current);
+      emitCompletion(driverId, animationId, completionTag, false);
+    }
+    state.ownership = Ownership::Interactive;
+  }
+  return snapshotGroup(driverIds);
+}
+
+bool setPresentationBatch(const std::vector<BatchEntry> &entries) {
+  if (!isOnMainThread() || entries.empty()) return false;
+  std::vector<BatchEntry> canonicalEntries = entries;
+  for (BatchEntry &entry : canonicalEntries) {
+    if (!canonicalizePresentation(entry.presentation)) return false;
+  }
+  std::vector<uint64_t> unique;
+  std::vector<int32_t> groupsToCancel;
+  unique.reserve(entries.size());
+  for (const BatchEntry &entry : canonicalEntries) {
+    if (entry.driverId == 0 ||
+        std::find(unique.begin(), unique.end(), entry.driverId) != unique.end()) {
+      return false;
+    }
+    const auto iterator = registry().find(entry.driverId);
+    if (iterator == registry().end() || iterator->second.destroyed ||
+        !isFinitePresentation(entry.presentation)) {
+      return false;
+    }
+    if (iterator != registry().end() && iterator->second.groupId != 0 &&
+        std::find(
+            groupsToCancel.begin(),
+            groupsToCancel.end(),
+            iterator->second.groupId) == groupsToCancel.end()) {
+      groupsToCancel.push_back(iterator->second.groupId);
+    }
+    unique.push_back(entry.driverId);
+  }
+
+  // Replacement is all-or-nothing: validation above is deliberately complete
+  // before any old group is dissolved. An overlap dissolves the whole immutable
+  // old group (including members absent from this batch) exactly once.
+  for (const int32_t groupId : groupsToCancel) {
+    finishGroupImpl(groupId, false, false);
+  }
+
+  const double now = nowSeconds();
+  for (const BatchEntry &entry : canonicalEntries) {
+    DriverState &state = registry().at(entry.driverId);
+    state.destroyed = false;
+    finishActive(entry.driverId, state, false);
+    state.latest = entry.presentation;
+    state.hasLatest = true;
+    state.ownership = Ownership::Interactive;
+    recordVelocitySample(
+        state.samples, velocityChannels(entry.presentation), now);
+  }
+  for (const BatchEntry &entry : canonicalEntries) {
+    applyToViews(registry().at(entry.driverId), entry.presentation);
+  }
+  return true;
+}
+
+namespace {
+
+int32_t startGroupCommon(
+    uint64_t controllerId,
+    std::vector<GroupMotionEntry> entries,
+    AnimationKind kind,
+    TimingAnimation timing,
+    SpringAnimation spring,
+    double durationMs,
+    int32_t reduceMotion,
+    int32_t completionTag,
+    double startedAtHintS) {
+  if (!isOnMainThread() || controllerId == 0 || entries.empty()) {
+    return 0;
+  }
+  for (GroupMotionEntry &entry : entries) {
+    if ((entry.hasFrom && !canonicalizePresentation(entry.from)) ||
+        !canonicalizePresentation(entry.target)) {
+      return 0;
+    }
+  }
+  if (kind == AnimationKind::Timing &&
+      !isValidTiming(timing)) {
+    return 0;
+  }
+  if (kind == AnimationKind::Spring &&
+      (!isValidSpring(spring) || spring.inheritVelocity)) {
+    return 0;
+  }
+  const bool reduce = shouldReduceMotion(reduceMotion) ||
+      (kind != AnimationKind::Spring && durationMs <= 0);
+  std::vector<uint64_t> unique;
+  std::vector<int32_t> groupsToCancel;
+  std::vector<Presentation> resolvedStarts;
+  unique.reserve(entries.size());
+  resolvedStarts.reserve(entries.size());
+  for (const GroupMotionEntry &entry : entries) {
+    if (entry.driverId == 0 ||
+        std::find(unique.begin(), unique.end(), entry.driverId) != unique.end()) {
+      return 0;
+    }
+    const auto iterator = registry().find(entry.driverId);
+    if ((iterator == registry().end() || iterator->second.destroyed ||
+         !iterator->second.hasLatest) && !entry.hasFrom) {
+      return 0;
+    }
+    if (iterator != registry().end() && iterator->second.groupId != 0 &&
+        std::find(
+            groupsToCancel.begin(),
+            groupsToCancel.end(),
+            iterator->second.groupId) == groupsToCancel.end()) {
+      groupsToCancel.push_back(iterator->second.groupId);
+    }
+    const Presentation resolvedStart = entry.hasFrom
+        ? entry.from
+        : visiblePresentation(entry.driverId, iterator->second);
+    if (!isFinitePresentation(resolvedStart) ||
+        !isFinitePresentation(entry.target) ||
+        !isAutonomousUniformCircular(resolvedStart) ||
+        !isAutonomousUniformCircular(entry.target)) {
+      return 0;
+    }
+    if (kind == AnimationKind::Spring) {
+      const double velocity = spring.initialVelocity;
+      if (!springScaleStaysPositive(
+              resolvedStart, entry.target, spring, velocity)) {
+        return 0;
+      }
+    }
+    resolvedStarts.push_back(resolvedStart);
+    unique.push_back(entry.driverId);
+  }
+
+  // Capture every implicit start above, while overlapped groups still own
+  // their current frames. Only after full preflight may replacement dissolve
+  // those immutable groups and emit one unfinished completion for each.
+  for (const int32_t groupId : groupsToCancel) {
+    finishGroupImpl(groupId, false, false);
+  }
+
+  ActiveGroup group;
+  group.controllerId = controllerId;
+  group.id = allocateAnimationId();
+  group.completionTag = completionTag;
+  group.kind = kind;
+  group.timing = timing;
+  group.spring = spring;
+  group.scalarSpring = {0, spring.initialVelocity};
+  group.durationS = durationMs / 1000.0;
+  group.members.reserve(entries.size());
+  const double wallNow = nowSeconds();
+
+  for (std::size_t entryIndex = 0; entryIndex < entries.size(); entryIndex += 1) {
+    GroupMotionEntry &entry = entries[entryIndex];
+    DriverState &state = registry()[entry.driverId];
+    const Presentation resolvedStart = resolvedStarts[entryIndex];
+    finishActive(entry.driverId, state, false);
+    state.destroyed = false;
+    state.latest = entry.target;
+    state.hasLatest = true;
+    state.ownership = Ownership::Native;
+    state.groupId = group.id;
+
+    GroupMemberAnimation member;
+    member.driverId = entry.driverId;
+    member.animation.id = group.id;
+    member.animation.kind = kind;
+    member.animation.start = resolvedStart;
+    member.animation.target = entry.target;
+    member.animation.current = resolvedStart;
+    member.animation.timing = timing;
+    member.animation.spring = spring;
+    member.animation.durationS = group.durationS;
+    group.members.push_back(std::move(member));
+  }
+
+  // Apply every explicit start after the whole participant set has passed
+  // preflight and acquired the new immutable group id. This remains one
+  // synchronous main-thread transaction even when the initial readiness
+  // barrier is pending; ready hosts must not keep displaying their old frame
+  // while snapshots already report `from`.
+  for (std::size_t entryIndex = 0; entryIndex < entries.size(); entryIndex += 1) {
+    if (!entries[entryIndex].hasFrom) continue;
+    applyToViews(
+        registry().at(entries[entryIndex].driverId),
+        resolvedStarts[entryIndex]);
+  }
+
+  const int32_t groupId = group.id;
+  const StartStamp stamp = resolveStartStamp(startedAtHintS, wallNow);
+  group.startedAtS = stamp.startedAtS;
+  group.lastFrameS = stamp.startedAtS;
+  group.frameClockAnchored = stamp.frameClockAnchored;
+  for (GroupMemberAnimation &member : group.members) {
+    member.animation.startedAtS = stamp.startedAtS;
+    member.animation.lastFrameS = stamp.startedAtS;
+    member.animation.frameClockAnchored = stamp.frameClockAnchored;
+  }
+  group.started = allGroupMembersReady(group);
+  groupRegistry().emplace(groupId, std::move(group));
+  if (reduce) {
+    finishGroupImpl(groupId, true, true);
+    return groupId;
+  }
+  ActiveGroup &stored = groupRegistry().at(groupId);
+  if (stored.started) {
+    startGroupFrameLoop(stored);
+  }
+  return groupId;
+}
+
+} // namespace
+
+int32_t animateTimingGroup(
+    uint64_t controllerId,
+    std::vector<GroupMotionEntry> entries,
+    TimingAnimation animation,
+    int32_t completionTag,
+    double startedAtHintS) {
+  return startGroupCommon(
+      controllerId,
+      std::move(entries),
+      AnimationKind::Timing,
+      animation,
+      {},
+      animation.durationMs,
+      animation.reduceMotion,
+      completionTag,
+      startedAtHintS);
+}
+
+int32_t animateSpringGroup(
+    uint64_t controllerId,
+    std::vector<GroupMotionEntry> entries,
+    SpringAnimation animation,
+    int32_t completionTag,
+    double startedAtHintS) {
+  return startGroupCommon(
+      controllerId,
+      std::move(entries),
+      AnimationKind::Spring,
+      {},
+      animation,
+      kSpringMaxDurationS * 1000.0,
+      animation.reduceMotion,
+      completionTag,
+      startedAtHintS);
+}
+
+std::vector<DriverSnapshot> cancelAnimationGroup(
+    int32_t groupId,
+    GroupCancelBehavior behavior) {
+  if (!isOnMainThread()) return {};
+  const bool finish = behavior == GroupCancelBehavior::Finish;
+  return finishGroupImpl(
+      groupId, finish, finish);
+}
+
 void setPresentation(
     uint64_t driverId,
     Presentation presentation,
@@ -680,6 +1308,7 @@ void setPresentation(
     bool overridePendingAnimation,
     bool recordVelocity) {
   if (!isOnMainThread()) return;
+  if (!canonicalizePresentation(presentation)) return;
   SMOOTH_CLIP_TRACE("SmoothClip.setPresentation");
   auto iterator = registry().find(driverId);
   if (!takeOwnership) {
@@ -692,12 +1321,16 @@ void setPresentation(
     iterator = registry().try_emplace(driverId).first;
   }
   auto &state = iterator->second;
+  if (state.groupId != 0) {
+    if (!takeOwnership) return;
+    finishGroupImpl(state.groupId, false, false);
+  }
   if (!takeOwnership && state.ownership != Ownership::Interactive) return;
   if (takeOwnership) {
     state.destroyed = false;
     // 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.
+    // authoritative start and explicitly cancels the pending run.
     if (state.animation.has_value() && !state.animation->started &&
         !overridePendingAnimation) {
       return;
@@ -708,7 +1341,8 @@ void setPresentation(
   state.hasLatest = true;
   state.ownership = Ownership::Interactive;
   if (recordVelocity) {
-    recordVelocitySample(state.samples, toChannels(presentation), nowSeconds());
+    recordVelocitySample(
+        state.samples, velocityChannels(presentation), nowSeconds());
   } else if (state.samples.hasLatest) {
     // Untracked movement invalidates the recorded velocity pair.
     clearVelocitySamples(state.samples);
@@ -721,12 +1355,16 @@ Presentation beginInteraction(uint64_t driverId) {
   auto iterator = registry().find(driverId);
   if (iterator == registry().end()) return unavailablePresentation();
   auto &state = iterator->second;
+  if (state.groupId != 0) {
+    finishGroupImpl(state.groupId, false, false);
+  }
   state.destroyed = false;
   if (!state.animation.has_value()) {
     state.ownership = Ownership::Interactive;
     return state.latest;
   }
   const int32_t animationId = state.animation->id;
+  const int32_t completionTag = state.animation->completionTag;
   const Presentation current = state.animation->current;
   clearActiveAnimation(driverId, state);
   state.latest = current;
@@ -735,7 +1373,7 @@ Presentation beginInteraction(uint64_t driverId) {
   // 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);
+  emitCompletion(driverId, animationId, completionTag, false);
   return current;
 }
 
@@ -743,27 +1381,57 @@ int32_t animateTiming(
     uint64_t driverId,
     AnimationStart start,
     Presentation presentation,
-    TimingAnimation animation) {
-  if (!isOnMainThread()) return 0;
+    TimingAnimation animation,
+    int32_t completionTag) {
+  const bool validAnimation = isValidTiming(animation);
+  if (!canonicalizePresentation(presentation) ||
+      (start.hasInteractiveStart &&
+       !canonicalizePresentation(start.interactiveStart))) {
+    return 0;
+  }
+  if (!isOnMainThread() || driverId == 0 ||
+      !isFinitePresentation(presentation) || !validAnimation) {
+    return 0;
+  }
   auto iterator = registry().find(driverId);
+  Presentation preflightStart;
+  if (iterator == registry().end()) {
+    if (!start.hasInteractiveStart ||
+        !isFinitePresentation(start.interactiveStart)) {
+      return 0;
+    }
+    preflightStart = start.interactiveStart;
+  } else {
+    if (iterator->second.destroyed && !start.hasInteractiveStart) return 0;
+    preflightStart = start.hasInteractiveStart
+        ? start.interactiveStart
+        : visiblePresentation(driverId, iterator->second);
+  }
+  if (!isFinitePresentation(preflightStart) ||
+      preflightStart.clip.curve != presentation.clip.curve) {
+    return 0;
+  }
+  const bool reduce = shouldReduceMotion(animation.reduceMotion) ||
+      animation.durationMs <= 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;
+  if (state.groupId != 0) finishGroupImpl(state.groupId, false, false);
   state.destroyed = false;
   const int32_t animationId = allocateAnimationId();
   const Presentation resolvedStart =
       prepareAnimation(driverId, state, start, presentation);
-  if (shouldReduceMotion(animation.reduceMotion) || animation.durationMs <= 0) {
+  if (reduce) {
     applyPresentation(state, presentation);
-    emitCompletion(driverId, animationId, true);
+    emitCompletion(driverId, animationId, completionTag, true);
     return animationId;
   }
   ActiveAnimation active;
   active.id = animationId;
+  active.completionTag = completionTag;
   active.kind = AnimationKind::Timing;
   active.timing = animation;
   active.start = resolvedStart;
@@ -776,33 +1444,67 @@ int32_t animateSpring(
     uint64_t driverId,
     AnimationStart start,
     Presentation presentation,
-    SpringAnimation animation) {
-  if (!isOnMainThread()) return 0;
+    SpringAnimation animation,
+    int32_t completionTag) {
+  const bool validAnimation = isValidSpring(animation);
+  if (!canonicalizePresentation(presentation) ||
+      (start.hasInteractiveStart &&
+       !canonicalizePresentation(start.interactiveStart))) {
+    return 0;
+  }
+  if (!isOnMainThread() || driverId == 0 ||
+      !isFinitePresentation(presentation) || !validAnimation) {
+    return 0;
+  }
   auto iterator = registry().find(driverId);
+  Presentation preflightStart;
+  if (iterator == registry().end()) {
+    if (!start.hasInteractiveStart ||
+        !isFinitePresentation(start.interactiveStart)) {
+      return 0;
+    }
+    preflightStart = start.interactiveStart;
+  } else {
+    if (iterator->second.destroyed && !start.hasInteractiveStart) return 0;
+    preflightStart = start.hasInteractiveStart
+        ? start.interactiveStart
+        : visiblePresentation(driverId, iterator->second);
+  }
+  const double velocity = animation.inheritVelocity &&
+          iterator != registry().end()
+      ? inheritedVelocity(
+            iterator->second.samples,
+            velocityChannels(presentation),
+            nowSeconds())
+      : animation.initialVelocity;
+  if (!isFinitePresentation(preflightStart) ||
+      preflightStart.clip.curve != presentation.clip.curve ||
+      !springScaleStaysPositive(
+          preflightStart, presentation, animation, velocity)) {
+    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;
+  if (state.groupId != 0) finishGroupImpl(state.groupId, false, false);
   state.destroyed = false;
   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.
-  const double velocity = animation.inheritVelocity
-      ? inheritedVelocity(state.samples, toChannels(presentation), nowSeconds())
-      : animation.initialVelocity;
   const Presentation resolvedStart =
       prepareAnimation(driverId, state, start, presentation);
   if (shouldReduceMotion(animation.reduceMotion)) {
     applyPresentation(state, presentation);
-    emitCompletion(driverId, animationId, true);
+    emitCompletion(driverId, animationId, completionTag, true);
     return animationId;
   }
   ActiveAnimation active;
   active.id = animationId;
+  active.completionTag = completionTag;
   active.kind = AnimationKind::Spring;
   active.spring = animation;
   active.spring.initialVelocity = velocity;
@@ -810,58 +1512,31 @@ int32_t animateSpring(
   active.start = resolvedStart;
   active.target = presentation;
   active.durationS = kSpringMaxDurationS;
-  const auto startChannels = toChannels(resolvedStart);
-  const auto targetChannels = toChannels(presentation);
-  for (int index = 0; index < 7; index += 1) {
-    active.springPosition[index] = startChannels[index];
+  const auto normalizedEndpoints = normalizeShadowEndpoints(
+      resolvedStart, presentation);
+  const auto startChannels = toChannels(normalizedEndpoints.first);
+  const auto targetChannels = toChannels(normalizedEndpoints.second);
+  active.springChannelCount =
+      (resolvedStart.shadow.enabled && resolvedStart.shadow.alpha > 0) ||
+          (presentation.shadow.enabled && presentation.shadow.alpha > 0)
+      ? kChannelCount
+      : kBaseChannelCount;
+  active.springPosition = startChannels;
+  for (std::size_t index = 0;
+       index < active.springChannelCount;
+       index += 1) {
     active.springVelocity[index] =
         velocity * (targetChannels[index] - startChannels[index]);
   }
   return startAnimation(driverId, state, std::move(active), start.startedAtHintS);
 }
 
-int32_t animateKeyframes(
-    uint64_t driverId,
-    AnimationStart start,
-    Presentation presentation,
-    double durationMs,
-    std::vector<Keyframe> keyframes,
-    int32_t reduceMotion) {
-  if (!isOnMainThread()) return 0;
-  auto iterator = registry().find(driverId);
-  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();
-  const Presentation resolvedStart =
-      prepareAnimation(driverId, state, start, presentation);
-  if (shouldReduceMotion(reduceMotion) || durationMs <= 0 ||
-      keyframes.size() < 2) {
-    applyPresentation(state, presentation);
-    emitCompletion(driverId, animationId, true);
-    return animationId;
-  }
-  ActiveAnimation active;
-  active.id = animationId;
-  active.kind = AnimationKind::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), 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();
-  emitCompletion(driverId, animationId, false);
+  emitCompletion(driverId, animationId, 0, false);
   return animationId;
 }
 
@@ -875,6 +1550,18 @@ CancelResult cancelAnimation(
     return {false, {{0, 0, 0, 0, 0}, 0, 0}};
   }
   auto &state = iterator->second;
+  if (state.groupId != 0) {
+    const int32_t activeGroupId = state.groupId;
+    if (animationId > 0 && animationId != activeGroupId) {
+      return {false, visiblePresentation(driverId, state)};
+    }
+    const std::vector<DriverSnapshot> snapshots =
+        finishGroupImpl(activeGroupId, useTarget, false);
+    for (const DriverSnapshot &snapshot : snapshots) {
+      if (snapshot.driverId == driverId) return {true, snapshot.presentation};
+    }
+    return {false, unavailablePresentation()};
+  }
   if (!state.animation.has_value() ||
       (animationId > 0 && animationId != state.animation->id)) {
     return {false, state.animation.has_value() ? state.animation->current
@@ -883,12 +1570,13 @@ CancelResult cancelAnimation(
   const Presentation result =
       useTarget ? state.animation->target : state.animation->current;
   const int32_t activeId = state.animation->id;
+  const int32_t completionTag = state.animation->completionTag;
   clearActiveAnimation(driverId, state);
   state.latest = result;
   state.hasLatest = true;
   state.ownership = Ownership::Interactive;
   applyToViews(state, result);
-  emitCompletion(driverId, activeId, false);
+  emitCompletion(driverId, activeId, completionTag, false);
   return {true, result};
 }
 
@@ -897,6 +1585,7 @@ void destroyDriver(uint64_t driverId) {
   auto iterator = registry().find(driverId);
   if (iterator == registry().end()) return;
   auto &state = iterator->second;
+  if (state.groupId != 0) finishGroupImpl(state.groupId, false, false);
   state.ownership = Ownership::Interactive;
   finishActive(driverId, state, false);
   // A destroyed driver's interaction history must not seed a revived
@@ -921,37 +1610,115 @@ void JSmoothClipView::applyClip(const Presentation &presentation) const {
   static const auto method =
       javaClassStatic()
           ->getMethod<void(
-              jdouble, jdouble, jdouble, jdouble, jdouble, jdouble, jdouble)>(
-              "setClipPresentationDip");
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jint,
+              jdouble,
+              jdouble,
+              jdouble,
+              jboolean,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble,
+              jdouble)>("setClipPresentationDip");
   method(
       self(),
       presentation.clip.x,
       presentation.clip.y,
       presentation.clip.width,
       presentation.clip.height,
-      presentation.clip.radius,
+      SmoothClipResolvedRadius(
+          presentation.clip.topLeftRadius, presentation.clip.radius),
+      SmoothClipResolvedRadius(
+          presentation.clip.topRightRadius, presentation.clip.radius),
+      SmoothClipResolvedRadius(
+          presentation.clip.bottomRightRadius, presentation.clip.radius),
+      SmoothClipResolvedRadius(
+          presentation.clip.bottomLeftRadius, presentation.clip.radius),
+      static_cast<jint>(presentation.clip.curve),
       presentation.contentTranslateX,
-      presentation.contentTranslateY);
+      presentation.contentTranslateY,
+      presentation.contentScale,
+      presentation.shadow.enabled,
+      presentation.shadow.red,
+      presentation.shadow.green,
+      presentation.shadow.blue,
+      presentation.shadow.alpha,
+      presentation.shadow.offsetX,
+      presentation.shadow.offsetY,
+      presentation.shadow.blurRadius,
+      presentation.shadow.spreadDistance);
 }
 
 void JSmoothClipView::applyClipPx(
-    const NormalizedClip &clip,
+    const CanonicalClip &clip,
     double contentTranslateXPx,
-    double contentTranslateYPx) const {
+    double contentTranslateYPx,
+    double contentScale,
+    const Shadow &shadowPx) const {
   static const auto method =
       javaClassStatic()
           ->getMethod<void(
-              jfloat, jfloat, jfloat, jfloat, jfloat, jfloat, jfloat)>(
-              "setClipPresentationPx");
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jint,
+              jfloat,
+              jfloat,
+              jfloat,
+              jboolean,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat,
+              jfloat)>("setClipPresentationPx");
   method(
       self(),
       static_cast<jfloat>(clip.left),
       static_cast<jfloat>(clip.top),
       static_cast<jfloat>(clip.right),
       static_cast<jfloat>(clip.bottom),
-      static_cast<jfloat>(clip.radius),
+      static_cast<jfloat>(clip.topLeftRadius),
+      static_cast<jfloat>(clip.topRightRadius),
+      static_cast<jfloat>(clip.bottomRightRadius),
+      static_cast<jfloat>(clip.bottomLeftRadius),
+      static_cast<jint>(clip.curve),
       static_cast<jfloat>(contentTranslateXPx),
-      static_cast<jfloat>(contentTranslateYPx));
+      static_cast<jfloat>(contentTranslateYPx),
+      static_cast<jfloat>(contentScale),
+      shadowPx.enabled,
+      static_cast<jfloat>(shadowPx.red),
+      static_cast<jfloat>(shadowPx.green),
+      static_cast<jfloat>(shadowPx.blue),
+      static_cast<jfloat>(shadowPx.alpha),
+      static_cast<jfloat>(shadowPx.offsetX),
+      static_cast<jfloat>(shadowPx.offsetY),
+      static_cast<jfloat>(shadowPx.blurRadius),
+      static_cast<jfloat>(shadowPx.spreadDistance));
+}
+
+void JSmoothClipView::setAutonomousMotion(bool active) const {
+  static const auto method =
+      javaClassStatic()->getMethod<void(jboolean)>("setAutonomousMotion");
+  method(self(), active);
 }
 
 void registerViewAndroid(
@@ -962,15 +1729,14 @@ void registerViewAndroid(
     double hostWidthPx,
     double hostHeightPx,
     bool lifecycleVisible) {
+  if (!canonicalizePresentation(initialPresentation)) return;
   auto &state = registry()[driverId];
   state.destroyed = false;
   if (!state.hasLatest) {
     state.latest = initialPresentation;
     state.hasLatest = true;
   }
-  const Presentation visible = state.animation.has_value()
-      ? state.animation->current
-      : state.latest;
+  const Presentation visible = visiblePresentation(driverId, state);
   JNIEnv *env = facebook::jni::Environment::current();
   for (auto &existing : state.views) {
     if (env->IsSameObject(existing.view.get(), view.get())) {
@@ -980,9 +1746,14 @@ void registerViewAndroid(
       existing.lifecycleVisible = lifecycleVisible;
       deliverToView(existing, visible);
       reconcileViewDisplayability(driverId, state, existing);
+      reconcileGroupReadiness(driverId);
       return;
     }
   }
+  // The public controller contract permits one simultaneous host. The React
+  // wrapper reports this as a development error; native also refuses a second
+  // host so release behavior cannot silently fan one controller out.
+  if (!state.views.empty()) return;
   ViewEntry entry{
       facebook::jni::make_global(view),
       density,
@@ -990,11 +1761,11 @@ void registerViewAndroid(
       hostHeightPx,
       lifecycleVisible,
       ViewParticipation::Deferred};
-  // `visible` above already delivered animation->current (= start) to the
-  // registering view — the correct first frame for a latched animation.
+  // `visible` already contains the start of a pre-ready animation.
   deliverToView(entry, visible);
   state.views.push_back(std::move(entry));
   reconcileViewDisplayability(driverId, state, state.views.back());
+  reconcileGroupReadiness(driverId);
 }
 
 void setViewHostGeometryAndroid(
@@ -1014,12 +1785,10 @@ void setViewHostGeometryAndroid(
     entry.hostWidthPx = hostWidthPx;
     entry.hostHeightPx = hostHeightPx;
     if (state.hasLatest) {
-      deliverToView(
-          entry,
-          state.animation.has_value() ? state.animation->current
-                                      : state.latest);
+      deliverToView(entry, visiblePresentation(driverId, state));
     }
     reconcileViewDisplayability(driverId, state, entry);
+    reconcileGroupReadiness(driverId);
     return;
   }
 }
@@ -1037,6 +1806,7 @@ void setViewLifecycleVisibilityAndroid(
     if (!env->IsSameObject(entry.view.get(), view.get())) continue;
     entry.lifecycleVisible = lifecycleVisible;
     reconcileViewDisplayability(driverId, state, entry);
+    reconcileGroupReadiness(driverId);
     return;
   }
 }
@@ -1048,12 +1818,9 @@ 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 {
@@ -1061,10 +1828,6 @@ void unregisterViewAndroid(
     }
   }
   if (removed && state.animation.has_value()) {
-    // 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
@@ -1078,9 +1841,12 @@ void unregisterViewAndroid(
       // for the next main-thread event (attach, host geometry, destroy) to
       // resolve.
     } else {
-      relatchIfNoDisplayable(driverId, state);
+      finishIfHostUnavailable(driverId, state);
     }
   }
+  if (removed && state.groupId != 0 && isOnMainThread()) {
+    reconcileGroupReadiness(driverId);
+  }
   if (state.destroyed && state.views.empty()) {
     registry().erase(iterator);
   }