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

package/cpp/SmoothClipAnimationCurve.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "SmoothClipRegistry.h"
+#include "SmoothClipSharedGeometry.h"
 
 #include <algorithm>
 #include <array>
@@ -9,9 +10,8 @@
 #include <utility>
 #include <vector>
 
-// Shared animation math for the Android integrator and the iOS CoreAnimation
-// restart paths: frame-clock anchoring, timing curves/remainders, spring
-// continuation, presentation blending and keyframes. Keeping the pure math out
+// Shared animation math for the Android integrator: frame-clock anchoring,
+// timing curves, spring validation, and presentation blending. Keeping the pure math out
 // of the registry translation units also lets the XCTest binary pin every rule
 // below — see ios/tests/SmoothClipAnimationCurveTests.mm.
 namespace smoothclip {
@@ -50,7 +50,7 @@ inline double clamp01(double value) {
 // parallel Reanimated animation by the callback's intra-frame offset for the
 // whole duration. Starts that carry the JS-captured stamp resolve through
 // resolveStartStamp() below and skip this anchor entirely; min() remains for
-// latch flushes and stamp-less callers, where its two branches are exact.
+// pre-ready starts and unstamped callers, where its two branches are exact.
 inline double anchorStartTime(double startedAtS, double frameNowS) {
   return std::min(startedAtS, frameNowS);
 }
@@ -81,7 +81,7 @@ inline StartStamp resolveStartStamp(double jsStampS, double wallNowS) {
   return {wallNowS, false};
 }
 
-// Elapsed fraction of a timing/keyframe animation. A non-positive duration is
+// Elapsed fraction of a timing animation. A non-positive duration is
 // complete on its first frame rather than dividing by zero.
 inline double timingFraction(
     double nowS,
@@ -91,20 +91,7 @@ inline double timingFraction(
   return clamp01((nowS - startedAtS) / durationS);
 }
 
-// --- Timing curve continuation -------------------------------------------
-
-struct CubicBezierPoint {
-  double x;
-  double y;
-};
-
-inline CubicBezierPoint mixBezierPoint(
-    CubicBezierPoint from,
-    CubicBezierPoint to,
-    double progress) {
-  return {from.x + (to.x - from.x) * progress,
-          from.y + (to.y - from.y) * progress};
-}
+// --- Timing curve --------------------------------------------------------
 
 inline double cubicBezierParameterForX(
     double x1,
@@ -141,420 +128,353 @@ inline double cubicBezier(
       3 * inverse * t * t * y2 + t * t * t;
 }
 
-struct TimingRemainder {
-  TimingAnimation animation;
-  double easedProgress;
-  bool representable;
-};
-
-struct TimingContinuation {
-  Presentation start;
-  TimingAnimation animation;
-};
+// --- Presentation channels ------------------------------------------------
 
-// Exact right-hand segment of a CSS/CoreAnimation cubic Bezier after a raw
-// time cutoff. Restarting the original controls from a frozen presentation
-// resets its slope and creates a visible velocity cusp. De Casteljau splitting
-// preserves the original curve; normalizing the right segment to (0,0)->(1,1)
-// makes it directly reusable with a shorter BasicAnimation/integrator run.
-inline TimingRemainder timingRemainder(
-    const TimingAnimation &original,
-    double rawProgress) {
-  const double progress = clamp01(rawProgress);
-  if (progress <= 0) return {original, 0, true};
-  if (progress >= 1) {
-    TimingAnimation complete = original;
-    complete.durationMs = 0;
-    complete.controlPoint1X = 0;
-    complete.controlPoint1Y = 0;
-    complete.controlPoint2X = 1;
-    complete.controlPoint2Y = 1;
-    return {complete, 1, true};
-  }
+// The first eleven channels are geometry/content; the final eight are shadow.
+// Curve and shadow presence are categorical and stay outside the scalar array.
+constexpr std::size_t kBaseChannelCount = 11;
+constexpr std::size_t kChannelCount = 19;
+using Channels = std::array<double, kChannelCount>;
 
-  const double t = cubicBezierParameterForX(
-      original.controlPoint1X, original.controlPoint2X, progress, 30);
-  const CubicBezierPoint p0{0, 0};
-  const CubicBezierPoint p1{
-      original.controlPoint1X, original.controlPoint1Y};
-  const CubicBezierPoint p2{
-      original.controlPoint2X, original.controlPoint2Y};
-  const CubicBezierPoint p3{1, 1};
-  const CubicBezierPoint a = mixBezierPoint(p0, p1, t);
-  const CubicBezierPoint b = mixBezierPoint(p1, p2, t);
-  const CubicBezierPoint c = mixBezierPoint(p2, p3, t);
-  const CubicBezierPoint d = mixBezierPoint(a, b, t);
-  const CubicBezierPoint e = mixBezierPoint(b, c, t);
-  const CubicBezierPoint split = mixBezierPoint(d, e, t);
-
-  TimingAnimation remainder = original;
-  remainder.durationMs = original.durationMs * (1 - progress);
-  const double remainingX = 1 - split.x;
-  const double remainingY = 1 - split.y;
-  // A curve whose y reaches exactly 1 before its time endpoint and later
-  // departs cannot be represented as one endpoint-normalized BasicAnimation.
-  // Keep the result finite; ordinary monotone easings never take this branch.
-  if (std::abs(remainingX) <= 1e-12 || std::abs(remainingY) <= 1e-12) {
-    remainder.controlPoint1X = 0;
-    remainder.controlPoint1Y = 0;
-    remainder.controlPoint2X = 1;
-    remainder.controlPoint2Y = 1;
-    return {remainder, split.y, false};
-  }
-  remainder.controlPoint1X = (e.x - split.x) / remainingX;
-  remainder.controlPoint1Y = (e.y - split.y) / remainingY;
-  remainder.controlPoint2X = (c.x - split.x) / remainingX;
-  remainder.controlPoint2Y = (c.y - split.y) / remainingY;
-  return {remainder, split.y, true};
+inline double resolvedRadius(double overrideValue, double shorthand) {
+  return std::isfinite(overrideValue) ? overrideValue : shorthand;
 }
 
-// --- Spring continuation --------------------------------------------------
-
-struct NormalizedSpringState {
-  // Remaining fraction of the original from->target displacement.
-  double remaining;
-  // Derivative of `remaining` in units per second.
-  double velocity;
-};
-
-// Closed-form state of the same mass/spring/damper equation CoreAnimation
-// evaluates. If p is animation progress, remaining=1-p starts at 1 and its
-// derivative starts at -initialVelocity.
-inline NormalizedSpringState normalizedSpringState(
-    const SpringAnimation &spring,
-    double elapsedS) {
-  if (!std::isfinite(elapsedS) || elapsedS <= 0) {
-    return {1, -spring.initialVelocity};
-  }
-  const double mass = spring.mass;
-  const double stiffness = spring.stiffness;
-  const double damping = spring.damping;
-  const double initialVelocity = spring.initialVelocity;
-  if (!std::isfinite(mass) || !std::isfinite(stiffness) ||
-      !std::isfinite(damping) || !std::isfinite(initialVelocity) ||
-      mass <= 0 || stiffness <= 0 || damping < 0) {
-    return {1, 0};
-  }
-
-  const double alpha = damping / (2 * mass);
-  const double omegaSquared = stiffness / mass;
-  const double discriminant = alpha * alpha - omegaSquared;
-  const double criticalScale = std::max(1.0, omegaSquared);
-  if (std::abs(discriminant) <= 1e-12 * criticalScale) {
-    const double coefficient = alpha - initialVelocity;
-    const double decay = std::exp(-alpha * elapsedS);
-    const double remaining = decay * (1 + coefficient * elapsedS);
-    const double velocity = decay *
-        (coefficient - alpha * (1 + coefficient * elapsedS));
-    return {remaining, velocity};
-  }
-  if (discriminant < 0) {
-    const double omega = std::sqrt(-discriminant);
-    const double coefficient = (alpha - initialVelocity) / omega;
-    const double angle = omega * elapsedS;
-    const double cosine = std::cos(angle);
-    const double sine = std::sin(angle);
-    const double basis = cosine + coefficient * sine;
-    const double basisVelocity =
-        -omega * sine + coefficient * omega * cosine;
-    const double decay = std::exp(-alpha * elapsedS);
-    return {decay * basis, decay * (basisVelocity - alpha * basis)};
-  }
-
-  const double root = std::sqrt(discriminant);
-  const double firstRate = -alpha + root;
-  const double secondRate = -alpha - root;
-  const double firstCoefficient =
-      (-initialVelocity - secondRate) / (firstRate - secondRate);
-  const double secondCoefficient = 1 - firstCoefficient;
-  const double first = firstCoefficient * std::exp(firstRate * elapsedS);
-  const double second = secondCoefficient * std::exp(secondRate * elapsedS);
-  return {first + second, firstRate * first + secondRate * second};
+inline bool radiiAreUniform(
+    double topLeft,
+    double topRight,
+    double bottomRight,
+    double bottomLeft) {
+  return topLeft == topRight && topLeft == bottomRight &&
+      topLeft == bottomLeft;
 }
 
-// CASpringAnimation.initialVelocity is normalized by the current remaining
-// distance. Re-expressing the old physical velocity against the frozen
-// current->target displacement preserves the derivative at a re-latch seam.
-inline double springContinuationVelocity(
-    const SpringAnimation &spring,
-    double elapsedS) {
-  const NormalizedSpringState state = normalizedSpringState(spring, elapsedS);
-  if (!std::isfinite(state.remaining) || !std::isfinite(state.velocity) ||
-      std::abs(state.remaining) <= 1e-9) {
-    return 0;
-  }
-  const double result = -state.velocity / state.remaining;
-  return std::isfinite(result) ? result : 0;
-}
-
-// --- Presentation channels ------------------------------------------------
-
-constexpr std::size_t kChannelCount = 7;
-using Channels = std::array<double, kChannelCount>;
-
 inline Channels toChannels(const Presentation &presentation) {
+  const double topLeft = resolvedRadius(
+      presentation.clip.topLeftRadius, presentation.clip.radius);
+  const double topRight = resolvedRadius(
+      presentation.clip.topRightRadius, presentation.clip.radius);
+  const double bottomRight = resolvedRadius(
+      presentation.clip.bottomRightRadius, presentation.clip.radius);
+  const double bottomLeft = resolvedRadius(
+      presentation.clip.bottomLeftRadius, presentation.clip.radius);
   return {presentation.clip.x,
           presentation.clip.y,
           presentation.clip.width,
           presentation.clip.height,
-          presentation.clip.radius,
+          topLeft,
+          topRight,
+          bottomRight,
+          bottomLeft,
           presentation.contentTranslateX,
-          presentation.contentTranslateY};
+          presentation.contentTranslateY,
+          presentation.contentScale,
+          presentation.shadow.red,
+          presentation.shadow.green,
+          presentation.shadow.blue,
+          presentation.shadow.alpha,
+          presentation.shadow.offsetX,
+          presentation.shadow.offsetY,
+          presentation.shadow.blurRadius,
+          presentation.shadow.spreadDistance};
 }
 
-inline Presentation fromChannels(const Channels &channels) {
-  return Presentation{
-      {channels[0], channels[1], channels[2], channels[3], channels[4]},
-      channels[5],
-      channels[6]};
+// --- Animation validation ---------------------------------------------------
+//
+// Keep the invariants at the native ownership boundary as well as in JS. OTA
+// callers and direct host-function users can bypass the TypeScript preflight;
+// rejecting here prevents an invalid request from dissolving an existing
+// animation group before the registry notices it cannot install the new plan.
+
+inline bool isSupportedCurve(ClipCurve curve) {
+  return curve == ClipCurve::Circular || curve == ClipCurve::Continuous;
 }
 
-inline Presentation interpolate(
-    const Presentation &from,
-    const Presentation &to,
-    double progress) {
-  const auto mix = [progress](double start, double end) {
-    return start + (end - start) * progress;
-  };
-  return Presentation{
-      {mix(from.clip.x, to.clip.x),
-       mix(from.clip.y, to.clip.y),
-       mix(from.clip.width, to.clip.width),
-       mix(from.clip.height, to.clip.height),
-       mix(from.clip.radius, to.clip.radius)},
-      mix(from.contentTranslateX, to.contentTranslateX),
-      mix(from.contentTranslateY, to.contentTranslateY)};
+inline bool isFinitePresentation(
+    const Presentation &presentation) {
+  const Channels channels = toChannels(presentation);
+  return std::all_of(
+             channels.begin(), channels.end(),
+             [](double value) { return std::isfinite(value); }) &&
+      isSupportedCurve(presentation.clip.curve) &&
+      presentation.contentScale > 0 &&
+      presentation.shadow.red >= 0 && presentation.shadow.red <= 1 &&
+      presentation.shadow.green >= 0 && presentation.shadow.green <= 1 &&
+      presentation.shadow.blue >= 0 && presentation.shadow.blue <= 1 &&
+      presentation.shadow.alpha >= 0 && presentation.shadow.alpha <= 1 &&
+      presentation.shadow.blurRadius >= 0;
 }
 
-// Freezes a timing animation at one already-rendered raw-time phase and
-// returns the exact right-hand Bezier segment. Keeping the presentation and
-// residual curve in one helper prevents lifecycle code from sampling one
-// timestamp for the geometry and another for the duration.
-inline TimingContinuation timingContinuation(
-    const TimingAnimation &original,
-    const Presentation &start,
-    const Presentation &target,
-    double rawProgress) {
-  const TimingRemainder remainder = timingRemainder(original, rawProgress);
-  return {
-      interpolate(start, target, remainder.easedProgress),
-      remainder.animation};
+/** Canonicalizes registry geometry without consulting any attached host. */
+inline bool canonicalizePresentation(Presentation &presentation) {
+  if (!isFinitePresentation(presentation)) return false;
+  CanonicalClip clip;
+  if (!SmoothClipCanonicalize(presentation.clip, clip)) return false;
+  presentation.clip = SmoothClipGeometry(clip);
+  return true;
 }
 
-// Android lifecycle callbacks can arrive long after the frame whose
-// presentation was actually delivered. Keep the clock inputs at this shared
-// boundary so callers cannot accidentally trim from callback wall time while
-// calculating geometry from the last rendered frame.
-inline TimingContinuation timingContinuationAtFrame(
-    const TimingAnimation &original,
-    const Presentation &start,
-    const Presentation &target,
-    double lastRenderedS,
-    double startedAtS,
-    double durationS) {
-  return timingContinuation(
-      original,
-      start,
-      target,
-      timingFraction(lastRenderedS, startedAtS, durationS));
+inline bool presentationsEqual(
+    const Presentation &first,
+    const Presentation &second) {
+  return first.clip.curve == second.clip.curve &&
+      first.shadow.enabled == second.shadow.enabled &&
+      toChannels(first) == toChannels(second);
 }
 
-// --- Keyframe curve -------------------------------------------------------
+inline bool hasVisibleShadow(const Presentation &presentation) {
+  return presentation.shadow.enabled && presentation.shadow.alpha > 0 &&
+      presentation.clip.width > 0 && presentation.clip.height > 0;
+}
 
-// Keyframes sampled from a smooth path, evaluated with monotone cubic Hermite
-// interpolation (Fritsch-Carlson).
-//
-// Straight lerping between keyframes is exact at every keyframe and wrong in
-// between in a way that matters more than its position error suggests: the
-// interpolated VELOCITY is a staircase that steps at every keyframe boundary,
-// beside content whose Reanimated curve is continuous. Consumers bake dozens of
-// keyframes precisely because their geometry path is not affine in progress, so
-// reconstructing that path smoothly is the honest reading of their intent.
-//
-// Monotone rather than plain Catmull-Rom because the alternative can overshoot,
-// and these channels do not tolerate it: width, height and radius must never
-// dip below zero or bulge past the values the consumer asked for. The
-// Fritsch-Carlson tangent clamp keeps every segment inside the range of its own
-// endpoints. Two keyframes degenerate to the old straight line (both tangents
-// equal the secant) — equal in real arithmetic, within one ulp (~1e-13 of the
-// travel) in doubles because the Hermite blend orders its operations
-// differently than the lerp it replaced. The jfloat delivery cast erases the
-// difference long before a pixel could see it.
-//
-// PARITY NOTE: iOS builds a CAKeyframeAnimation with `kCAAnimationLinear`
-// (SmoothClipView.mm) and cannot run this evaluator — CoreAnimation interpolates
-// off-thread. The platforms therefore differ mid-segment by the linearization
-// error this removes, sub-pixel at any realistic keyframe density and zero at
-// every keyframe. Closing it needs either `kCAAnimationCubic` (a different
-// spline that CAN overshoot, so no) or resampling the keyframes densely through
-// this curve before handing them to CA.
-class KeyframeCurve {
- public:
-  void reset(std::vector<Keyframe> frames) {
-    frames_ = std::move(frames);
-    cursor_ = 1;
-    tangents_.assign(frames_.size(), Channels{});
-    const std::size_t count = frames_.size();
-    if (count < 2) return;
-
-    // Secant slope of every segment, per channel. A non-increasing offset pair
-    // (the re-latch remap can produce one) contributes no slope rather than
-    // dividing by zero; evaluate() short-circuits those segments too.
-    std::vector<Channels> secants(count - 1);
-    for (std::size_t index = 0; index + 1 < count; index += 1) {
-      const double span = frames_[index + 1].offset - frames_[index].offset;
-      const Channels lower = toChannels(frames_[index].presentation);
-      const Channels upper = toChannels(frames_[index + 1].presentation);
-      for (std::size_t channel = 0; channel < kChannelCount; channel += 1) {
-        secants[index][channel] =
-            span > 0 ? (upper[channel] - lower[channel]) / span : 0.0;
-      }
-    }
+inline bool isAutonomousUniformCircular(
+    const Presentation &presentation) {
+  const Geometry &clip = presentation.clip;
+  return clip.curve == ClipCurve::Circular && radiiAreUniform(
+      resolvedRadius(clip.topLeftRadius, clip.radius),
+      resolvedRadius(clip.topRightRadius, clip.radius),
+      resolvedRadius(clip.bottomRightRadius, clip.radius),
+      resolvedRadius(clip.bottomLeftRadius, clip.radius));
+}
 
-    // One-sided at the ends, averaged inside.
-    for (std::size_t channel = 0; channel < kChannelCount; channel += 1) {
-      tangents_[0][channel] = secants[0][channel];
-      tangents_[count - 1][channel] = secants[count - 2][channel];
-      for (std::size_t index = 1; index + 1 < count; index += 1) {
-        tangents_[index][channel] =
-            (secants[index - 1][channel] + secants[index][channel]) / 2.0;
-      }
-    }
+/**
+ * Makes shadow appearance/disappearance a pure alpha fade. A disabled or
+ * transparent endpoint borrows the visible endpoint's style while retaining
+ * its own geometry, so path, blur, spread, and offset do not collapse during
+ * the fade. The public target remains unchanged in the registry; these copies
+ * are animation inputs only.
+ */
+inline std::pair<Presentation, Presentation> normalizeShadowEndpoints(
+    Presentation from,
+    Presentation to) {
+  const bool fromVisible = hasVisibleShadow(from);
+  const bool toVisible = hasVisibleShadow(to);
+  if (!fromVisible) from.shadow.alpha = 0;
+  if (!toVisible) to.shadow.alpha = 0;
+  if (fromVisible == toVisible) return {from, to};
+
+  Shadow &invisible = fromVisible ? to.shadow : from.shadow;
+  const Shadow &visible = fromVisible ? from.shadow : to.shadow;
+  invisible = visible;
+  invisible.enabled = true;
+  invisible.alpha = 0;
+  return {from, to};
+}
 
-    // Fritsch-Carlson clamp: this is what makes the curve non-overshooting.
-    for (std::size_t index = 0; index + 1 < count; index += 1) {
-      for (std::size_t channel = 0; channel < kChannelCount; channel += 1) {
-        const double secant = secants[index][channel];
-        if (secant == 0.0) {
-          // Flat segment: pin both ends flat so the curve cannot bulge off a
-          // pair of equal keyframes.
-          tangents_[index][channel] = 0.0;
-          tangents_[index + 1][channel] = 0.0;
-          continue;
-        }
-        double alpha = tangents_[index][channel] / secant;
-        double beta = tangents_[index + 1][channel] / secant;
-        if (alpha < 0.0) {
-          tangents_[index][channel] = 0.0;
-          alpha = 0.0;
-        }
-        if (beta < 0.0) {
-          tangents_[index + 1][channel] = 0.0;
-          beta = 0.0;
-        }
-        const double magnitude = alpha * alpha + beta * beta;
-        if (magnitude > 9.0) {
-          const double scale = 3.0 / std::sqrt(magnitude);
-          tangents_[index][channel] = scale * alpha * secant;
-          tangents_[index + 1][channel] = scale * beta * secant;
-        }
-      }
-    }
-  }
+inline bool isValidReduceMotionCode(int32_t value) {
+  return value >= 0 && value <= 2;
+}
 
-  const std::vector<Keyframe> &frames() const { return frames_; }
-  std::size_t size() const { return frames_.size(); }
-  bool usable() const { return frames_.size() >= 2; }
-
-  Presentation evaluate(double progress) {
-    const std::size_t count = frames_.size();
-    if (count == 0) return Presentation{{0, 0, 0, 0, 0}, 0, 0};
-    if (count == 1) return frames_[0].presentation;
-
-    // The scan resumes from the previous segment instead of restarting at 1.
-    // Progress is monotonic within an animation, so this is O(1) amortized
-    // where the old restart-every-frame scan was O(keyframes) per frame; the
-    // backward walk keeps it correct if progress ever moves the other way.
-    std::size_t upper = std::min(std::max<std::size_t>(cursor_, 1), count - 1);
-    while (upper > 1 && progress < frames_[upper - 1].offset) upper -= 1;
-    while (upper < count - 1 && progress > frames_[upper].offset) upper += 1;
-    cursor_ = upper;
-
-    const Keyframe &lower = frames_[upper - 1];
-    const Keyframe &higher = frames_[upper];
-    const double span = higher.offset - lower.offset;
-    if (span <= 0) return higher.presentation;
-
-    const double t = clamp01((progress - lower.offset) / span);
-    const double t2 = t * t;
-    const double t3 = t2 * t;
-    // Cubic Hermite basis.
-    const double h00 = 2 * t3 - 3 * t2 + 1;
-    const double h10 = t3 - 2 * t2 + t;
-    const double h01 = -2 * t3 + 3 * t2;
-    const double h11 = t3 - t2;
-
-    const Channels from = toChannels(lower.presentation);
-    const Channels to = toChannels(higher.presentation);
-    const Channels &fromSlope = tangents_[upper - 1];
-    const Channels &toSlope = tangents_[upper];
-    Channels blended{};
-    for (std::size_t channel = 0; channel < kChannelCount; channel += 1) {
-      blended[channel] = h00 * from[channel] +
-          h10 * span * fromSlope[channel] + h01 * to[channel] +
-          h11 * span * toSlope[channel];
-    }
-    return fromChannels(blended);
-  }
+inline bool isValidTiming(const TimingAnimation &animation) {
+  return std::isfinite(animation.durationMs) && animation.durationMs >= 0 &&
+      std::isfinite(animation.controlPoint1X) &&
+      std::isfinite(animation.controlPoint1Y) &&
+      std::isfinite(animation.controlPoint2X) &&
+      std::isfinite(animation.controlPoint2Y) &&
+      animation.controlPoint1X >= 0 && animation.controlPoint1X <= 1 &&
+      animation.controlPoint2X >= 0 && animation.controlPoint2X <= 1 &&
+      isValidReduceMotionCode(animation.reduceMotion);
+}
 
- private:
-  std::vector<Keyframe> frames_;
-  std::vector<Channels> tangents_;
-  std::size_t cursor_ = 1;
-};
+inline bool isValidSpring(const SpringAnimation &animation) {
+  return std::isfinite(animation.mass) && animation.mass > 0 &&
+      std::isfinite(animation.stiffness) && animation.stiffness > 0 &&
+      std::isfinite(animation.damping) && animation.damping >= 0 &&
+      std::isfinite(animation.initialVelocity) &&
+      std::isfinite(animation.energyThreshold) &&
+      animation.energyThreshold > 0 &&
+      isValidReduceMotionCode(animation.reduceMotion);
+}
 
-struct KeyframeContinuation {
-  Presentation start;
-  std::vector<Keyframe> frames;
-  double durationMs;
+struct ScalarSpringState {
+  double position;
+  double velocity;
 };
 
-// Trims keyframes at the same raw-time phase that produced `frozen`. The new
-// zero frame is the rendered presentation, not an analytically re-sampled
-// neighbor, so a pause/re-latch cannot jump at the seam. Strictly increasing
-// remapped offsets avoid duplicate/division-by-zero segments after repeated
-// trims or floating-point collisions near the cutoff.
-inline KeyframeContinuation keyframeContinuation(
-    const std::vector<Keyframe> &frames,
-    const Presentation &frozen,
+/** One analytic Reanimated-compatible spring step for normalized progress. */
+inline ScalarSpringState advanceScalarSpring(
+    ScalarSpringState state,
+    const SpringAnimation &animation,
+    double deltaTimeS) {
+  const double dt = std::clamp(deltaTimeS, 0.0, 0.064);
+  if (dt == 0) return state;
+  const double omega0 = std::sqrt(animation.stiffness / animation.mass);
+  const double zeta = animation.damping /
+      (2.0 * std::sqrt(animation.stiffness * animation.mass));
+  const double displacement = state.position - 1.0;
+  const double velocity = state.velocity;
+  if (zeta < 1.0) {
+    const double omega1 = omega0 * std::sqrt(1.0 - zeta * zeta);
+    const double envelope = std::exp(-zeta * omega0 * dt);
+    const double sinTerm = std::sin(omega1 * dt);
+    const double cosTerm = std::cos(omega1 * dt);
+    const double coefficient =
+        (velocity + zeta * omega0 * displacement) / omega1;
+    const double nextDisplacement =
+        envelope * (displacement * cosTerm + coefficient * sinTerm);
+    const double nextVelocity = envelope *
+        (velocity * (cosTerm - zeta * omega0 / omega1 * sinTerm) -
+         displacement * (omega0 * omega0 / omega1) * sinTerm);
+    return {1.0 + nextDisplacement, nextVelocity};
+  }
+
+  // Reanimated deliberately uses its critical branch for zeta >= 1.
+  const double envelope = std::exp(-omega0 * dt);
+  const double coefficient = velocity + omega0 * displacement;
+  const double nextDisplacement =
+      envelope * (displacement + coefficient * dt);
+  const double nextVelocity =
+      envelope * (velocity - omega0 * coefficient * dt);
+  return {1.0 + nextDisplacement, nextVelocity};
+}
+
+inline double relativeSpringEnergy(
+    ScalarSpringState state,
+    const SpringAnimation &animation) {
+  const double displacement = state.position - 1.0;
+  const double currentEnergy =
+      animation.mass * state.velocity * state.velocity +
+      animation.stiffness * displacement * displacement;
+  const double initialEnergy =
+      animation.mass * animation.initialVelocity * animation.initialVelocity +
+      animation.stiffness;
+  return currentEnergy / initialEnergy;
+}
+
+inline bool springScaleStaysPositive(
+    const Presentation &start,
     const Presentation &target,
-    double durationMs,
-    double rawProgress) {
-  const double progress = clamp01(rawProgress);
-  KeyframeContinuation result{
-      frozen, {{0.0, frozen}}, std::max(0.0, durationMs * (1 - progress))};
-  if (progress < 1.0) {
-    for (const Keyframe &frame : frames) {
-      if (frame.offset <= progress) continue;
-      const double offset = clamp01(
-          (frame.offset - progress) / (1 - progress));
-      if (offset <= result.frames.back().offset + 1e-12) continue;
-      result.frames.push_back({offset, frame.presentation});
+    const SpringAnimation &animation,
+    double initialVelocity) {
+  if (start.contentScale == target.contentScale) return true;
+  if (!std::isfinite(initialVelocity)) return false;
+
+  const double startScale = start.contentScale;
+  const double targetScale = target.contentScale;
+  const double delta = targetScale - startScale;
+  const auto scaleForDisplacement = [&](double displacement) {
+    // displacement is q = progress - 1, so scale = target + delta*q.
+    return targetScale + delta * displacement;
+  };
+  if (startScale <= 0 || targetScale <= 0) return false;
+
+  const double naturalFrequency =
+      std::sqrt(animation.stiffness / animation.mass);
+  const double decay = animation.damping / (2 * animation.mass);
+  const double discriminant = decay * decay -
+      naturalFrequency * naturalFrequency;
+  constexpr double epsilon = 1e-12;
+  constexpr double pi = 3.14159265358979323846;
+
+  const auto isPositiveAt = [&](double time, double displacement) {
+    return time <= epsilon || scaleForDisplacement(displacement) > 0;
+  };
+
+  if (discriminant < -epsilon) {
+    const double frequency = std::sqrt(-discriminant);
+    const double a = -1;
+    const double b = (initialVelocity - decay) / frequency;
+    const double derivativeCos = initialVelocity;
+    const double derivativeSin = frequency - decay * b;
+    double phase = std::atan2(-derivativeCos, derivativeSin);
+    while (phase <= epsilon) phase += pi;
+    // Extrema alternate and their envelope only decays, so the first two
+    // positive extrema cover both signs and therefore the global minimum.
+    for (int index = 0; index < 2; index += 1) {
+      const double time = phase / frequency;
+      const double displacement = std::exp(-decay * time) *
+          (a * std::cos(phase) + b * std::sin(phase));
+      if (!isPositiveAt(time, displacement)) return false;
+      phase += pi;
     }
+    return true;
+  }
+
+  if (std::abs(discriminant) <= epsilon) {
+    const double b = initialVelocity - decay;
+    const double denominator = decay * b;
+    if (std::abs(denominator) <= epsilon) return true;
+    const double time = initialVelocity / denominator;
+    if (time <= epsilon) return true;
+    const double displacement = std::exp(-decay * time) * (-1 + b * time);
+    return isPositiveAt(time, displacement);
   }
-  if (result.frames.size() == 1 ||
-      result.frames.back().offset < 1.0 - 1e-12) {
-    result.frames.push_back({1.0, target});
-  } else {
-    result.frames.back().offset = 1.0;
-    result.frames.back().presentation = target;
+
+  const double root = std::sqrt(discriminant);
+  const double slow = -decay + root;
+  const double fast = -decay - root;
+  const double slowCoefficient =
+      (initialVelocity + fast) / (slow - fast);
+  const double fastCoefficient = -1 - slowCoefficient;
+  const double numerator = -fastCoefficient * fast;
+  const double denominator = slowCoefficient * slow;
+  if (std::abs(denominator) <= epsilon || numerator / denominator <= 0) {
+    return true;
   }
-  return result;
+  const double time =
+      std::log(numerator / denominator) / (slow - fast);
+  if (time <= epsilon) return true;
+  const double displacement = slowCoefficient * std::exp(slow * time) +
+      fastCoefficient * std::exp(fast * time);
+  return isPositiveAt(time, displacement);
 }
 
-inline KeyframeContinuation keyframeContinuationAtFrame(
-    const std::vector<Keyframe> &frames,
-    const Presentation &frozen,
-    const Presentation &target,
-    double lastRenderedS,
-    double startedAtS,
-    double durationS) {
-  return keyframeContinuation(
-      frames,
-      frozen,
-      target,
-      std::max(0.0, durationS * 1000.0),
-      timingFraction(lastRenderedS, startedAtS, durationS));
+inline Presentation fromChannels(
+    const Channels &channels,
+    ClipCurve curve = ClipCurve::Circular,
+    bool shadowEnabled = false) {
+  Geometry geometry{
+      channels[0], channels[1], channels[2], channels[3], 0.0};
+  geometry.topLeftRadius = channels[4];
+  geometry.topRightRadius = channels[5];
+  geometry.bottomRightRadius = channels[6];
+  geometry.bottomLeftRadius = channels[7];
+  geometry.radius = radiiAreUniform(
+      channels[4], channels[5], channels[6], channels[7])
+      ? channels[4]
+      : 0.0;
+  geometry.curve = curve;
+  Shadow shadow{
+      shadowEnabled,
+      std::clamp(channels[11], 0.0, 1.0),
+      std::clamp(channels[12], 0.0, 1.0),
+      std::clamp(channels[13], 0.0, 1.0),
+      std::clamp(channels[14], 0.0, 1.0),
+      channels[15],
+      channels[16],
+      std::max(0.0, channels[17]),
+      channels[18]};
+  return Presentation{
+      geometry, channels[8], channels[9], channels[10], shadow};
+}
+
+inline Presentation interpolate(
+    const Presentation &from,
+    const Presentation &to,
+    double progress) {
+  const auto mix = [progress](double start, double end) {
+    return start + (end - start) * progress;
+  };
+  Channels blended{};
+  const auto normalized = normalizeShadowEndpoints(from, to);
+  const Channels fromChannelsValue = toChannels(normalized.first);
+  const Channels toChannelsValue = toChannels(normalized.second);
+  const bool rendersShadow = hasVisibleShadow(from) || hasVisibleShadow(to);
+  const std::size_t channelCount =
+      rendersShadow ? kChannelCount : kBaseChannelCount;
+  for (std::size_t index = 0; index < channelCount; index += 1) {
+    blended[index] = mix(fromChannelsValue[index], toChannelsValue[index]);
+  }
+  if (!rendersShadow) {
+    std::copy(
+        fromChannelsValue.begin() + kBaseChannelCount,
+        fromChannelsValue.end(),
+        blended.begin() + kBaseChannelCount);
+  }
+  const bool shadowEnabled = progress >= 1
+      ? to.shadow.enabled
+      : rendersShadow;
+  return fromChannels(blended, from.clip.curve, shadowEnabled);
 }
 
 } // namespace smoothclip