pythonnative 0.21.0__py3-none-any.whl → 0.22.0__py3-none-any.whl

pythonnative/animated.py

@@ -1,10 +1,11 @@
-"""Animated values + animation drivers + animated component wrappers.
+"""Animated values, native-driven animation, and animated components.
 
-Modeled on React Native's ``Animated`` API but with an
-``async``-aware completion contract. The core primitives are:
+Modeled on React Native's ``Animated`` API with an ``async``-aware
+completion contract. The core primitives are:
 
 - [`AnimatedValue`][pythonnative.animated.AnimatedValue]: a numeric
-  cell with subscribers; animations mutate it over time.
+  cell attached to native view properties; animations drive it over
+  time.
 - ``Animated.timing`` / ``Animated.spring`` / ``Animated.decay``:
   animation factories. The objects they return implement
   ``__await__``, so you can write ``await Animated.timing(v, to=1.0)``
@@ -14,14 +15,24 @@ Modeled on React Native's ``Animated`` API but with an
 - ``Animated.View`` / ``Animated.Text`` / ``Animated.Image``:
   components whose ``style`` may contain ``AnimatedValue`` instances.
 
-Driver:
-
-- A single background thread ticks at ~60 Hz, advancing every active
-  animation by ``dt``.
-- Animations expose two APIs:
-  - ``handle.start()`` — fire-and-forget. Returns ``self``.
-  - ``await handle`` (or ``await handle.run()``) — wait for the
-    animation to complete; cancellation cancels the animation.
+Driver architecture (the **native driver**):
+
+When an animation starts, PythonNative compiles its spec (curve,
+duration, target value) and offers it to the platform handler of every
+native view the value is attached to
+([`ViewHandler.start_animation`][pythonnative.native_views.base.ViewHandler.start_animation]).
+
+- **Accepted** (iOS Core Animation, Android ``ViewPropertyAnimator`` /
+  ``DynamicAnimation``): the platform animates the property entirely
+  natively — no Python code runs per frame. Python receives exactly one
+  callback when the animation settles, updates the
+  [`AnimatedValue`][pythonnative.animated.AnimatedValue], and resolves
+  any awaiting tasks.
+- **Declined** (desktop preview, unattached values, callable easings,
+  values feeding Python-side listeners): a single background thread
+  ticks the animation at ~60 Hz from Python, pushing each frame through
+  ``set_animated_property``. Semantics are identical; only the frame
+  source differs.
 
 Example:
     ```python
@@ -48,6 +59,7 @@ Example:
 from __future__ import annotations
 
 import asyncio
+import itertools
 import math
 import threading
 import time
@@ -58,11 +70,13 @@ from .hooks import use_effect, use_ref
 from .runtime import resolve_future
 from .style import StyleProp, resolve_style
 
-# Maximum frame rate at which the Python ticker drives animations.
+# Maximum frame rate at which the Python fallback ticker drives
+# animations (native-driven animations run at the display's refresh
+# rate, managed by the platform).
 _TARGET_FPS = 60.0
 _FRAME_DT = 1.0 / _TARGET_FPS
 
-# Upper bound on how much wall-clock time the animation loop will try to
+# Upper bound on how much wall-clock time the fallback loop will try to
 # catch up on in a single iteration after thread starvation. At 60 fps
 # this is ~333 ms of simulated motion; further drift is dropped to keep
 # the loop responsive.
@@ -98,30 +112,48 @@ def _resolve_easing(name: Any) -> Callable[[float], float]:
     return _EASINGS.get(str(name), _EASINGS["ease_in_out"])
 
 
+def _backend() -> Any:
+    """Return the active native-view registry (the animation backend)."""
+    from .native_views import get_registry
+
+    return get_registry()
+
+
+# Process-unique ids for native animations, so completion callbacks can
+# be routed without holding references on the native side.
+_anim_id_counter = itertools.count(1)
+
+
 # ======================================================================
 # AnimatedValue
 # ======================================================================
 
 
 class AnimatedValue:
-    """A subscribable numeric cell driven by animations.
-
-    Direct mutation via
-    [`set_value`][pythonnative.animated.AnimatedValue.set_value]
-    fires subscribers immediately; animations call ``set_value`` from
-    the ticker thread.
-
-    Subscribers are ``(prop_name, callback)`` tuples. Each animated
-    component (e.g., ``Animated.View``) subscribes once per
-    ``AnimatedValue`` prop in its style during mount.
+    """A numeric cell that can be attached to native view properties.
+
+    Animated components (``Animated.View`` et al.) **attach** the value
+    to ``(tag, prop)`` bindings after mount. Setting the value pushes
+    the new number to every attached native view through the registry's
+    ``set_animated_property`` — and when an animation can be driven
+    natively, the platform animates those same bindings directly.
+
+    Python-side listeners registered via
+    [`add_listener`][pythonnative.animated.AnimatedValue.add_listener]
+    observe every Python-driven change. Natively-driven animations
+    intentionally skip per-frame Python callbacks (that's the point);
+    listeners see the final settled value.
     """
 
-    __slots__ = ("_value", "_subscribers", "_lock")
+    __slots__ = ("_value", "_subscribers", "_attachments", "_lock", "_native_group")
 
     def __init__(self, initial: float = 0.0) -> None:
         self._value = float(initial)
         self._subscribers: List[Tuple[str, Callable[[float], None]]] = []
+        self._attachments: List[Tuple[int, str]] = []
         self._lock = threading.Lock()
+        # The in-flight native animation group driving this value, if any.
+        self._native_group: Optional["_NativeAnimationGroup"] = None
 
     @property
     def value(self) -> float:
@@ -129,23 +161,65 @@ class AnimatedValue:
         return self._value
 
     def set_value(self, new_value: float) -> None:
-        """Set the value immediately and fire all subscribers."""
-        new_value = float(new_value)
+        """Set the value immediately, pushing to native views and listeners."""
+        self._apply(float(new_value), push_native=True)
+
+    def _apply(self, new_value: float, push_native: bool) -> None:
         with self._lock:
             self._value = new_value
             subs = list(self._subscribers)
+            attachments = list(self._attachments)
+        if push_native and attachments:
+            try:
+                backend = _backend()
+                for tag, prop in attachments:
+                    backend.set_animated_property(tag, prop, new_value)
+            except Exception:
+                pass
         for prop, cb in subs:
             try:
                 cb(new_value)
             except Exception:
                 pass
 
+    # -- bindings ------------------------------------------------------
+
+    def attach(self, tag: int, prop: str) -> Callable[[], None]:
+        """Bind this value to ``prop`` of the native view under ``tag``.
+
+        The current value is pushed immediately so the view reflects it
+        even if no animation is running. Returns a detach callable.
+        """
+        binding = (tag, prop)
+        with self._lock:
+            self._attachments.append(binding)
+        try:
+            _backend().set_animated_property(tag, prop, self._value)
+        except Exception:
+            pass
+
+        def _detach() -> None:
+            with self._lock:
+                try:
+                    self._attachments.remove(binding)
+                except ValueError:
+                    pass
+
+        return _detach
+
+    def attachments(self) -> List[Tuple[int, str]]:
+        """Snapshot of the current ``(tag, prop)`` bindings."""
+        with self._lock:
+            return list(self._attachments)
+
+    # -- listeners -----------------------------------------------------
+
     def add_listener(self, prop: str, callback: Callable[[float], None]) -> Callable[[], None]:
-        """Register ``callback`` for changes to this value.
+        """Register ``callback`` for Python-driven changes to this value.
 
-        Returns an unsubscribe callable. ``prop`` is metadata only —
-        it lets the subscriber differentiate this binding from others
-        on the same ``AnimatedValue``.
+        Returns an unsubscribe callable. ``prop`` is metadata only — it
+        lets the subscriber differentiate this binding from others on
+        the same ``AnimatedValue``.
         """
         with self._lock:
             self._subscribers.append((prop, callback))
@@ -159,6 +233,24 @@ class AnimatedValue:
 
         return _unsubscribe
 
+    def has_listeners(self) -> bool:
+        """Whether any Python-side listeners are registered."""
+        with self._lock:
+            return bool(self._subscribers)
+
+    # -- native handoff ------------------------------------------------
+
+    def _adopt_native_group(self, group: Optional["_NativeAnimationGroup"]) -> None:
+        previous = self._native_group
+        self._native_group = group
+        if previous is not None and previous is not group:
+            previous.cancel()
+
+    def stop_animation(self) -> None:
+        """Cancel any in-flight animation on this value (native or Python)."""
+        self._adopt_native_group(None)
+        _manager.cancel_for_value(self)
+
     def __float__(self) -> float:
         return self._value
 
@@ -167,16 +259,16 @@ class AnimatedValue:
 
 
 # ======================================================================
-# Animation driver
+# Python fallback driver
 # ======================================================================
 
 
 class _AnimationManager:
-    """Single-threaded driver for all currently-running animations.
+    """Single-threaded fallback driver for Python-ticked animations.
 
     Holds a list of ``_RunningAnimation`` instances and ticks them at
     ~60 Hz. The thread starts on first use and idles when nothing is
-    active.
+    active. Native-driven animations never touch this loop.
     """
 
     def __init__(self) -> None:
@@ -197,6 +289,15 @@ class _AnimationManager:
             except ValueError:
                 pass
 
+    def cancel_for_value(self, value: AnimatedValue) -> None:
+        """Cancel every queued/running Python-driven animation on ``value``."""
+        with self._lock:
+            stale = [a for a in self._animations if a.value is value]
+            for anim in stale:
+                self._animations.remove(anim)
+        for anim in stale:
+            anim._finish()
+
     def _ensure_thread_locked(self) -> None:
         if self._thread is not None and self._thread.is_alive():
             return
@@ -207,16 +308,16 @@ class _AnimationManager:
         last = time.monotonic()
         # Clamping the per-tick dt is important for numerical stability:
         # an underdamped spring with a 0.3 s step explodes immediately,
-        # and on iOS/Android the animation thread can be starved for
-        # several frames during render bursts. We integrate physics on a
-        # clamped dt (max 2 target frames) and sub-step when wall-clock
-        # has advanced more than that, so the perceived motion still
-        # tracks real time at most a couple of frames behind. After an
-        # extreme starvation (e.g. the app was backgrounded for seconds)
-        # we cap the catch-up at ``_MAX_CATCHUP_FRAMES`` worth of
-        # physics; any further wall-clock drift is dropped on the floor,
-        # which keeps the loop responsive instead of spinning forward
-        # through hundreds of substeps.
+        # and the animation thread can be starved for several frames
+        # during render bursts. We integrate physics on a clamped dt
+        # (max 2 target frames) and sub-step when wall-clock has
+        # advanced more than that, so the perceived motion still tracks
+        # real time at most a couple of frames behind. After an extreme
+        # starvation (e.g. the app was backgrounded for seconds) we cap
+        # the catch-up at ``_MAX_CATCHUP_FRAMES`` worth of physics; any
+        # further wall-clock drift is dropped on the floor, which keeps
+        # the loop responsive instead of spinning forward through
+        # hundreds of substeps.
         max_step = _FRAME_DT * 2.0
         max_catchup = _FRAME_DT * _MAX_CATCHUP_FRAMES
         while not self._stopped:
@@ -249,12 +350,12 @@ _manager = _AnimationManager()
 
 
 # ======================================================================
-# Animation primitives
+# Python-driven animation primitives (the fallback path)
 # ======================================================================
 
 
 class _RunningAnimation:
-    """Base class for in-flight animations; ``advance()`` returns True when done."""
+    """Base class for Python-ticked animations; ``advance()`` returns True when done."""
 
     def __init__(self, value: AnimatedValue) -> None:
         self.value = value
@@ -315,10 +416,11 @@ class _SpringAnimation(_RunningAnimation):
         stiffness: float,
         damping: float,
         mass: float,
+        initial_velocity: float = 0.0,
     ) -> None:
         super().__init__(value)
         self._to = float(to)
-        self._velocity = 0.0
+        self._velocity = float(initial_velocity)
         self._stiffness = float(stiffness)
         self._damping = float(damping)
         self._mass = float(mass)
@@ -368,6 +470,163 @@ class _DelayAnimation(_RunningAnimation):
         return False
 
 
+# ======================================================================
+# Native-driven animation group
+# ======================================================================
+
+
+class _NativeAnimationGroup:
+    """One logical animation fanned out to N natively-animated views.
+
+    Each attached ``(tag, prop)`` binding gets its own ``anim_id``; the
+    group completes when the platform reports completion for all of
+    them. Cancellation asks each platform handler for the current
+    presentation value so the ``AnimatedValue`` lands wherever the view
+    visually was.
+    """
+
+    def __init__(self, value: AnimatedValue, final_value: float) -> None:
+        self.value = value
+        self.final_value = final_value
+        self._targets: Dict[int, Tuple[int, str]] = {}  # anim_id -> (tag, prop)
+        self._pending: set = set()
+        self._completion_futures: List[asyncio.Future[None]] = []
+        self._completed = False
+        self._lock = threading.Lock()
+
+    def add_target(self, anim_id: int, tag: int, prop: str) -> None:
+        with self._lock:
+            self._targets[anim_id] = (tag, prop)
+            self._pending.add(anim_id)
+        _native_groups[anim_id] = self
+
+    def add_completion_future(self, future: asyncio.Future[None]) -> None:
+        with self._lock:
+            done = self._completed
+            if not done:
+                self._completion_futures.append(future)
+        if done:
+            resolve_future(future, None)
+
+    def target_completed(self, anim_id: int, finished: bool) -> None:
+        with self._lock:
+            self._pending.discard(anim_id)
+            remaining = len(self._pending)
+        _native_groups.pop(anim_id, None)
+        if remaining == 0:
+            self._settle(self.final_value if finished else None)
+
+    def cancel(self) -> None:
+        """Cancel all in-flight native animations, syncing to presentation values."""
+        with self._lock:
+            targets = dict(self._targets)
+            self._pending.clear()
+        presentation: Optional[float] = None
+        try:
+            backend = _backend()
+            for anim_id, (tag, _prop) in targets.items():
+                _native_groups.pop(anim_id, None)
+                current = backend.cancel_animation(tag, anim_id)
+                if current is not None:
+                    try:
+                        presentation = float(current)
+                    except (TypeError, ValueError):
+                        pass
+        except Exception:
+            pass
+        self._settle(presentation)
+
+    def _settle(self, end_value: Optional[float]) -> None:
+        with self._lock:
+            if self._completed:
+                return
+            self._completed = True
+            futures = list(self._completion_futures)
+            self._completion_futures.clear()
+        if self.value._native_group is self:
+            self.value._native_group = None
+        if end_value is not None:
+            # The native side already shows this value; update the
+            # Python cell (and listeners) without re-pushing.
+            self.value._apply(end_value, push_native=False)
+        for fut in futures:
+            resolve_future(fut, None)
+
+
+# anim_id -> group, for routing completion callbacks from platform handlers.
+_native_groups: Dict[int, _NativeAnimationGroup] = {}
+
+
+def native_animation_completed(anim_id: int, finished: bool = True) -> None:
+    """Report a natively-driven animation as settled.
+
+    Called by platform handlers from their completion callbacks (iOS
+    ``UIView`` completion blocks, Android ``withEndAction`` /
+    ``DynamicAnimation.OnAnimationEndListener``). Safe to call from any
+    thread; unknown ids are ignored (e.g. an animation cancelled
+    moments before its completion fired).
+
+    Args:
+        anim_id: The id passed to ``ViewHandler.start_animation``.
+        finished: ``False`` when the platform reports the animation was
+            interrupted rather than running to completion.
+    """
+    group = _native_groups.get(anim_id)
+    if group is not None:
+        group.target_completed(anim_id, finished)
+
+
+def _projected_final_value(spec: Dict[str, Any]) -> float:
+    """Compute where an animation will settle, from its spec."""
+    kind = spec.get("kind")
+    if kind == "decay":
+        # v(t) = v0 · e^(−k·1000·t)  ⇒  ∫v dt = v0 / (k·1000)
+        v0 = float(spec.get("velocity", 0.0))
+        k = max(1e-6, float(spec.get("deceleration", 0.997)))
+        return float(spec.get("from", 0.0)) + v0 / (k * 1000.0)
+    return float(spec.get("to", spec.get("from", 0.0)))
+
+
+def _start_native(value: AnimatedValue, spec: Dict[str, Any]) -> Optional[_NativeAnimationGroup]:
+    """Offer ``spec`` to the platform for every binding of ``value``.
+
+    Returns the live group when **all** bindings accepted the native
+    animation; otherwise rolls back any accepted targets and returns
+    ``None`` so the caller falls back to the Python ticker.
+    """
+    targets = value.attachments()
+    if not targets:
+        return None
+    if value.has_listeners():
+        # Python listeners want per-frame values; only the ticker
+        # provides those.
+        return None
+    try:
+        backend = _backend()
+    except Exception:
+        return None
+
+    group = _NativeAnimationGroup(value, _projected_final_value(spec))
+    accepted: List[Tuple[int, int]] = []  # (anim_id, tag)
+    for tag, prop in targets:
+        anim_id = next(_anim_id_counter)
+        try:
+            ok = backend.start_animation(tag, anim_id, prop, spec)
+        except Exception:
+            ok = False
+        if not ok:
+            for prev_id, prev_tag in accepted:
+                _native_groups.pop(prev_id, None)
+                try:
+                    backend.cancel_animation(prev_tag, prev_id)
+                except Exception:
+                    pass
+            return None
+        group.add_target(anim_id, tag, prop)
+        accepted.append((anim_id, tag))
+    return group
+
+
 # ======================================================================
 # Public animation handles
 # ======================================================================
@@ -425,37 +684,66 @@ class _AwaitableAnimation:
 class _AnimationHandle(_AwaitableAnimation):
     """Public handle returned by ``Animated.timing`` / ``.spring`` / ``.decay``.
 
-    Wraps a ``_RunningAnimation`` factory so each ``.start()`` call
-    creates a fresh in-flight animation (matches React Native — the
-    ``Animated.timing`` return value is reusable).
+    Each ``.start()`` call snapshots the value's current state, prefers
+    the native driver, and falls back to a fresh Python-ticked
+    animation otherwise (matches React Native — the ``Animated.timing``
+    return value is reusable).
     """
 
-    def __init__(self, factory: Callable[[], _RunningAnimation]) -> None:
-        self._factory = factory
-        self._current: Optional[_RunningAnimation] = None
+    def __init__(
+        self,
+        value: Optional[AnimatedValue],
+        spec_factory: Callable[[], Dict[str, Any]],
+        fallback_factory: Callable[[], _RunningAnimation],
+        native_eligible: bool = True,
+    ) -> None:
+        self._value = value
+        self._spec_factory = spec_factory
+        self._fallback_factory = fallback_factory
+        self._native_eligible = native_eligible
+        self._python_anim: Optional[_RunningAnimation] = None
+        self._native_group: Optional[_NativeAnimationGroup] = None
 
     def start(self) -> "_AnimationHandle":
         """Begin the animation. Returns ``self`` for chaining."""
         self.stop()
-        anim = self._factory()
-        self._current = anim
+        if self._value is not None and self._native_eligible:
+            spec = self._spec_factory()
+            group = _start_native(self._value, spec)
+            if group is not None:
+                self._native_group = group
+                self._value._adopt_native_group(group)
+                return self
+        anim = self._fallback_factory()
+        self._python_anim = anim
         _manager.add(anim)
         return self
 
     def stop(self) -> None:
         """Cancel the running instance (no-op if not running)."""
-        if self._current is not None:
-            self._current._finish()
-            _manager.remove(self._current)
-            self._current = None
+        if self._native_group is not None:
+            group = self._native_group
+            self._native_group = None
+            if self._value is not None and self._value._native_group is group:
+                self._value._native_group = None
+            group.cancel()
+        if self._python_anim is not None:
+            anim = self._python_anim
+            self._python_anim = None
+            anim._finish()
+            _manager.remove(anim)
 
     async def _drive(self) -> None:
-        if self._current is None:
+        if self._native_group is None and self._python_anim is None:
             self.start()
         loop = asyncio.get_running_loop()
         future: asyncio.Future[None] = loop.create_future()
-        assert self._current is not None
-        self._current.add_completion_future(future)
+        if self._native_group is not None:
+            self._native_group.add_completion_future(future)
+        elif self._python_anim is not None:
+            self._python_anim.add_completion_future(future)
+        else:
+            return
         await future
 
 
@@ -491,12 +779,9 @@ class _CompositeAnimation(_AwaitableAnimation):
     async def _await_item(item: Any) -> None:
         if item is None:
             return
-        if isinstance(item, _AwaitableAnimation):
-            await item
-        else:
-            # Plain awaitables and coroutines are supported too — lets
-            # users mix in ``asyncio.sleep`` or other awaitables.
-            await item
+        # ``_AwaitableAnimation`` and plain awaitables/coroutines are
+        # both supported — lets users mix in ``asyncio.sleep``.
+        await item
 
 
 # ======================================================================
@@ -509,7 +794,7 @@ def _resolve_style_with_values(style: StyleProp) -> Tuple[Dict[str, Any], Dict[s
 
     AnimatedValue entries in the style are replaced with their current
     numeric value in ``plain_style`` and recorded in
-    ``animated_bindings`` so the wrapping component can subscribe
+    ``animated_bindings`` so the wrapping component can attach them
     after mount.
     """
     flat = resolve_style(style)
@@ -537,36 +822,25 @@ def _make_animated_factory(
         from .components import Text as _Text
         from .components import View as _View
 
+        # ``@component`` packs positional children into the ``children``
+        # prop (this function declares ``*args``), and the reconciler
+        # re-invokes it with keyword props only — so at render time the
+        # payload arrives in ``kwargs``, never in ``args``.
+        children = list(args) or list(kwargs.pop("children", ()) or ())
+
         style = kwargs.pop("style", None)
         plain_style, bindings = _resolve_style_with_values(style)
 
         ref = use_ref(None)
 
-        def _subscribe() -> Callable[[], None]:
-            view = ref["current"]
-            unsubs: List[Callable[[], None]] = []
-            if view is None:
+        def _attach_bindings() -> Callable[[], None]:
+            tag = ref.get("_pn_tag")
+            if tag is None:
                 return lambda: None
-
-            for prop, value in bindings.items():
-
-                def _on_change(new_val: float, _prop: str = prop, _view: Any = view) -> None:
-                    handler = _get_handler_for(_view)
-                    if handler is None:
-                        return
-                    setter = getattr(handler, "set_animated_property", None)
-                    if setter is None:
-                        return
-                    try:
-                        setter(_view, _animated_prop_name(_prop), new_val)
-                    except Exception:
-                        pass
-
-                unsub = value.add_listener(prop, _on_change)
-                unsubs.append(unsub)
+            detachers = [value.attach(tag, _animated_prop_name(prop)) for prop, value in bindings.items()]
 
             def _cleanup() -> None:
-                for fn in unsubs:
+                for fn in detachers:
                     try:
                         fn()
                     except Exception:
@@ -574,50 +848,27 @@ def _make_animated_factory(
 
             return _cleanup
 
-        # Re-subscribe whenever bindings change identity.
-        use_effect(_subscribe, [tuple(sorted((k, id(v)) for k, v in bindings.items()))])
+        # Re-attach whenever the binding set changes identity.
+        use_effect(_attach_bindings, [tuple(sorted((k, id(v)) for k, v in bindings.items()))])
 
         if element_type == "Text":
-            text = args[0] if args else kwargs.pop("text", "")
-            return _Text(text, style=plain_style, ref=ref)
+            text = children[0] if children else kwargs.pop("text", "")
+            return _Text(text, style=plain_style, ref=ref, **kwargs)
         if element_type == "Image":
-            source = args[0] if args else kwargs.pop("source", "")
-            return _Image(source, style=plain_style, ref=ref)
-        children = list(args) if accept_children else []
-        return _View(*children, style=plain_style, ref=ref)
+            source = children[0] if children else kwargs.pop("source", "")
+            return _Image(source, style=plain_style, ref=ref, **kwargs)
+        if not accept_children:
+            children = []
+        return _View(*children, style=plain_style, ref=ref, **kwargs)
 
     return _animated
 
 
 def _animated_prop_name(prop: str) -> str:
     """Map a style key to the name expected by ``set_animated_property``."""
-    if prop == "opacity":
-        return "opacity"
-    if prop == "background_color":
-        return "background_color"
-    if prop in ("translate_x", "translate_y", "scale", "scale_x", "scale_y", "rotate"):
-        return prop
     return prop
 
 
-def _get_handler_for(native_view: Any) -> Any:
-    """Best-effort lookup of the registered handler for ``native_view``."""
-    del native_view
-    try:
-        from .native_views import get_registry
-
-        registry = get_registry()
-        handlers = getattr(registry, "_handlers", {})
-        handler = handlers.get("View")
-        if handler is not None:
-            return handler
-        if handlers:
-            return next(iter(handlers.values()))
-        return None
-    except Exception:
-        return None
-
-
 # ======================================================================
 # Public API
 # ======================================================================
@@ -640,12 +891,22 @@ class _AnimatedNamespace:
         duration: float = 300.0,
         easing: Any = "ease_in_out",
     ) -> _AnimationHandle:
-        """Linearly interpolate ``value`` to ``to`` over ``duration`` ms."""
-
-        def _factory() -> _RunningAnimation:
+        """Interpolate ``value`` to ``to`` over ``duration`` ms with ``easing``."""
+
+        def _spec() -> Dict[str, Any]:
+            return {
+                "kind": "timing",
+                "from": value.value,
+                "to": float(to),
+                "duration_ms": float(duration),
+                "easing": str(easing),
+            }
+
+        def _fallback() -> _RunningAnimation:
             return _TimingAnimation(value, to, duration, _resolve_easing(easing))
 
-        return _AnimationHandle(_factory)
+        # Callable easings can't cross the bridge; tick them in Python.
+        return _AnimationHandle(value, _spec, _fallback, native_eligible=not callable(easing))
 
     @staticmethod
     def spring(
@@ -655,13 +916,25 @@ class _AnimatedNamespace:
         stiffness: float = 100.0,
         damping: float = 10.0,
         mass: float = 1.0,
+        initial_velocity: float = 0.0,
     ) -> _AnimationHandle:
         """Run a damped harmonic spring toward ``to``."""
 
-        def _factory() -> _RunningAnimation:
-            return _SpringAnimation(value, to, stiffness, damping, mass)
+        def _spec() -> Dict[str, Any]:
+            return {
+                "kind": "spring",
+                "from": value.value,
+                "to": float(to),
+                "stiffness": float(stiffness),
+                "damping": float(damping),
+                "mass": float(mass),
+                "initial_velocity": float(initial_velocity),
+            }
 
-        return _AnimationHandle(_factory)
+        def _fallback() -> _RunningAnimation:
+            return _SpringAnimation(value, to, stiffness, damping, mass, initial_velocity)
+
+        return _AnimationHandle(value, _spec, _fallback)
 
     @staticmethod
     def decay(
@@ -670,12 +943,20 @@ class _AnimatedNamespace:
         velocity: float,
         deceleration: float = 0.997,
     ) -> _AnimationHandle:
-        """Decelerate ``value`` from its current velocity until it rests."""
+        """Decelerate ``value`` from ``velocity`` (units/ms) until it rests."""
+
+        def _spec() -> Dict[str, Any]:
+            return {
+                "kind": "decay",
+                "from": value.value,
+                "velocity": float(velocity),
+                "deceleration": float(deceleration),
+            }
 
-        def _factory() -> _RunningAnimation:
+        def _fallback() -> _RunningAnimation:
             return _DecayAnimation(value, velocity, deceleration)
 
-        return _AnimationHandle(_factory)
+        return _AnimationHandle(value, _spec, _fallback)
 
     @staticmethod
     def parallel(animations: List[Any]) -> _CompositeAnimation:
@@ -691,10 +972,13 @@ class _AnimatedNamespace:
     def delay(duration: float) -> _AnimationHandle:
         """Wait ``duration`` ms before continuing in a sequence."""
 
-        def _factory() -> _RunningAnimation:
+        def _spec() -> Dict[str, Any]:
+            return {"kind": "delay", "duration_ms": float(duration)}
+
+        def _fallback() -> _RunningAnimation:
             return _DelayAnimation(duration)
 
-        return _AnimationHandle(_factory)
+        return _AnimationHandle(None, _spec, _fallback)
 
     View = staticmethod(_make_animated_factory("View", accept_children=True))
     Text = staticmethod(_make_animated_factory("Text", accept_children=False))
@@ -746,4 +1030,5 @@ __all__ = [
     "AnimatedValue",
     "Animated",
     "use_animated_value",
+    "native_animation_completed",
 ]