react-native-smooth-clip-view 0.4.6 → 0.5.0

package/ios/SmoothClipBackdropView.mm

@@ -0,0 +1,267 @@
+#import "SmoothClipBackdropView.h"
+
+#import "SmoothClipViewRegistry.h"
+
+#include "SmoothClipAnimationCurve.h"
+
+#import <QuartzCore/QuartzCore.h>
+#import <React/RCTFabricComponentsPlugins.h>
+#import <react/renderer/components/SmoothClipViewSpec/ComponentDescriptors.h>
+#import <react/renderer/components/SmoothClipViewSpec/Props.h>
+#import <react/renderer/components/SmoothClipViewSpec/RCTComponentViewHelpers.h>
+
+#include <algorithm>
+#include <cmath>
+
+using namespace facebook::react;
+
+static NSString *const kSmoothClipBackdropAnimationKey = @"smoothClip.backdrop";
+
+@interface SmoothClipBackdropContentView : UIView
+@end
+
+@implementation SmoothClipBackdropContentView
+
+- (id<CAAction>)actionForLayer:(CALayer *)layer forKey:(NSString *)event {
+  // The registry drives the translation explicitly, by a model write or by
+  // the animations installed below; no implicit action per frame.
+  return (id<CAAction>)[NSNull null];
+}
+
+@end
+
+@implementation SmoothClipBackdropView {
+  SmoothClipBackdropContentView *_content;
+  uint64_t _driverId;
+  CGPoint _translation;
+  BOOL _animating;
+}
+
++ (ComponentDescriptorProvider)componentDescriptorProvider {
+  return concreteComponentDescriptorProvider<
+      SmoothClipBackdropViewComponentDescriptor>();
+}
+
++ (BOOL)shouldBeRecycled {
+  return NO;
+}
+
+- (instancetype)initWithFrame:(CGRect)frame {
+  if (self = [super initWithFrame:frame]) {
+    static const auto defaultProps =
+        std::make_shared<const SmoothClipBackdropViewProps>();
+    _props = defaultProps;
+    _content = [[SmoothClipBackdropContentView alloc] initWithFrame:self.bounds];
+    _content.autoresizesSubviews = NO;
+    [self addSubview:_content];
+    _driverId = 0;
+    _translation = CGPointZero;
+    _animating = NO;
+  }
+  return self;
+}
+
+- (void)dealloc {
+  if (_driverId != 0) {
+    smoothclip::unregisterBackdropView(_driverId, self);
+  }
+}
+
+- (void)mountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
+                          index:(NSInteger)index {
+  NSAssert(childComponentView.superview == nil,
+           @"SmoothClipBackdropView attempted to mount an already-mounted child");
+  [_content insertSubview:childComponentView atIndex:index];
+}
+
+- (void)unmountChildComponentView:(UIView<RCTComponentViewProtocol> *)childComponentView
+                            index:(NSInteger)index {
+  NSAssert(childComponentView.superview == _content,
+           @"SmoothClipBackdropView attempted to unmount a child from another parent");
+  [childComponentView removeFromSuperview];
+}
+
+- (void)updateLayoutMetrics:(const LayoutMetrics &)layoutMetrics
+           oldLayoutMetrics:(const LayoutMetrics &)oldLayoutMetrics {
+  [super updateLayoutMetrics:layoutMetrics oldLayoutMetrics:oldLayoutMetrics];
+  // Bounds and centre, never frame: the content layer carries the channel as
+  // a translation transform, and a frame write under a transform re-derives
+  // the position through the transform's inverse, folding the current
+  // translation into the position for good. Fabric sets props (and so the
+  // channel) before it lays the view out.
+  const CGRect bounds = self.bounds;
+  _content.bounds = bounds;
+  _content.center = CGPointMake(CGRectGetMidX(bounds), CGRectGetMidY(bounds));
+}
+
+- (void)updateProps:(const Props::Shared &)props
+           oldProps:(const Props::Shared &)oldProps {
+  const auto &newProps =
+      *std::static_pointer_cast<const SmoothClipBackdropViewProps>(props);
+  [super updateProps:props oldProps:oldProps];
+  const uint64_t nextDriverId =
+      isfinite(newProps.driverId) && newProps.driverId > 0
+      ? static_cast<uint64_t>(newProps.driverId)
+      : 0;
+  if (nextDriverId == _driverId) return;
+  if (_driverId != 0) {
+    smoothclip::unregisterBackdropView(_driverId, self);
+  }
+  _driverId = nextDriverId;
+  if (_driverId != 0) {
+    smoothclip::registerBackdropView(_driverId, self);
+  }
+}
+
+- (void)prepareForRecycle {
+  if (_driverId != 0) {
+    smoothclip::unregisterBackdropView(_driverId, self);
+    _driverId = 0;
+  }
+  [self stopBackdropAnimation];
+  [self writeTranslation:CGPointZero];
+  [super prepareForRecycle];
+}
+
+// MARK: - Registry hooks
+
+- (void)writeTranslation:(CGPoint)translation {
+  _translation = translation;
+  _content.layer.transform =
+      CATransform3DMakeTranslation(translation.x, translation.y, 0);
+}
+
+- (void)stopBackdropAnimation {
+  if (!_animating) return;
+  [_content.layer removeAnimationForKey:kSmoothClipBackdropAnimationKey];
+  _animating = NO;
+}
+
+- (CGPoint)smoothClipBackdropCurrentTranslation {
+  CALayer *layer = _animating ? _content.layer.presentationLayer : nil;
+  if (layer == nil) return _translation;
+  const CATransform3D transform = layer.transform;
+  return CGPointMake(transform.m41, transform.m42);
+}
+
+- (void)smoothClipApplyBackdrop:(CGPoint)translation {
+  [self stopBackdropAnimation];
+  [self writeTranslation:translation];
+}
+
+- (void)installBackdropGroup:(CAAnimationGroup *)group
+             sharedBeginTime:(CFTimeInterval)sharedBeginTime {
+  if (sharedBeginTime <= 0) sharedBeginTime = CACurrentMediaTime();
+  // The clip's epoch, translated into this layer's clock: a stamped epoch
+  // may sit up to one frame ahead of the commit, and until it arrives the
+  // run presents its first frame rather than the target the model holds.
+  group.beginTime = [_content.layer convertTime:sharedBeginTime fromLayer:nil];
+  group.fillMode = kCAFillModeBackwards;
+  [_content.layer addAnimation:group forKey:kSmoothClipBackdropAnimationKey];
+  _animating = YES;
+}
+
+- (BOOL)smoothClipAnimateBackdropTo:(CGPoint)target
+                             timing:(smoothclip::TimingAnimation)timing
+                    sharedBeginTime:(CFTimeInterval)sharedBeginTime {
+  const CGPoint from = [self smoothClipBackdropCurrentTranslation];
+  [self stopBackdropAnimation];
+  [self writeTranslation:target];
+  if (self.window == nil) return NO;
+  CAMediaTimingFunction *function = [CAMediaTimingFunction
+      functionWithControlPoints:timing.controlPoint1X
+                               :timing.controlPoint1Y
+                               :timing.controlPoint2X
+                               :timing.controlPoint2Y];
+  CABasicAnimation *x =
+      [CABasicAnimation animationWithKeyPath:@"transform.translation.x"];
+  x.fromValue = @(from.x);
+  x.toValue = @(target.x);
+  x.timingFunction = function;
+  CABasicAnimation *y =
+      [CABasicAnimation animationWithKeyPath:@"transform.translation.y"];
+  y.fromValue = @(from.y);
+  y.toValue = @(target.y);
+  y.timingFunction = function;
+  CAAnimationGroup *group = [CAAnimationGroup animation];
+  group.animations = @[ x, y ];
+  group.duration = std::max(0.0, timing.durationMs) / 1000.0;
+  [self installBackdropGroup:group sharedBeginTime:sharedBeginTime];
+  return YES;
+}
+
+- (BOOL)smoothClipAnimateBackdropTo:(CGPoint)target
+                             spring:(smoothclip::SpringAnimation)spring
+                    sharedBeginTime:(CFTimeInterval)sharedBeginTime {
+  const CGPoint from = [self smoothClipBackdropCurrentTranslation];
+  [self stopBackdropAnimation];
+  [self writeTranslation:target];
+  if (self.window == nil) return NO;
+  // The same normalized trajectory and settling rule as the clip host, so
+  // both layers stop in the same frame.
+  const double duration =
+      smoothclip::springSettleDuration(spring, spring.initialVelocity);
+  const auto animation = [&](NSString *keyPath, double fromValue, double toValue) {
+    CASpringAnimation *result = [CASpringAnimation animationWithKeyPath:keyPath];
+    result.fromValue = @(fromValue);
+    result.toValue = @(toValue);
+    result.mass = spring.mass;
+    result.stiffness = spring.stiffness;
+    result.damping = spring.damping;
+    result.initialVelocity = spring.initialVelocity;
+    result.duration = duration;
+    return result;
+  };
+  CAAnimationGroup *group = [CAAnimationGroup animation];
+  group.animations = @[
+    animation(@"transform.translation.x", from.x, target.x),
+    animation(@"transform.translation.y", from.y, target.y),
+  ];
+  group.duration = duration;
+  [self installBackdropGroup:group sharedBeginTime:sharedBeginTime];
+  return YES;
+}
+
+- (void)smoothClipCancelBackdropUsingTarget:(BOOL)useTarget {
+  if (!_animating) return;
+  const CGPoint visible = [self smoothClipBackdropCurrentTranslation];
+  [self stopBackdropAnimation];
+  if (!useTarget) [self writeTranslation:visible];
+}
+
+- (BOOL)smoothClipPauseBackdropAtMediaTime:(CFTimeInterval)mediaTime {
+  CAAnimation *installed =
+      [_content.layer animationForKey:kSmoothClipBackdropAnimationKey];
+  if (!_animating || installed == nil) return NO;
+  CAAnimation *paused = [installed copy];
+  const CFTimeInterval localNow =
+      [_content.layer convertTime:mediaTime fromLayer:nil];
+  paused.speed = 0;
+  paused.timeOffset = std::clamp(
+      localNow - installed.beginTime, (CFTimeInterval)0, installed.duration);
+  paused.beginTime = 0;
+  [_content.layer removeAnimationForKey:kSmoothClipBackdropAnimationKey];
+  [_content.layer addAnimation:paused forKey:kSmoothClipBackdropAnimationKey];
+  return YES;
+}
+
+- (BOOL)smoothClipResumeBackdropAtMediaTime:(CFTimeInterval)mediaTime
+                                  catchUpBy:(CFTimeInterval)catchUp {
+  CAAnimation *installed =
+      [_content.layer animationForKey:kSmoothClipBackdropAnimationKey];
+  if (!_animating || installed == nil) return NO;
+  CAAnimation *resumed = [installed copy];
+  const CFTimeInterval localNow =
+      [_content.layer convertTime:mediaTime fromLayer:nil];
+  const CFTimeInterval resumedTime = std::min(
+      installed.duration,
+      std::max((CFTimeInterval)0, installed.timeOffset + catchUp));
+  resumed.speed = 1;
+  resumed.timeOffset = 0;
+  resumed.beginTime = localNow - resumedTime;
+  [_content.layer removeAnimationForKey:kSmoothClipBackdropAnimationKey];
+  [_content.layer addAnimation:resumed forKey:kSmoothClipBackdropAnimationKey];
+  return YES;
+}
+
+@end

package/ios/SmoothClipRegistry.mm

@@ -1,5 +1,6 @@
 #import "SmoothClipViewRegistry.h"
 
+#import "SmoothClipBackdropView.h"
 #import "SmoothClipView.h"
 
 #import <React/RCTUtils.h>
@@ -57,6 +58,21 @@
 - (void)smoothClipClearVelocitySamples;
 @end
 
+@interface SmoothClipBackdropView (Registry)
+- (CGPoint)smoothClipBackdropCurrentTranslation;
+- (void)smoothClipApplyBackdrop:(CGPoint)translation;
+- (BOOL)smoothClipAnimateBackdropTo:(CGPoint)target
+                             timing:(smoothclip::TimingAnimation)timing
+                    sharedBeginTime:(CFTimeInterval)sharedBeginTime;
+- (BOOL)smoothClipAnimateBackdropTo:(CGPoint)target
+                             spring:(smoothclip::SpringAnimation)spring
+                    sharedBeginTime:(CFTimeInterval)sharedBeginTime;
+- (void)smoothClipCancelBackdropUsingTarget:(BOOL)useTarget;
+- (BOOL)smoothClipPauseBackdropAtMediaTime:(CFTimeInterval)mediaTime;
+- (BOOL)smoothClipResumeBackdropAtMediaTime:(CFTimeInterval)mediaTime
+                                  catchUpBy:(CFTimeInterval)catchUp;
+@end
+
 namespace smoothclip {
 namespace {
 
@@ -91,6 +107,9 @@ struct DriverState {
   bool hasLatest = false;
   Ownership ownership = Ownership::Interactive;
   std::vector<ViewKey> views;
+  // Backdrop views bound to the driver: translated by the presentation's
+  // backdrop channel on every write and animated on every run's epoch.
+  std::vector<ViewKey> backdrops;
   std::optional<ActiveAnimation> animation;
   // Set by destroyDriver while views are still registered (StrictMode effect
   // replay, hosts mounted in another subtree). The entry is erased when the
@@ -116,8 +135,19 @@ struct GroupState {
   std::unordered_set<uint64_t> remainingDriverIds;
   bool finished = true;
   bool mutating = false;
+  // Media time the caller's UI frame was stamped with; 0 when none was given.
+  CFTimeInterval beginTimeHint = 0;
 };
 
+// A frame stamp sits at most one frame ahead of the commit that carries it.
+// Anything further ahead is not a frame stamp and must not hold the run.
+// Behind the commit it is trusted only within the same window the Android
+// frame loop uses (kStartStampSanityWindowS): a group held pending longer than
+// that (a host that could not display, the app inactive) or a stamp from a
+// rescaled clock (Slow Animations) would otherwise begin fully elapsed and
+// snap to its target.
+constexpr CFTimeInterval kMaxBeginTimeLeadS = 0.25;
+
 std::unordered_map<uint64_t, DriverState> &registry() {
   static std::unordered_map<uint64_t, DriverState> value;
   return value;
@@ -199,6 +229,7 @@ void tryStartGroup(int32_t groupId);
 void finishGroupForHostLoss(int32_t groupId);
 DriverSnapshot snapshotForDriver(uint64_t driverId);
 SmoothClipView *viewForKey(ViewKey key);
+SmoothClipBackdropView *backdropForKey(ViewKey key);
 
 bool animationNeedsForegroundReconciliation(const DriverState &state) {
   if (!state.animation.has_value()) return false;
@@ -248,6 +279,9 @@ bool pauseSpringForInactivity(
         smoothClipPauseSpringAnimation:animation.animationId
                            atMediaTime:mediaTime] && paused;
   }
+  for (const ViewKey key : state.backdrops) {
+    [backdropForKey(key) smoothClipPauseBackdropAtMediaTime:mediaTime];
+  }
   if (!paused) animation.needsForegroundReconciliation = true;
   return paused;
 }
@@ -268,6 +302,10 @@ bool resumeSpringAfterInactivity(
                             atMediaTime:mediaTime
                              catchUpBy:catchUp] && resumed;
   }
+  for (const ViewKey key : state.backdrops) {
+    [backdropForKey(key) smoothClipResumeBackdropAtMediaTime:mediaTime
+                                                   catchUpBy:catchUp];
+  }
   if (!resumed) animation.needsForegroundReconciliation = true;
   return resumed;
 }
@@ -328,6 +366,83 @@ SmoothClipView *viewForKey(ViewKey key) {
   return (__bridge SmoothClipView *)(reinterpret_cast<void *>(key));
 }
 
+ViewKey keyForBackdrop(SmoothClipBackdropView *view) {
+  return reinterpret_cast<ViewKey>((__bridge void *)view);
+}
+
+SmoothClipBackdropView *backdropForKey(ViewKey key) {
+  return (__bridge SmoothClipBackdropView *)(reinterpret_cast<void *>(key));
+}
+
+CGPoint backdropTranslation(const Presentation &presentation) {
+  return CGPointMake(
+      presentation.backdropTranslateX, presentation.backdropTranslateY);
+}
+
+// The clip host knows nothing of the backdrop channel, so a presentation
+// read back from it carries none. A bound backdrop's visible translation is
+// the truth; without one, the driver's model (a pending run's start, else the
+// latest target).
+void overlayBackdrop(const DriverState &state, Presentation &presentation) {
+  if (!state.backdrops.empty()) {
+    const CGPoint translation = [backdropForKey(state.backdrops.front())
+        smoothClipBackdropCurrentTranslation];
+    presentation.backdropTranslateX = translation.x;
+    presentation.backdropTranslateY = translation.y;
+    return;
+  }
+  const Presentation &model =
+      state.animation.has_value() && !state.animation->started
+      ? state.animation->start
+      : state.latest;
+  presentation.backdropTranslateX = model.backdropTranslateX;
+  presentation.backdropTranslateY = model.backdropTranslateY;
+}
+
+void applyBackdrops(const DriverState &state, const Presentation &presentation) {
+  const CGPoint translation = backdropTranslation(presentation);
+  for (const ViewKey key : state.backdrops) {
+    [backdropForKey(key) smoothClipApplyBackdrop:translation];
+  }
+}
+
+void cancelBackdrops(const DriverState &state, bool useTarget) {
+  for (const ViewKey key : state.backdrops) {
+    [backdropForKey(key) smoothClipCancelBackdropUsingTarget:useTarget];
+  }
+}
+
+// Freezes every bound backdrop where it is and reads the channel back into
+// the frozen presentation.
+void freezeBackdropsInto(const DriverState &state, Presentation &presentation) {
+  cancelBackdrops(state, false);
+  overlayBackdrop(state, presentation);
+}
+
+// Runs the pending animation's backdrop channel on every bound backdrop, on
+// the same epoch as the clip's group. An inherited spring velocity was
+// resolved once by the registry before dispatch (resolvedSpringVelocity), so
+// `active.spring` carries the same trajectory the clip host runs.
+void installBackdropAnimations(
+    const DriverState &state,
+    CFTimeInterval sharedBeginTime) {
+  if (!state.animation.has_value() || state.backdrops.empty()) return;
+  const ActiveAnimation &active = *state.animation;
+  const CGPoint target = backdropTranslation(state.latest);
+  for (const ViewKey key : state.backdrops) {
+    SmoothClipBackdropView *backdrop = backdropForKey(key);
+    if (active.kind == AnimationKind::Timing) {
+      [backdrop smoothClipAnimateBackdropTo:target
+                                     timing:active.timing
+                            sharedBeginTime:sharedBeginTime];
+    } else {
+      [backdrop smoothClipAnimateBackdropTo:target
+                                     spring:active.spring
+                            sharedBeginTime:sharedBeginTime];
+    }
+  }
+}
+
 bool shouldReduceMotion(int32_t setting) {
   return setting == 1 ||
       (setting == 0 && UIAccessibilityIsReduceMotionEnabled());
@@ -468,6 +583,7 @@ Presentation canonicalFrozenPresentation(
   if (!hasCanonical && hasParticipantFallback) {
     canonical = participantFallback;
   }
+  freezeBackdropsInto(state, canonical);
   return canonical;
 }
 
@@ -478,7 +594,9 @@ Presentation canonicalVisiblePresentation(const DriverState &state) {
   for (const ViewKey key : state.views) {
     SmoothClipView *candidate = viewForKey(key);
     if ([candidate smoothClipIsJoinable]) {
-      return [candidate smoothClipCurrentPresentation];
+      Presentation visible = [candidate smoothClipCurrentPresentation];
+      overlayBackdrop(state, visible);
+      return visible;
     }
   }
   return state.latest;
@@ -554,11 +672,13 @@ std::vector<DriverSnapshot> cancelGroupInternal(
       for (const ViewKey key : state.views) {
         [viewForKey(key) smoothClipCancelAnimationUsingTarget:YES];
       }
+      cancelBackdrops(state, true);
       if (wasPending) {
         for (const ViewKey key : state.views) {
           [viewForKey(key) smoothClipApplyPresentation:resolved
                                   recordVelocitySample:NO];
         }
+        applyBackdrops(state, resolved);
       }
     } else {
       resolved = canonicalFrozenPresentation(state);
@@ -614,6 +734,7 @@ void cancelActive(
   for (const ViewKey key : state.views) {
     [viewForKey(key) smoothClipCancelAnimationUsingTarget:useTarget];
   }
+  cancelBackdrops(state, useTarget);
   emitCompletion(driverId, state, animationId, false);
 }
 
@@ -628,6 +749,7 @@ void finishStandaloneAtTarget(uint64_t driverId, DriverState &state) {
   for (const ViewKey key : state.views) {
     [viewForKey(key) smoothClipCancelAnimationUsingTarget:YES];
   }
+  cancelBackdrops(state, true);
   state.ownership = Ownership::Interactive;
   emitCompletion(driverId, state, animationId, true);
 }
@@ -646,6 +768,7 @@ void finishIfNoInstalledParticipants(uint64_t driverId, DriverState &state) {
   for (const ViewKey key : state.views) {
     [viewForKey(key) smoothClipCancelAnimationUsingTarget:YES];
   }
+  cancelBackdrops(state, true);
   state.ownership = Ownership::Interactive;
   emitCompletion(driverId, state, animationId, finished);
 }
@@ -662,6 +785,7 @@ void applyPresentation(
     [viewForKey(key) smoothClipApplyPresentation:presentation
                               recordVelocitySample:recordVelocitySample];
   }
+  applyBackdrops(state, presentation);
 }
 
 void prepareAnimation(
@@ -753,6 +877,7 @@ void startPendingAnimation(DriverState &state) {
     [participant smoothClipApplyPresentation:start recordVelocitySample:NO];
     installPendingAnimation(state, participant, key, start);
   }
+  installBackdropAnimations(state, 0);
 }
 
 void tryStartGroup(int32_t groupId) {
@@ -773,7 +898,18 @@ void tryStartGroup(int32_t groupId) {
     }
   }
 
-  const CFTimeInterval sharedBeginTime = CACurrentMediaTime();
+  // Anchor the run to the UI frame that started it when JS stamped one
+  // (Reanimated's target vsync): a `withTiming` begun in that same frame and
+  // this Core Animation run then trace one epoch, instead of the run leading
+  // by the rest of the frame. A recent stale stamp (a run held pending until
+  // its host could display) starts partway through, as that JS clock did; one
+  // outside the sanity window starts now.
+  const CFTimeInterval now = CACurrentMediaTime();
+  const CFTimeInterval hint = groupIterator->second.beginTimeHint;
+  const CFTimeInterval sharedBeginTime =
+      hint > 0 && hint <= now + kMaxBeginTimeLeadS &&
+          hint >= now - kStartStampSanityWindowS
+      ? hint : now;
   [CATransaction begin];
   [CATransaction setDisableActions:YES];
   for (const uint64_t driverId : driverIds) {
@@ -788,6 +924,7 @@ void tryStartGroup(int32_t groupId) {
       installPendingAnimation(
           state, participant, key, start, sharedBeginTime);
     }
+    installBackdropAnimations(state, sharedBeginTime);
   }
   [CATransaction commit];
 }
@@ -947,6 +1084,7 @@ void registerView(
     state.views.push_back(key);
   }
   [view smoothClipApplyPresentation:visible recordVelocitySample:NO];
+  applyBackdrops(state, visible);
   if (startsPendingRun) {
     startPendingAnimation(state);
   }
@@ -1002,7 +1140,45 @@ void unregisterView(uint64_t driverId, SmoothClipView *view) {
   state.views.erase(
       std::remove(state.views.begin(), state.views.end(), key),
       state.views.end());
-  if (state.destroyed && state.views.empty()) registry().erase(iterator);
+  if (state.destroyed && state.views.empty() && state.backdrops.empty()) {
+    registry().erase(iterator);
+  }
+}
+
+void registerBackdropView(uint64_t driverId, SmoothClipBackdropView *view) {
+  NSCAssert(NSThread.isMainThread, @"SmoothClip registry is main-thread only");
+  auto &state = registry()[driverId];
+  const ViewKey key = keyForBackdrop(view);
+  if (std::find(state.backdrops.begin(), state.backdrops.end(), key) !=
+      state.backdrops.end()) {
+    return;
+  }
+  // Adopt the driver's current value: a pending run's start, an already
+  // bound backdrop's visible value mid-run, else the model. A backdrop bound
+  // while a run is in flight follows from the next run.
+  Presentation visible =
+      state.animation.has_value() && !state.animation->started
+      ? state.animation->start
+      : state.latest;
+  if (!state.backdrops.empty()) overlayBackdrop(state, visible);
+  state.backdrops.push_back(key);
+  if (state.hasLatest) {
+    [view smoothClipApplyBackdrop:backdropTranslation(visible)];
+  }
+}
+
+void unregisterBackdropView(uint64_t driverId, SmoothClipBackdropView *view) {
+  NSCAssert(NSThread.isMainThread, @"SmoothClip registry is main-thread only");
+  auto iterator = registry().find(driverId);
+  if (iterator == registry().end()) return;
+  DriverState &state = iterator->second;
+  const ViewKey key = keyForBackdrop(view);
+  state.backdrops.erase(
+      std::remove(state.backdrops.begin(), state.backdrops.end(), key),
+      state.backdrops.end());
+  if (state.destroyed && state.views.empty() && state.backdrops.empty()) {
+    registry().erase(iterator);
+  }
 }
 
 void setPresentation(
@@ -1325,7 +1501,8 @@ int32_t createGroupAnimation(
     SpringAnimation spring,
     double durationMs,
     int32_t reduceMotion,
-    int32_t completionTag) {
+    int32_t completionTag,
+    double startedAtHintS) {
   std::vector<Presentation> resolvedStarts;
   bool reduced = false;
   if (!NSThread.isMainThread || controllerId == 0 ||
@@ -1377,6 +1554,9 @@ int32_t createGroupAnimation(
       driverIds,
       std::unordered_set<uint64_t>(driverIds.begin(), driverIds.end()),
   };
+  if (std::isfinite(startedAtHintS) && startedAtHintS > 0) {
+    group.beginTimeHint = startedAtHintS;
+  }
   groupRegistry().emplace(groupId, std::move(group));
 
   for (std::size_t entryIndex = 0; entryIndex < entries.size(); entryIndex += 1) {
@@ -1420,7 +1600,6 @@ int32_t animateTimingGroup(
     TimingAnimation animation,
     int32_t completionTag,
     double startedAtHintS) {
-  (void)startedAtHintS;
   return createGroupAnimation(
       controllerId,
       std::move(entries),
@@ -1429,7 +1608,8 @@ int32_t animateTimingGroup(
       {},
       animation.durationMs,
       animation.reduceMotion,
-      completionTag);
+      completionTag,
+      startedAtHintS);
 }
 
 int32_t animateSpringGroup(
@@ -1438,7 +1618,6 @@ int32_t animateSpringGroup(
     SpringAnimation animation,
     int32_t completionTag,
     double startedAtHintS) {
-  (void)startedAtHintS;
   return createGroupAnimation(
       controllerId,
       std::move(entries),
@@ -1447,7 +1626,8 @@ int32_t animateSpringGroup(
       animation,
       0,
       animation.reduceMotion,
-      completionTag);
+      completionTag,
+      startedAtHintS);
 }
 
 std::vector<DriverSnapshot> cancelAnimationGroup(
@@ -1544,6 +1724,7 @@ int32_t animateTiming(
       state.animation->participants.insert(key);
     }
   }
+  installBackdropAnimations(state, 0);
   return animationId;
 }
 
@@ -1633,6 +1814,7 @@ int32_t animateSpring(
       state.animation->participants.insert(key);
     }
   }
+  installBackdropAnimations(state, 0);
   return animationId;
 }
 
@@ -1709,6 +1891,7 @@ CancelResult cancelAnimation(
         [viewForKey(key) smoothClipApplyPresentation:target
                                 recordVelocitySample:NO];
       }
+      applyBackdrops(state, target);
     }
     state.ownership = Ownership::Interactive;
     return {true, target};
@@ -1733,7 +1916,7 @@ void destroyDriver(uint64_t driverId) {
   for (const ViewKey key : state.views) {
     [viewForKey(key) smoothClipClearVelocitySamples];
   }
-  if (state.views.empty()) {
+  if (state.views.empty() && state.backdrops.empty()) {
     registry().erase(iterator);
   } else {
     // Views can outlive the hook briefly (StrictMode effect replay, hosts in