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

package/README.md

@@ -165,6 +165,15 @@ const gesture = Gesture.Pan()
 | `driver`   | `SmoothClipDriver` | Reusable hybrid clip driver.            |
 | `children` | `ReactNode`        | Content rendered inside the fixed host. |
 
+The host hides itself, drops out of the accessibility tree, and stops accepting
+touches while the clip is empty. The two platforms draw the boundary where they
+actually stop rendering, which differs below one pixel: Android emits an integer
+`Outline`, which collapses to nothing under half a physical pixel, so an extent
+in `(0, 0.5)` px counts as empty there; iOS masks in floats and treats only a
+zero-or-negative extent as empty. A clip animating through that band therefore
+turns non-interactive one frame earlier on Android — matching what each platform
+puts on screen, which is the property worth keeping identical.
+
 ### Driver
 
 - `useSmoothClipDriver(initialPresentation, options)` returns one hybrid driver
@@ -190,15 +199,19 @@ const gesture = Gesture.Pan()
   remaining distance in one second). Every geometry channel continues with the
   same normalized rate, so grab/release preserves the felt direction and
   speed. `'inherit'` (the default) estimates the scalar from the last two
-  interactive samples on iOS and Android; samples older than 100 ms — and the
-  web fallback — fall back to zero. Two writes landing inside the same frame
+  interactive samples on iOS and Android; the web fallback always inherits
+  zero. How long the finger has been still since that last sample scales the
+  result: full credit for one frame (16.7 ms), then a linear decay to zero at
+  100 ms. A release straight out of a drag is therefore untouched, and holding
+  still before releasing bleeds the momentum off smoothly instead of keeping
+  all of it until 99 ms and none at 101 ms. Two writes landing inside the same frame
   (< 4 ms apart, e.g. a release-sample `from` seed right after the last drag
   write) coalesce into one sample, and an identical re-write is ignored, so a
   fused handoff can neither zero nor inflate the inherited velocity.
-  `beginInteraction()` records the frozen presentation as a plain sample on
-  both platforms, so a grab-and-instant-refling inherits bounded recent
-  motion (the staleness guard still zeroes a stale pair) instead of
-  launching dead.
+  Only interactive writes contribute samples. Internal freeze/join/resume and
+  static-finalization writes do not, so grabbing a native animation cannot
+  manufacture velocity for a later `'inherit'` spring; a subsequent drag (or
+  explicit `animation.from`) supplies the release samples instead.
 - `driver.react` exposes `beginInteraction`, `set`, `animateTo`, and `cancel`
   as Promises (`setScalars` is UI-worklet-only). React code never blocks
   waiting for main/UI-thread work. An immediate animation request resolves
@@ -217,35 +230,64 @@ const gesture = Gesture.Pan()
   write issued immediately before the handoff, so the animation starts from
   exactly that value (pass `frames[0].presentation` for keyframes, which
   interpolate absolutely). A non-finite `from` rejects the whole call; against
-  a held pending-animation latch the seed is dropped — the latch is newer
-  intent, and nothing is displayable yet anyway. `from` behaves the same on
-  both platforms (it is driver-layer, not native): on iOS the seed stops any
-  running Core Animation and writes the model layer first; keyframes then
-  start exactly at `from`, while timing/spring sample their from-value off
-  the presentation layer — the last committed frame, at most one frame
-  behind `from` — identical to the explicit two-call pattern.
+  a held pending-animation latch, explicit `from` is the newer intent: it
+  cancels that latch once with `finished: false`, records/applies `from`, then
+  starts the replacement from that native value. Passive hook seeds and public
+  `set`/`setScalars` writes still leave a held latch intact. `from` behaves the
+  same on both platforms (it is driver-layer, not native): on iOS the seed
+  stops any running Core Animation and writes the model layer first; keyframes
+  then start exactly at `from`, while timing/spring sample their from-value off
+  the presentation layer — the last committed frame, at most one frame behind
+  `from` — identical to the explicit two-call pattern.
 - `cancel()` freezes visible presentation by default. Pass `'target'` as its
   behavior to jump to the requested endpoint.
 - `options.onAnimationComplete` fires exactly once per animation with its ID
   and `finished` state, including cancellation, replacement, and native-side
   rejection (`animateTo` then returns a fresh non-zero id whose single
   `finished: false` completion follows — key completion handling by the
-  returned id, never by `0`). `animateTo` returns `0` — and delivers no
-  completion — only when the driver entry no longer exists (destroyed) or the
-  call ran off the main thread. Unmounting the last host mid-flight does not complete the
-  animation: the remainder is re-latched and the next displayable host resumes
-  it, so the completion arrives when it finishes there — or unfinished on
-  replacement, cancellation, `beginInteraction()`, or driver destruction.
-  With multiple hosts on one driver, unregistering any participant mid-flight
-  makes the eventual completion `finished: false` — `finished: true` means
-  every participant ran the animation to its end.
+  returned id, never by `0`). A valid pre-registration request carries its
+  authoritative interactive start, creates the missing driver state and
+  returns a real id. `0` — with no completion — is reserved for off-main,
+  invalid-id, or otherwise unsupported dispatch: a missing-state native request
+  with no authoritative start, any `driver.ui.animateTo` issued after the
+  driver's hook has unmounted, and an invalid-parameter request issued before
+  the driver's first seed reached native (validation rejections mint their
+  `finished: false` completion only once the native entry exists). (The
+  post-unmount case is decided on the UI runtime,
+  because a destroyed driver and a not-yet-seeded one are the same missing
+  registry entry to native — accepting it would build a latch nothing can start
+  and nothing can cancel.) A host is displayable only while it is attached,
+  foreground/window-visible, laid out, and positive-sized (the window's own
+  `hidden`/scene state is not consulted — RN's single always-visible window
+  makes it moot). Losing the last
+  displayable host mid-flight — including temporary detach, zero-size layout,
+  or app background — freezes and re-latches the exact remainder instead of
+  consuming duration offscreen. Foreground/reattach resumes the same animation
+  ID from that stored timing/keyframe phase or spring state.
+  Parallel Reanimated clocks do **not** pause with it: a `withTiming` started
+  beside `animateTo` keeps its wall-clock start, so after backgrounding it
+  completes on its first resumed frame while the native run still animates its
+  preserved remainder. Key teardown and state transitions off
+  `onAnimationComplete` (or re-synchronize on `AppState`) rather than off a
+  duration-matched Reanimated callback.
+  With multiple hosts on one driver, a host becomes an installed participant
+  only after its native animation starts. Temporary loss moves it to suspended;
+  a rejoin restores active participation. Unregistering an installed/suspended
+  host, or reaching completion while it remains suspended, makes the eventual
+  completion `finished: false`. A host that stayed deferred because it was
+  detached, unlaid-out, or zero-sized never poisons completion. `finished: true`
+  means every installed participant either ran to the end or rejoined and did so.
 - An `animateTo` issued before any host view can produce a visible frame (for
   example from an effect in the same commit that mounts the host, or inside a
   modal route whose subtree attaches to its window late) is held pending and
-  starts with its full duration at the first displayable registration or
-  window attach. A pending animation owns the driver: take-ownership writes
-  (`set`, `setScalars`, the hook's seed) are dropped while it is held —
-  replace it with another `animateTo`, or cancel it via `beginInteraction()`
+  starts with its full duration at the first moment a registered host can
+  produce a frame — positive layout, window attach/visibility, and foreground
+  state must all be present. This also covers an animation worklet that runs before the
+  hook's seed worklet: the animation creates the state and the later passive
+  seed cannot reset its ownership or active id. A pending animation owns the
+  driver: ordinary take-ownership writes (`set`, `setScalars`, the hook's seed)
+  are dropped while it is held. Replace it with another `animateTo`, override
+  it with an explicit `animation.from`, or cancel it via `beginInteraction()`
   or `cancel()`. If no view ever becomes displayable, it survives until it is
   replaced, cancelled, or the driver is destroyed — at which point its single
   `finished: false` completion is delivered.

package/android/CMakeLists.txt

@@ -36,7 +36,6 @@ target_include_directories(
 
 target_link_libraries(
   smoothclipview
-  android
   log
   fbjni::fbjni
   ReactAndroid::jsi

package/android/build.gradle

@@ -114,6 +114,19 @@ android {
     targetCompatibility JavaVersion.VERSION_1_8
   }
 
+  testOptions {
+    unitTests {
+      includeAndroidResources = true
+      all {
+        // Robolectric on Java 17 reflects into these platform packages.
+        jvmArgs "--add-opens=java.base/java.lang=ALL-UNNAMED",
+                "--add-opens=java.base/java.util=ALL-UNNAMED",
+                "--add-opens=java.base/java.io=ALL-UNNAMED",
+                "--add-opens=java.base/java.net=ALL-UNNAMED"
+      }
+    }
+  }
+
   packagingOptions {
     // Provided by the host application at runtime.
     excludes += [
@@ -128,4 +141,6 @@ android {
 dependencies {
   implementation "com.facebook.react:react-android"
   testImplementation "junit:junit:4.13.2"
+  testImplementation "org.mockito:mockito-core:5.14.2"
+  testImplementation "org.robolectric:robolectric:4.16"
 }

package/android/src/main/cpp/SmoothClipAndroid.h

@@ -22,7 +22,6 @@ struct JSmoothClipView : facebook::jni::JavaClass<JSmoothClipView> {
       const NormalizedClip &clip,
       double contentTranslateXPx,
       double contentTranslateYPx) const;
-  bool isViewAttachedToWindow() const;
 };
 
 // Called from Kotlin (SmoothClipViewManager) on the UI thread when a Fabric
@@ -33,7 +32,8 @@ void registerViewAndroid(
     Presentation initialPresentation,
     double density,
     double hostWidthPx,
-    double hostHeightPx);
+    double hostHeightPx,
+    bool lifecycleVisible);
 // Refreshes a registered view's density / host size (px) and synchronously
 // redelivers the driver's visible value pre-normalized against them.
 void setViewHostGeometryAndroid(
@@ -45,13 +45,17 @@ void setViewHostGeometryAndroid(
 void unregisterViewAndroid(
     uint64_t driverId,
     facebook::jni::alias_ref<JSmoothClipView> view);
-// Called from Kotlin when a registered view attaches to a window. A latched
-// animation may only start once a registered view can actually produce a
-// visible frame (attached AND has host geometry); otherwise its clock would
-// burn progress no one can see.
-void viewBecameDisplayableAndroid(
+// Pushes attachment/window visibility independently of host geometry. The
+// registry combines both signals into its displayability/participant state.
+void setViewLifecycleVisibilityAndroid(
     uint64_t driverId,
-    facebook::jni::alias_ref<JSmoothClipView> view);
+    facebook::jni::alias_ref<JSmoothClipView> view,
+    bool lifecycleVisible);
+
+// Advances the registry frame loop. Called from Kotlin (SmoothClipBindings)
+// inside Choreographer#doFrame with the frame's vsync timestamp converted to
+// seconds; never lets a failure unwind back into doFrame.
+void onFrameAndroid(double frameTimeS);
 
 // Installs `global.__SmoothClipView` (worklet-callable host functions) into the
 // JS runtime and wires native animation completion delivery through the

package/android/src/main/cpp/SmoothClipBindings.cpp

@@ -6,6 +6,7 @@
 #include <jsi/jsi.h>
 
 #include <cmath>
+#include <limits>
 #include <memory>
 #include <unordered_map>
 #include <utility>
@@ -45,6 +46,18 @@ bool boolArg(const Value *args, size_t count, size_t index) {
   return index < count && args[index].isBool() && args[index].getBool();
 }
 
+// Optional trailing start stamp (Reanimated-rule milliseconds captured in the
+// issuing worklet), converted to the registry's CLOCK_MONOTONIC seconds. A
+// missing or non-numeric argument — and the JS side's deliberate NaN fallback
+// when the worklet globals are absent — resolves to NaN, which
+// resolveStartStamp() treats as "no hint": nowSeconds() plus the min() anchor,
+// exactly the pre-hint behavior.
+double startStampArg(const Value *args, size_t count, size_t index) {
+  return index < count && args[index].isNumber()
+      ? args[index].asNumber() / 1000.0
+      : std::numeric_limits<double>::quiet_NaN();
+}
+
 Presentation presentationFromArgs(const Value *args, size_t offset) {
   return Presentation{
       {args[offset].asNumber(),
@@ -153,15 +166,17 @@ void installBindings(
   Object bindings(runtime);
 
   setHostFunction(
-      runtime, bindings, "setClipPresentation", 9,
+      runtime, bindings, "setClipPresentation", 10,
       [](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
         if (count < 9) return Value::undefined();
         const double driverId = args[0].asNumber();
         const Presentation presentation = presentationFromArgs(args, 1);
         const bool takeOwnership = boolArg(args, count, 8);
+        const bool overridePendingAnimation = boolArg(args, count, 9);
         if (validDriverId(driverId) && finitePresentation(presentation)) {
           setPresentation(
-              static_cast<uint64_t>(driverId), presentation, takeOwnership);
+              static_cast<uint64_t>(driverId), presentation, takeOwnership,
+              overridePendingAnimation);
         }
         return Value::undefined();
       });
@@ -177,7 +192,7 @@ void installBindings(
       });
 
   setHostFunction(
-      runtime, bindings, "animateTiming", 22,
+      runtime, bindings, "animateTiming", 23,
       [](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
         if (count < 22) return Value(0);
         const double driverId = args[0].asNumber();
@@ -194,13 +209,13 @@ void installBindings(
         }
         return Value(animateTiming(
             static_cast<uint64_t>(driverId),
-            {boolArg(args, count, 1), start},
+            {boolArg(args, count, 1), start, startStampArg(args, count, 22)},
             target,
             animation));
       });
 
   setHostFunction(
-      runtime, bindings, "animateSpring", 22,
+      runtime, bindings, "animateSpring", 23,
       [](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
         if (count < 22) return Value(0);
         const double driverId = args[0].asNumber();
@@ -221,13 +236,13 @@ void installBindings(
         }
         return Value(animateSpring(
             static_cast<uint64_t>(driverId),
-            {boolArg(args, count, 1), start},
+            {boolArg(args, count, 1), start, startStampArg(args, count, 22)},
             target,
             animation));
       });
 
   setHostFunction(
-      runtime, bindings, "animateKeyframes", 19,
+      runtime, bindings, "animateKeyframes", 20,
       [](Runtime &rt, const Value &, const Value *args, size_t count) -> Value {
         if (count < 19 || !args[17].isObject() ||
             !args[17].getObject(rt).isArray(rt)) {
@@ -270,7 +285,7 @@ void installBindings(
         }
         return Value(animateKeyframes(
             static_cast<uint64_t>(driverId),
-            {boolArg(args, count, 1), start},
+            {boolArg(args, count, 1), start, startStampArg(args, count, 19)},
             target,
             durationMs,
             std::move(keyframes),
@@ -374,7 +389,8 @@ void nativeRegisterView(
     jdouble contentTranslateY,
     jdouble density,
     jdouble widthPx,
-    jdouble heightPx) {
+    jdouble heightPx,
+    jboolean lifecycleVisible) {
   if (driverId <= 0 || !std::isfinite(driverId)) return;
   smoothclip::registerViewAndroid(
       static_cast<uint64_t>(driverId),
@@ -383,7 +399,8 @@ void nativeRegisterView(
           {x, y, width, height, radius}, contentTranslateX, contentTranslateY},
       density,
       widthPx,
-      heightPx);
+      heightPx,
+      lifecycleVisible != 0);
 }
 
 void nativeSetViewHostGeometry(
@@ -406,19 +423,24 @@ void nativeUnregisterView(
   smoothclip::unregisterViewAndroid(static_cast<uint64_t>(driverId), view);
 }
 
-void nativeViewBecameDisplayable(
+void nativeSetViewLifecycleVisibility(
     jni::alias_ref<jni::JObject>,
     jdouble driverId,
-    jni::alias_ref<smoothclip::JSmoothClipView> view) {
+    jni::alias_ref<smoothclip::JSmoothClipView> view,
+    jboolean lifecycleVisible) {
   if (driverId <= 0 || !std::isfinite(driverId)) return;
-  smoothclip::viewBecameDisplayableAndroid(
-      static_cast<uint64_t>(driverId), view);
+  smoothclip::setViewLifecycleVisibilityAndroid(
+      static_cast<uint64_t>(driverId), view, lifecycleVisible != 0);
 }
 
 void nativeInvalidate(jni::alias_ref<jni::JObject>) {
   smoothclip::invalidateBindings();
 }
 
+void nativeOnFrame(jni::alias_ref<jni::JObject>, jlong frameTimeNanos) {
+  smoothclip::onFrameAndroid(static_cast<double>(frameTimeNanos) / 1e9);
+}
+
 } // namespace
 
 JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
@@ -432,8 +454,10 @@ JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
                 "nativeSetViewHostGeometry", nativeSetViewHostGeometry),
             makeNativeMethod("nativeUnregisterView", nativeUnregisterView),
             makeNativeMethod(
-                "nativeViewBecameDisplayable", nativeViewBecameDisplayable),
+                "nativeSetViewLifecycleVisibility",
+                nativeSetViewLifecycleVisibility),
             makeNativeMethod("nativeInvalidate", nativeInvalidate),
+            makeNativeMethod("nativeOnFrame", nativeOnFrame),
         });
   });
 }