react-native-smooth-clip-view 0.2.8 → 0.3.0

package/lib/module/drivers.native.js

@@ -1,20 +1,37 @@
 "use strict";
 
-// The shared NATIVE driver: iOS and Android both execute this file, via the
+// The shared native driver: iOS and Android both execute this file, via the
 // one-line re-exports in drivers.ios.ts / drivers.android.ts that Metro's
 // platform resolution picks up from index.ts's `./drivers` import. Only the
-// `./smoothClipNative` import below is platform-split. drivers.ts (no
-// suffix) is the web/Reanimated fallback, not this driver's sibling.
+// `./smoothClipNative` import below is platform-split.
 import { useEffect, useRef } from 'react';
+import { Platform } from 'react-native';
 import { useSharedValue } from 'react-native-reanimated';
 import { isRNRuntime, scheduleOnRN, scheduleOnUI } from 'react-native-worklets';
 import NativeSmoothClipModule from './smoothClipNative';
+import { getSmoothClipCapabilities } from './capabilities';
 import { allocateDriverId, attachDriverState, createDriverState, detachDriverState, getDriverState, setDriverState } from "./driverState.js";
 import { completeNativeAnimation, synchronizeNativeCompletion } from "./nativeCompletion.js";
-import { clipPresentationEquals, createClipPresentation, isFiniteClipPresentation } from "./geometry.js";
+import { canonicalizeClipPresentation, clipPresentationEquals, createClipPresentation, isFiniteClipPresentation } from "./geometry.js";
 import { createReactRequest, rejectDriverRequests, resolveReactRequest } from "./reactRequests.js";
 const INTERACTIVE = 0;
 const NATIVE = 1;
+
+// Only Android consumes the Reanimated start stamp (its frame-clock anchor —
+// docs/android-frame-clock-anchor.md). iOS's TurboModule reads its declared
+// parameters positionally and drops the trailing argument, so capturing the
+// stamp there is a wasted native _getAnimationTimestamp() call per animateTo.
+// Resolved once at module scope; the worklet captures the primitive.
+const NEEDS_START_STAMP = Platform.OS === 'android';
+const PRESENTATION_PROTOCOL_VERSION = getSmoothClipCapabilities().presentationProtocolVersion;
+const NativeSmoothClipModuleV2 = NativeSmoothClipModule;
+
+// Widened like the animate* functions below: one trailing argument beyond the
+// TurboModule spec — whether this write should record an `'inherit'` velocity
+// sample. Android's JSI bindings read it (absent means record, the pre-flag
+// behavior); the iOS TurboModule reads its declared parameters positionally
+// and drops it, so iOS always records.
+
 const setPresentationHostFunction = NativeSmoothClipModule.setClipPresentation;
 const beginInteractionHostFunction = NativeSmoothClipModule.beginInteraction;
 
@@ -31,15 +48,27 @@ const animateKeyframesHostFunction = NativeSmoothClipModule.animateKeyframes;
 const rejectAnimationHostFunction = NativeSmoothClipModule.rejectAnimation;
 const cancelAnimationHostFunction = NativeSmoothClipModule.cancelAnimation;
 const destroyDriverHostFunction = NativeSmoothClipModule.destroyDriver;
+const setPresentationV2HostFunction = NativeSmoothClipModuleV2.setClipPresentationV2;
+const beginInteractionV2HostFunction = NativeSmoothClipModuleV2.beginInteractionV2;
+const snapshotCurrentV2HostFunction = NativeSmoothClipModuleV2.snapshotCurrentV2;
+const animateTimingV2HostFunction = NativeSmoothClipModuleV2.animateTimingV2;
+const animateSpringV2HostFunction = NativeSmoothClipModuleV2.animateSpringV2;
+const animateKeyframesV2HostFunction = NativeSmoothClipModuleV2.animateKeyframesV2;
+const animateTimingFromV2HostFunction = NativeSmoothClipModuleV2.animateTimingFromV2;
+const animateSpringFromV2HostFunction = NativeSmoothClipModuleV2.animateSpringFromV2;
+const animateKeyframesFromV2HostFunction = NativeSmoothClipModuleV2.animateKeyframesFromV2;
+const cancelAnimationV2HostFunction = NativeSmoothClipModuleV2.cancelAnimationV2;
 
-// Workaround for react-native-worklets 0.10: the RN-side serialization cache
+// Workaround for react-native-worklets 0.10.0 (fixed upstream in >=0.10.1,
+// which drops the registry/proxy design; kept while the peer range still
+// allows 0.10.0 consumers): the RN-side serialization cache
 // hands out one remote-function registry id per function forever, but the
 // registry entry is deleted as soon as any transient UI-side proxy of that
 // function is garbage collected. A later scheduleOnRN for the same function
 // then reads `undefined` from the registry and aborts in Value::getObject.
 // Pinning one UI-side reference for the app lifetime keeps the proxy — and
-// with it the registry entry — alive. Remove once worklets decouples registry
-// cleanup from proxy lifetime.
+// with it the registry entry — alive. Remove once the peer range requires
+// worklets >=0.10.1.
 scheduleOnUI(resolver => {
   'worklet';
 
@@ -55,7 +84,7 @@ function reduceMotionCode(value) {
       return 0;
   }
 }
-function animationIsFinite(target, animation) {
+function animationIsFinite(animation, strictV2) {
   'worklet';
 
   if (animation.from !== undefined && !isFiniteClipPresentation(animation.from)) {
@@ -65,34 +94,53 @@ function animationIsFinite(target, animation) {
   }
   if (animation.type === 'timing') {
     const [x1,, x2] = animation.controlPoints;
-    return Number.isFinite(animation.duration) && animation.controlPoints.every(Number.isFinite) &&
+    return Number.isFinite(animation.duration) && (!strictV2 || animation.duration >= 0) && animation.controlPoints.every(Number.isFinite) && (
     // A cubic-bezier easing is only defined for x within [0,1] (the CSS /
     // CoreAnimation / Reanimated Easing.bezier contract). Out-of-range x
     // makes the Android parameter solve meaningless while CoreAnimation
     // silently clamps — reject like any other invalid input instead of
     // diverging per platform.
-    x1 >= 0 && x1 <= 1 && x2 >= 0 && x2 <= 1;
+    !strictV2 || x1 >= 0 && x1 <= 1 && x2 >= 0 && x2 <= 1);
   }
   if (animation.type === 'spring') {
-    return [animation.mass ?? 1, animation.stiffness ?? 100, animation.damping ?? 10, animation.initialVelocity === 'inherit' ? 0 : animation.initialVelocity ?? 0].every(Number.isFinite);
-  }
-  if (!Number.isFinite(animation.duration) || animation.frames.length < 2) {
-    return false;
-  }
-  let previousOffset = -1;
-  for (const frame of animation.frames) {
-    if (!Number.isFinite(frame.offset) || frame.offset < 0 || frame.offset > 1 || frame.offset <= previousOffset || !isFiniteClipPresentation(frame.presentation)) {
-      return false;
-    }
-    previousOffset = frame.offset;
+    const mass = animation.mass ?? 1;
+    const stiffness = animation.stiffness ?? 100;
+    const damping = animation.damping ?? 10;
+    const initialVelocity = animation.initialVelocity === 'inherit' ? 0 : animation.initialVelocity ?? 0;
+    return [mass, stiffness, damping, initialVelocity].every(Number.isFinite) && (!strictV2 || mass > 0 && stiffness > 0 && damping >= 0);
   }
-  return animation.frames[0]?.offset === 0 && previousOffset === 1 && clipPresentationEquals(animation.frames[animation.frames.length - 1]?.presentation ?? null, target);
+  // Keyframe frames validate inside flattenFiniteKeyframes — one traversal
+  // both checks and flattens, instead of walking every frame twice. The type
+  // check is statically always-true for the TS union but load-bearing for JS
+  // callers: an unrecognized type must reject here, or it would skip the
+  // keyframe gate entirely and hand native a null frames array.
+  return animation.type === 'keyframes' && (!strictV2 || animation.duration >= 0);
 }
 function presentationFromNative(values, fallback, offset = 0) {
   'worklet';
 
+  if (values.length >= offset + 12) {
+    const presentation = canonicalizeClipPresentation({
+      clip: {
+        x: values[offset],
+        y: values[offset + 1],
+        width: values[offset + 2],
+        height: values[offset + 3],
+        radius: 0,
+        topLeftRadius: values[offset + 4],
+        topRightRadius: values[offset + 5],
+        bottomRightRadius: values[offset + 6],
+        bottomLeftRadius: values[offset + 7],
+        curve: values[offset + 8] === 1 ? 'continuous' : 'circular'
+      },
+      contentTranslateX: values[offset + 9],
+      contentTranslateY: values[offset + 10],
+      contentScale: values[offset + 11]
+    });
+    return presentation ?? fallback;
+  }
   if (values.length < offset + 7) return fallback;
-  const presentation = {
+  const presentation = canonicalizeClipPresentation({
     clip: {
       x: values[offset],
       y: values[offset + 1],
@@ -102,20 +150,83 @@ function presentationFromNative(values, fallback, offset = 0) {
     },
     contentTranslateX: values[offset + 5],
     contentTranslateY: values[offset + 6]
-  };
-  return isFiniteClipPresentation(presentation) ? presentation : fallback;
+  });
+  return presentation ?? fallback;
+}
+function curveCode(presentation) {
+  'worklet';
+
+  return presentation.clip.curve === 'continuous' ? 1 : 0;
+}
+function isV1Compatible(presentation) {
+  'worklet';
+
+  const clip = presentation.clip;
+  return clip.curve === 'circular' && clip.topLeftRadius === clip.radius && clip.topRightRadius === clip.radius && clip.bottomRightRadius === clip.radius && clip.bottomLeftRadius === clip.radius && presentation.contentScale === 1;
 }
-function flattenedKeyframes(animation) {
+function springScaleIsProvablyPositive(start, target, animation) {
   'worklet';
 
+  if (start.contentScale === target.contentScale) return true;
+
+  // A zero-velocity critically/over-damped step is monotonic, so its sampled
+  // scale remains between two already-positive endpoints. Inherited or
+  // under-damped configurations can overshoot; callers must compile those
+  // plans to exact keyframes instead of risking a non-positive transform.
+  const mass = animation.mass ?? 1;
+  const stiffness = animation.stiffness ?? 100;
+  const damping = animation.damping ?? 10;
+  return animation.initialVelocity === 0 && damping * damping >= 4 * mass * stiffness;
+}
+
+// Validates and flattens the keyframe list in one traversal (the flat number
+// array is the wire format the native side reads back positionally). Returns
+// null when any frame is invalid — same rejection contract the two-pass
+// validate-then-flatten had.
+function flattenFiniteKeyframes(target, animation) {
+  'worklet';
+
+  if (!Number.isFinite(animation.duration) || animation.frames.length < 2) {
+    return null;
+  }
   const values = [];
+  const canonicalFrames = [];
+  let previousOffset = -1;
   for (const frame of animation.frames) {
+    const {
+      offset
+    } = frame;
+    const presentation = canonicalizeClipPresentation(frame.presentation);
+    if (!Number.isFinite(offset) || offset < 0 || offset > 1 || offset <= previousOffset || presentation === null || presentation.clip.curve !== target.clip.curve) {
+      return null;
+    }
+    previousOffset = offset;
+    canonicalFrames.push(presentation);
     const {
       clip,
       contentTranslateX,
-      contentTranslateY
-    } = frame.presentation;
-    values.push(frame.offset, clip.x, clip.y, clip.width, clip.height, clip.radius, contentTranslateX, contentTranslateY);
+      contentTranslateY,
+      contentScale
+    } = presentation;
+    values.push(offset, clip.x, clip.y, clip.width, clip.height, clip.topLeftRadius, clip.topRightRadius, clip.bottomRightRadius, clip.bottomLeftRadius, curveCode(presentation), contentTranslateX, contentTranslateY, contentScale);
+  }
+  if (animation.frames[0]?.offset !== 0 || previousOffset !== 1 || !clipPresentationEquals(canonicalFrames[canonicalFrames.length - 1] ?? null, target)) {
+    return null;
+  }
+  return {
+    frames: values,
+    canonicalFrames
+  };
+}
+function flattenV1Keyframes(frames, offsets) {
+  'worklet';
+
+  const values = [];
+  for (let index = 0; index < frames.length; index += 1) {
+    const presentation = frames[index];
+    const offset = offsets[index];
+    if (presentation === undefined || offset === undefined) continue;
+    values.push(offset, presentation.clip.x, presentation.clip.y, presentation.clip.width, presentation.clip.height, presentation.clip.radius, presentation.contentTranslateX, presentation.contentTranslateY);
   }
   return values;
 }
@@ -125,7 +236,11 @@ function uiOnly() {
   throw new Error('[SmoothClipView] driver.ui methods must run on the UI runtime. Use driver.react from React code.');
 }
 export function useSmoothClipDriver(initialValue, options = {}) {
-  const initialPresentation = 'clip' in initialValue ? initialValue : createClipPresentation(initialValue);
+  const requestedInitialPresentation = 'clip' in initialValue ? initialValue : createClipPresentation(initialValue);
+  const initialPresentation = canonicalizeClipPresentation(requestedInitialPresentation);
+  if (initialPresentation === null) {
+    throw new Error('[SmoothClipView] Initial presentation must be finite.');
+  }
   const presentation = useSharedValue(initialPresentation);
   const ownership = useSharedValue(INTERACTIVE);
   const suppressDeliveries = useSharedValue(0);
@@ -148,6 +263,11 @@ export function useSmoothClipDriver(initialValue, options = {}) {
   if (driverRef.current === null) {
     const driverId = allocateDriverId();
     const reduceMotion = reduceMotionCode(options.reduceMotion ?? 'system');
+    // Captured once, like reduceMotion. Only the per-frame setScalars stream
+    // consults it; set(), the fused animateTo `from` seed, and the effect's
+    // declarative deliveries always record, so every once-per-call channel
+    // keeps its pre-flag 'inherit' behavior.
+    const velocityTracking = options.velocityTracking === true;
     const seedPresentation = next => {
       'worklet';
 
@@ -165,8 +285,9 @@ export function useSmoothClipDriver(initialValue, options = {}) {
     const beginOnUI = () => {
       'worklet';
 
-      if (disposed.value !== 0) return presentation.value;
-      const current = presentationFromNative(beginInteractionHostFunction(driverId), presentation.value);
+      const fallback = canonicalizeClipPresentation(presentation.value) ?? initialPresentation;
+      if (disposed.value !== 0) return fallback;
+      const current = presentationFromNative(PRESENTATION_PROTOCOL_VERSION === 2 && beginInteractionV2HostFunction ? beginInteractionV2HostFunction(driverId) : beginInteractionHostFunction(driverId), fallback);
       activeAnimationId.value = 0;
       ownership.value = INTERACTIVE;
       scalarsStale.value = 0;
@@ -176,28 +297,72 @@ export function useSmoothClipDriver(initialValue, options = {}) {
     const setOnUI = next => {
       'worklet';
 
-      if (disposed.value !== 0 || !isFiniteClipPresentation(next)) return;
+      const canonical = canonicalizeClipPresentation(next);
+      if (disposed.value !== 0 || canonical === null) return;
       activeAnimationId.value = 0;
       ownership.value = INTERACTIVE;
       scalarsStale.value = 0;
       const {
         clip,
         contentTranslateX,
-        contentTranslateY
-      } = next;
-      setPresentationHostFunction(driverId, clip.x, clip.y, clip.width, clip.height, clip.radius, contentTranslateX, contentTranslateY, true, false);
-      seedPresentation(next);
+        contentTranslateY,
+        contentScale
+      } = canonical;
+      // Always records: only the per-frame setScalars hot path is gated by
+      // velocityTracking. set() already pays full validation and a SharedValue
+      // seed per call, so the sample recording is noise here.
+      if (PRESENTATION_PROTOCOL_VERSION === 2 && setPresentationV2HostFunction) {
+        setPresentationV2HostFunction(driverId, clip.x, clip.y, clip.width, clip.height, clip.topLeftRadius, clip.topRightRadius, clip.bottomRightRadius, clip.bottomLeftRadius, curveCode(canonical), contentTranslateX, contentTranslateY, contentScale, true, false, true);
+      } else if (isV1Compatible(canonical)) {
+        setPresentationHostFunction(driverId, clip.x, clip.y, clip.width, clip.height, clip.radius, contentTranslateX, contentTranslateY, true, false);
+      } else {
+        return;
+      }
+      seedPresentation(canonical);
     };
-    const setScalarsOnUI = (x, y, width, height, radius, contentTranslateX, contentTranslateY, overridePendingAnimation = false) => {
+    const setScalarsOnUI = (x, y, width, height, radius, contentTranslateX, contentTranslateY, overridePendingAnimation = false, forceRecordVelocity = false) => {
       'worklet';
 
+      // Resolved in the body, not as a default-parameter initializer: the
+      // worklets Babel plugin only captures closure variables referenced
+      // inside the function body, so `= velocityTracking` up in the parameter
+      // list would throw "Property 'velocityTracking' doesn't exist" on the
+      // UI runtime.
+      const recordVelocity = forceRecordVelocity || velocityTracking;
+      // Number.isFinite (not a fused arithmetic gate): it also rejects
+      // non-number types, which arithmetic would coerce past the gate and
+      // into a UI-runtime throw from the binding's asNumber. The gate must
+      // stay on this side of the bridge: the native binding drops non-finite
+      // writes silently, and flipping the ownership SharedValues below for a
+      // write native never applied would let the deliver listener record
+      // values native has not observed — a later identical declarative write
+      // then dedupes against them and is swallowed for good.
       if (disposed.value !== 0 || !Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(width) || !Number.isFinite(height) || !Number.isFinite(radius) || !Number.isFinite(contentTranslateX) || !Number.isFinite(contentTranslateY)) {
         return;
       }
       if (activeAnimationId.value !== 0) activeAnimationId.value = 0;
       if (ownership.value !== INTERACTIVE) ownership.value = INTERACTIVE;
       if (scalarsStale.value === 0) scalarsStale.value = 1;
-      setPresentationHostFunction(driverId, x, y, width, height, radius, contentTranslateX, contentTranslateY, true, overridePendingAnimation);
+      setPresentationHostFunction(driverId, x, y, width, height, radius, contentTranslateX, contentTranslateY, true, overridePendingAnimation, recordVelocity);
+    };
+    const setPresentationScalarsOnUI = (x, y, width, height, topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius, nextCurveCode, contentTranslateX, contentTranslateY, contentScale, overridePendingAnimation = false, forceRecordVelocity = false) => {
+      'worklet';
+
+      const values = [x, y, width, height, topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius, nextCurveCode, contentTranslateX, contentTranslateY, contentScale];
+      if (disposed.value !== 0 || !values.every(Number.isFinite) || nextCurveCode !== 0 && nextCurveCode !== 1 || contentScale <= 0) {
+        return;
+      }
+      const recordVelocity = forceRecordVelocity || velocityTracking;
+      if (PRESENTATION_PROTOCOL_VERSION !== 2 || !setPresentationV2HostFunction) {
+        if (nextCurveCode === 0 && contentScale === 1 && topLeftRadius === topRightRadius && topLeftRadius === bottomRightRadius && topLeftRadius === bottomLeftRadius) {
+          setScalarsOnUI(x, y, width, height, topLeftRadius, contentTranslateX, contentTranslateY, overridePendingAnimation, forceRecordVelocity);
+        }
+        return;
+      }
+      if (activeAnimationId.value !== 0) activeAnimationId.value = 0;
+      if (ownership.value !== INTERACTIVE) ownership.value = INTERACTIVE;
+      if (scalarsStale.value === 0) scalarsStale.value = 1;
+      setPresentationV2HostFunction(driverId, x, y, width, height, topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius, nextCurveCode, contentTranslateX, contentTranslateY, contentScale, true, overridePendingAnimation, recordVelocity);
     };
     const animateOnUI = (target, animation) => {
       'worklet';
@@ -206,7 +371,43 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       // invalid stale call cannot mint a native rejection id/completion against
       // a driver whose listener and registry entry are already gone.
       if (disposed.value !== 0) return 0;
-      if (!isFiniteClipPresentation(target) || !animationIsFinite(target, animation)) {
+      const canonicalTarget = canonicalizeClipPresentation(target);
+      const canonicalFrom = animation.from === undefined ? undefined : canonicalizeClipPresentation(animation.from);
+      const keyframeResult = animation.type === 'keyframes' ? canonicalTarget === null ? null : flattenFiniteKeyframes(canonicalTarget, animation) : null;
+      if (canonicalTarget === null || animation.from !== undefined && canonicalFrom === null || animation.type === 'keyframes' && keyframeResult === null) {
+        return rejectAnimationHostFunction(driverId);
+      }
+      const resolvedFrom = canonicalFrom ?? undefined;
+      const v1Compatible = isV1Compatible(canonicalTarget) && (resolvedFrom === undefined || isV1Compatible(resolvedFrom)) && (animation.type !== 'keyframes' || (keyframeResult?.canonicalFrames.every(isV1Compatible) ?? false));
+      // V1-representable plans deliberately stay on the original seven-scalar
+      // bridge even when V2 is installed. Besides preserving bridge shape,
+      // this retains V1's finite-value/clamping and host-normalization rules.
+      const useV2 = !v1Compatible;
+      if (!animationIsFinite(animation, useV2)) {
+        return rejectAnimationHostFunction(driverId);
+      }
+      const hasV2Protocol = PRESENTATION_PROTOCOL_VERSION === 2 && snapshotCurrentV2HostFunction !== undefined && animateTimingV2HostFunction !== undefined && animateSpringV2HostFunction !== undefined && animateKeyframesV2HostFunction !== undefined;
+      const hasAtomicFromMethod = resolvedFrom === undefined || (animation.type === 'timing' ? animateTimingFromV2HostFunction !== undefined : animation.type === 'spring' ? animateSpringFromV2HostFunction !== undefined : animateKeyframesFromV2HostFunction !== undefined);
+      // This is intentionally before sampling or any ownership/group/
+      // presentation mutation. New JS against old native must fail closed,
+      // and an explicit V2 start must never degrade to set()+animate().
+      if (useV2 && (!hasV2Protocol || !hasAtomicFromMethod)) {
+        return rejectAnimationHostFunction(driverId);
+      }
+      if (useV2 && resolvedFrom !== undefined && animation.type === 'keyframes' && !clipPresentationEquals(keyframeResult?.canonicalFrames[0] ?? null, resolvedFrom)) {
+        return rejectAnimationHostFunction(driverId);
+      }
+      const currentPresentation = canonicalizeClipPresentation(presentation.value) ?? initialPresentation;
+      const sampledStart = resolvedFrom ?? (useV2 ? presentationFromNative(snapshotCurrentV2HostFunction(driverId), currentPresentation) : currentPresentation);
+      // setPresentationScalars intentionally leaves the public SharedValue
+      // stale to keep the hot path allocation-free. Validate an implicit
+      // retarget against the sampled native-visible start, not that stale JS
+      // value; otherwise a streamed curve transition cannot settle natively on
+      // its new (now stable) curve.
+      if (canonicalTarget.clip.curve !== sampledStart.clip.curve) {
+        return rejectAnimationHostFunction(driverId);
+      }
+      if (useV2 && animation.type === 'spring' && !springScaleIsProvablyPositive(sampledStart, canonicalTarget, animation)) {
         return rejectAnimationHostFunction(driverId);
       }
       // Past the hook's cleanup the native entry is gone for good, and an
@@ -215,14 +416,19 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       // rejectAnimation, which would mint an id and a completion for a driver
       // whose JS state is already detached. This is the "unsupported dispatch"
       // arm of the documented 0 contract.
-      const from = animation.from;
-      if (from !== undefined) {
+      const from = resolvedFrom;
+      if (from !== undefined && !useV2) {
         // Fused hot write: exactly setScalars(from…) issued immediately
         // before the handoff, so native's latest value — the animation
         // start below — is the caller's explicit presentation. Also
         // re-grabs from a running animation, which the implicit
-        // interactive-start path would silently skip.
-        setScalarsOnUI(from.clip.x, from.clip.y, from.clip.width, from.clip.height, from.clip.radius, from.contentTranslateX, from.contentTranslateY, true);
+        // interactive-start path would silently skip. Always records a
+        // velocity sample regardless of velocityTracking: this is one write
+        // per animateTo, not the per-frame stream the flag exists to keep
+        // cheap, and an unrecorded seed would invalidate the history a
+        // set()-driven drag just recorded (the tracker's coalesce and
+        // identical-re-record rules were designed for exactly this write).
+        setScalarsOnUI(from.clip.x, from.clip.y, from.clip.width, from.clip.height, from.clip.radius, from.contentTranslateX, from.contentTranslateY, true, true);
       }
 
       // After a setScalars hot write the SharedValue no longer matches what
@@ -231,12 +437,17 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       // latest value instead.
       const scalarsWereStale = scalarsStale.value !== 0;
       const hasInteractiveStart = ownership.value === INTERACTIVE && !scalarsWereStale;
-      const start = presentation.value;
-      ownership.value = NATIVE;
-      presentation.value = target;
-      scalarsStale.value = 0;
-      const startClip = start.clip;
-      const targetClip = target.clip;
+      const start = canonicalizeClipPresentation(presentation.value) ?? initialPresentation;
+      // V1 preserves the old optimistic SharedValue ownership transition.
+      // V2 commits it only after native has atomically accepted the plan.
+      if (!useV2) {
+        ownership.value = NATIVE;
+        presentation.value = canonicalTarget;
+        scalarsStale.value = 0;
+      }
+      const dispatchStart = useV2 && from !== undefined ? from : start;
+      const startClip = dispatchStart.clip;
+      const targetClip = canonicalTarget.clip;
       // Reanimated stamps a parallel animation's t0 on this same runtime as
       // `__frameTimestamp || _getAnimationTimestamp()` (valueSetter.ts).
       // Capturing the identical value here and handing it to the integrator
@@ -247,18 +458,36 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       // its rAF flush where __frameTimestamp is cleared, keeps the wall
       // clock — a lead lasting the whole animation. NaN when the globals are
       // absent (tests, non-worklets runtimes): native then falls back to its
-      // own clock plus the min() anchor, the pre-stamp behavior.
+      // own clock plus the min() anchor, the pre-stamp behavior. On iOS the
+      // stamp is always NaN: Core Animation anchors at commit time and the
+      // TurboModule discards the argument, so the capture would only cost.
       const workletGlobal = globalThis;
-      const startedAtMs = workletGlobal.__frameTimestamp || (typeof workletGlobal._getAnimationTimestamp === 'function' ? workletGlobal._getAnimationTimestamp() : Number.NaN);
+      const startedAtMs = !NEEDS_START_STAMP ? Number.NaN : workletGlobal.__frameTimestamp || (typeof workletGlobal._getAnimationTimestamp === 'function' ? workletGlobal._getAnimationTimestamp() : Number.NaN);
       let animationId;
-      if (animation.type === 'timing') {
+      if (animation.type === 'timing' && useV2) {
+        const [x1, y1, x2, y2] = animation.controlPoints;
+        animationId = from !== undefined ? animateTimingFromV2HostFunction(driverId, startClip.x, startClip.y, startClip.width, startClip.height, startClip.topLeftRadius, startClip.topRightRadius, startClip.bottomRightRadius, startClip.bottomLeftRadius, curveCode(dispatchStart), dispatchStart.contentTranslateX, dispatchStart.contentTranslateY, dispatchStart.contentScale, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.topLeftRadius, targetClip.topRightRadius, targetClip.bottomRightRadius, targetClip.bottomLeftRadius, curveCode(canonicalTarget), canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, canonicalTarget.contentScale, animation.duration, x1, y1, x2, y2, reduceMotion, startedAtMs) : animateTimingV2HostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.topLeftRadius, startClip.topRightRadius, startClip.bottomRightRadius, startClip.bottomLeftRadius, curveCode(dispatchStart), dispatchStart.contentTranslateX, dispatchStart.contentTranslateY, dispatchStart.contentScale, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.topLeftRadius, targetClip.topRightRadius, targetClip.bottomRightRadius, targetClip.bottomLeftRadius, curveCode(canonicalTarget), canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, canonicalTarget.contentScale, animation.duration, x1, y1, x2, y2, reduceMotion, startedAtMs);
+      } else if (animation.type === 'timing') {
         const [x1, y1, x2, y2] = animation.controlPoints;
-        animationId = animateTimingHostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.radius, start.contentTranslateX, start.contentTranslateY, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.radius, target.contentTranslateX, target.contentTranslateY, Math.max(0, animation.duration), x1, y1, x2, y2, reduceMotion, startedAtMs);
+        animationId = animateTimingHostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.radius, start.contentTranslateX, start.contentTranslateY, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.radius, canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, Math.max(0, animation.duration), x1, y1, x2, y2, reduceMotion, startedAtMs);
+      } else if (animation.type === 'spring' && useV2) {
+        const inheritVelocity = animation.initialVelocity === undefined || animation.initialVelocity === 'inherit';
+        const mass = animation.mass ?? 1;
+        const stiffness = animation.stiffness ?? 100;
+        const damping = animation.damping ?? 10;
+        const initialVelocity = inheritVelocity ? 0 : animation.initialVelocity;
+        animationId = from !== undefined ? animateSpringFromV2HostFunction(driverId, startClip.x, startClip.y, startClip.width, startClip.height, startClip.topLeftRadius, startClip.topRightRadius, startClip.bottomRightRadius, startClip.bottomLeftRadius, curveCode(dispatchStart), dispatchStart.contentTranslateX, dispatchStart.contentTranslateY, dispatchStart.contentScale, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.topLeftRadius, targetClip.topRightRadius, targetClip.bottomRightRadius, targetClip.bottomLeftRadius, curveCode(canonicalTarget), canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, canonicalTarget.contentScale, mass, stiffness, damping, initialVelocity, inheritVelocity, reduceMotion, startedAtMs) : animateSpringV2HostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.topLeftRadius, startClip.topRightRadius, startClip.bottomRightRadius, startClip.bottomLeftRadius, curveCode(dispatchStart), dispatchStart.contentTranslateX, dispatchStart.contentTranslateY, dispatchStart.contentScale, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.topLeftRadius, targetClip.topRightRadius, targetClip.bottomRightRadius, targetClip.bottomLeftRadius, curveCode(canonicalTarget), canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, canonicalTarget.contentScale, mass, stiffness, damping, initialVelocity, inheritVelocity, reduceMotion, startedAtMs);
       } else if (animation.type === 'spring') {
         const inheritVelocity = animation.initialVelocity === undefined || animation.initialVelocity === 'inherit';
-        animationId = animateSpringHostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.radius, start.contentTranslateX, start.contentTranslateY, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.radius, target.contentTranslateX, target.contentTranslateY, Math.max(0.0001, animation.mass ?? 1), Math.max(0.0001, animation.stiffness ?? 100), Math.max(0, animation.damping ?? 10), inheritVelocity ? 0 : animation.initialVelocity, inheritVelocity, reduceMotion, startedAtMs);
+        animationId = animateSpringHostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.radius, start.contentTranslateX, start.contentTranslateY, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.radius, canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, Math.max(0.0001, animation.mass ?? 1), Math.max(0.0001, animation.stiffness ?? 100), Math.max(0, animation.damping ?? 10), inheritVelocity ? 0 : animation.initialVelocity, inheritVelocity, reduceMotion, startedAtMs);
+      } else if (useV2) {
+        const frames = keyframeResult.frames;
+        animationId = from !== undefined ? animateKeyframesFromV2HostFunction(driverId, startClip.x, startClip.y, startClip.width, startClip.height, startClip.topLeftRadius, startClip.topRightRadius, startClip.bottomRightRadius, startClip.bottomLeftRadius, curveCode(dispatchStart), dispatchStart.contentTranslateX, dispatchStart.contentTranslateY, dispatchStart.contentScale, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.topLeftRadius, targetClip.topRightRadius, targetClip.bottomRightRadius, targetClip.bottomLeftRadius, curveCode(canonicalTarget), canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, canonicalTarget.contentScale, animation.duration, frames, reduceMotion, startedAtMs) : animateKeyframesV2HostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.topLeftRadius, startClip.topRightRadius, startClip.bottomRightRadius, startClip.bottomLeftRadius, curveCode(dispatchStart), dispatchStart.contentTranslateX, dispatchStart.contentTranslateY, dispatchStart.contentScale, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.topLeftRadius, targetClip.topRightRadius, targetClip.bottomRightRadius, targetClip.bottomLeftRadius, curveCode(canonicalTarget), canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, canonicalTarget.contentScale, animation.duration, frames, reduceMotion, startedAtMs);
       } else {
-        animationId = animateKeyframesHostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.radius, start.contentTranslateX, start.contentTranslateY, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.radius, target.contentTranslateX, target.contentTranslateY, Math.max(0, animation.duration), flattenedKeyframes(animation), reduceMotion, startedAtMs);
+        animationId = animateKeyframesHostFunction(driverId, hasInteractiveStart, startClip.x, startClip.y, startClip.width, startClip.height, startClip.radius, start.contentTranslateX, start.contentTranslateY, targetClip.x, targetClip.y, targetClip.width, targetClip.height, targetClip.radius, canonicalTarget.contentTranslateX, canonicalTarget.contentTranslateY, Math.max(0, animation.duration),
+        // Non-null here: the validation gate above rejected null before any
+        // side effect.
+        flattenV1Keyframes(keyframeResult.canonicalFrames, animation.frames.map(frame => frame.offset)), reduceMotion, startedAtMs);
       }
       if (animationId === 0) {
         // The 0 sentinel: off-main, invalid-id, or otherwise unsupported
@@ -269,12 +498,19 @@ export function useSmoothClipDriver(initialValue, options = {}) {
         // effect, with a fresh id and one finished:false completion once the
         // native entry exists — in the pre-seed window rejectAnimation has no
         // entry and returns the bare 0 sentinel with no completion instead.
-        ownership.value = INTERACTIVE;
-        presentation.value = start;
-        if (scalarsWereStale) scalarsStale.value = 1;
-        activeAnimationId.value = 0;
+        if (!useV2) {
+          ownership.value = INTERACTIVE;
+          presentation.value = start;
+          if (scalarsWereStale) scalarsStale.value = 1;
+          activeAnimationId.value = 0;
+        }
         return rejectAnimationHostFunction(driverId);
       }
+      if (useV2) {
+        ownership.value = NATIVE;
+        presentation.value = canonicalTarget;
+        scalarsStale.value = 0;
+      }
       activeAnimationId.value = animationId;
       return animationId;
     };
@@ -284,10 +520,11 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       // Past the hook's cleanup the native entry is gone; the call would fail
       // defined (handled=false) but it is the last driver.ui path that still
       // crosses into native after the tombstone. Guard it like the rest.
-      if (disposed.value !== 0) return presentation.value;
-      const values = cancelAnimationHostFunction(driverId, animationId, behavior === 'target' ? 1 : 0);
-      if (values.length < 8 || values[0] !== 1) return presentation.value;
-      const current = presentationFromNative(values, presentation.value, 1);
+      const fallback = canonicalizeClipPresentation(presentation.value) ?? initialPresentation;
+      if (disposed.value !== 0) return fallback;
+      const values = PRESENTATION_PROTOCOL_VERSION === 2 && cancelAnimationV2HostFunction ? cancelAnimationV2HostFunction(driverId, animationId, behavior === 'target' ? 1 : 0) : cancelAnimationHostFunction(driverId, animationId, behavior === 'target' ? 1 : 0);
+      if (values.length < 8 || values[0] !== 1) return fallback;
+      const current = presentationFromNative(values, fallback, 1);
       activeAnimationId.value = 0;
       ownership.value = INTERACTIVE;
       scalarsStale.value = 0;
@@ -316,6 +553,12 @@ export function useSmoothClipDriver(initialValue, options = {}) {
           if (isRNRuntime()) return uiOnly();
           setScalarsOnUI(x, y, width, height, radius, contentTranslateX, contentTranslateY);
         },
+        setPresentationScalars(x, y, width, height, topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius, nextCurveCode, contentTranslateX, contentTranslateY, contentScale) {
+          'worklet';
+
+          if (isRNRuntime()) return uiOnly();
+          setPresentationScalarsOnUI(x, y, width, height, topLeftRadius, topRightRadius, bottomRightRadius, bottomLeftRadius, nextCurveCode, contentTranslateX, contentTranslateY, contentScale);
+        },
         animateTo(target, animation) {
           'worklet';
 
@@ -391,6 +634,13 @@ export function useSmoothClipDriver(initialValue, options = {}) {
           });
           return promise;
         }
+      },
+      __smoothClipHandle: {
+        driverId,
+        presentation,
+        ownership,
+        activeAnimationId,
+        disposed
       }
     };
     setDriverState(driver, createDriverState(driverId, initialPresentation, presentation, callbackRef, activeAnimationId, ownership));
@@ -413,7 +663,7 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       synchronizeNativeCompletion(activeAnimationId, ownership, result.animationId, result.finished);
       completeNativeAnimation(driverId, result.animationId, result.finished);
     });
-    scheduleOnUI((source, listenerId, nativeDriverId, owner, suppressed, active, stale, gone, setter) => {
+    scheduleOnUI((source, listenerId, nativeDriverId, owner, suppressed, active, stale, gone, setter, setterV2, protocolVersion) => {
       'worklet';
 
       // First, before the listener or the seed: this effect run owns the
@@ -422,7 +672,8 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       gone.value = 0;
       let last = null;
       const deliver = next => {
-        if (!isFiniteClipPresentation(next) || clipPresentationEquals(last, next)) {
+        const canonical = canonicalizeClipPresentation(next);
+        if (canonical === null || clipPresentationEquals(last, canonical)) {
           return;
         }
         // Record `last` only for values native has actually observed:
@@ -431,17 +682,27 @@ export function useSmoothClipDriver(initialValue, options = {}) {
         if (owner.value !== INTERACTIVE) return;
         if (suppressed.value > 0) {
           suppressed.value -= 1;
-          last = next;
+          last = canonical;
           return;
         }
-        last = next;
+        if (protocolVersion !== 2 && !isV1Compatible(canonical)) {
+          return;
+        }
+        last = canonical;
         if (stale.value !== 0) stale.value = 0;
         const {
           clip,
           contentTranslateX,
-          contentTranslateY
-        } = next;
-        setter(nativeDriverId, clip.x, clip.y, clip.width, clip.height, clip.radius, contentTranslateX, contentTranslateY, false, false);
+          contentTranslateY,
+          contentScale
+        } = canonical;
+        // Declarative deliveries always record velocity samples — only the
+        // setScalars hot path is gated by the velocityTracking option.
+        if (protocolVersion === 2 && setterV2) {
+          setterV2(nativeDriverId, clip.x, clip.y, clip.width, clip.height, clip.topLeftRadius, clip.topRightRadius, clip.bottomRightRadius, clip.bottomLeftRadius, curveCode(canonical), contentTranslateX, contentTranslateY, contentScale, false, false, true);
+        } else {
+          setter(nativeDriverId, clip.x, clip.y, clip.width, clip.height, clip.radius, contentTranslateX, contentTranslateY, false, false);
+        }
       };
       source.addListener(listenerId, deliver);
       // Authoritative take-ownership seed. Creates the native entry before
@@ -450,15 +711,19 @@ export function useSmoothClipDriver(initialValue, options = {}) {
       // An animation worklet can win the scheduling race and create a latch
       // first; Native ownership then marks that intent as newer, so this
       // passive seed must not clear its active id or replay the target value.
-      const current = source.value;
-      if (owner.value === INTERACTIVE && isFiniteClipPresentation(current)) {
+      const current = canonicalizeClipPresentation(source.value);
+      if (owner.value === INTERACTIVE && current !== null) {
         active.value = 0;
         owner.value = INTERACTIVE;
         stale.value = 0;
         last = current;
-        setter(nativeDriverId, current.clip.x, current.clip.y, current.clip.width, current.clip.height, current.clip.radius, current.contentTranslateX, current.contentTranslateY, true, false);
+        if (protocolVersion === 2 && setterV2) {
+          setterV2(nativeDriverId, current.clip.x, current.clip.y, current.clip.width, current.clip.height, current.clip.topLeftRadius, current.clip.topRightRadius, current.clip.bottomRightRadius, current.clip.bottomLeftRadius, curveCode(current), current.contentTranslateX, current.contentTranslateY, current.contentScale, true, false, true);
+        } else if (isV1Compatible(current)) {
+          setter(nativeDriverId, current.clip.x, current.clip.y, current.clip.width, current.clip.height, current.clip.radius, current.contentTranslateX, current.contentTranslateY, true, false);
+        }
       }
-    }, presentation, driverId, driverId, ownership, suppressDeliveries, activeAnimationId, scalarsStale, disposed, setPresentationHostFunction);
+    }, presentation, driverId, driverId, ownership, suppressDeliveries, activeAnimationId, scalarsStale, disposed, setPresentationHostFunction, setPresentationV2HostFunction, PRESENTATION_PROTOCOL_VERSION);
     return () => {
       subscription.remove();
       rejectDriverRequests(driverId);