chore(core): a compositor animator for touch presentations

.changeset/uikit-motion-animator.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: a compositor animator for touch presentations. It plays UIKit's springs, and scroll coasts (built by a separate coast module, so a surface that never coasts does not carry them; momentum is the only curve `decay` plays) as Web Animations on translate, rotate, scale and opacity, so they keep running while JavaScript is busy, and reads values and velocities back from the curves for interruption, retargeting and Reduce Motion cross-fades. Not exported from the package entry point; no component uses it yet.
+
+@vjeux

packages/core/src/motion/README.md

@@ -3,10 +3,11 @@
 Internal motion foundation for the touch presentations of core components: the
 UIKit constants table (every spring, duration, deceleration rate, rubber-band
 constant, curve and gesture threshold a touch presentation uses, each with its
-source) and the spring, decay, rubber-band and projection math UIKit uses.
-Nothing here is exported from the package entry point. Core's motion and
-gesture modules read the table by path; components take touch motion from the
-theme's motion roles (`spec:AST-094` FR4), not from this table.
+source), the spring, decay, rubber-band and projection math UIKit uses, and a
+compositor animator that plays it. Nothing here is exported from the package
+entry point. Core's motion and gesture modules read the table by path;
+components take touch motion from the theme's motion roles (`spec:AST-094`
+FR4), not from this table.
 
 ## Files
 
@@ -21,13 +22,78 @@ theme's motion roles (`spec:AST-094` FR4), not from this table.
 | `MEASUREMENTS.md`     | The UIKit reference captures each unconfirmed value still needs.                                                        |
 | `spring.ts`           | Closed-form damped spring, every Apple parameterization, settling duration, a spring chasing a moving target.           |
 | `decay.ts`            | UIScrollView's momentum coast.                                                                                          |
+| `coast.ts`            | A release's momentum curves for `animator.decay`: the coast, the edge spring, a release past an edge.                   |
 | `rubberBand.ts`       | UIScrollView's resistance past an edge, and its inverse.                                                                |
 | `projection.ts`       | Release targets: the rest point nearest the projected coast; paging.                                                    |
+| `bezier.ts`           | Cubic-bézier timing functions (Core Animation's named curves).                                                          |
+| `animator.ts`         | Compositor animator: springs and momentum curves compiled to Web Animations, read back analytically.                    |
 
 Component-specific values (a sheet's detents, a switch's geometry, a context
 menu's timeline) live in a domain file per component, `uikit/<component>.ts`,
 under the same rules.
 
+## Animator
+
+```
+import {createAnimator} from '../motion/animator';
+import {springs} from '../motion/uikit';
+
+const animator = createAnimator(sheet);
+
+// A drag writes one style per frame and never renders:
+animator.set({y: offset});
+
+// The finger lifts: spring to the detent with the release velocity (px/s).
+const handle = animator.animate({y: detent}, {spring: springs.sheetDetent, velocity: {y: 1200}});
+
+// A finger lands mid-flight: where is the sheet right now, how fast?
+const y = animator.get('y', event.timeStamp);
+const v = animator.getVelocity('y', event.timeStamp);
+animator.stop(['y']); // freezes at the value on screen
+
+// A throw on a scroll-like surface, with an edge (coast.ts builds the curves):
+animator.decay(coast(animator, {x: velocityX}, {bounds: {x: {min: -maxScroll, max: 0}}}));
+
+await handle.finished; // true if it ran to the end, false if interrupted
+```
+
+- Drives `x`, `y`, `rotate`, `scaleX`, `scaleY` (`scale` sets both) and
+  `opacity`, through the individual CSS properties `translate`, `rotate`,
+  `scale` and `opacity`. The element's `transform` stays the component's.
+- `get` / `getVelocity` evaluate the curves; the DOM is never read.
+- `animate` always starts from the presentation value with the presentation
+  velocity unless a velocity is handed in, so retargeting is continuous
+  (`handle.retarget(to)` keeps the call's spring).
+- Everything one call starts shares one start time; `{at}` puts several
+  animators on one clock.
+- Reduced Motion (`prefers-reduced-motion: reduce`, `design:reduced-motion`
+  DR2–DR4): on a coarse primary pointer every `animate` cross-fades within
+  200 ms. An entrance lands and fades in, an exit fades out then moves, any
+  other move dips (fade out, move, fade in), and an opacity change fades, over
+  `timing.reducedMotionCrossFadeMs` capped at 200 ms. On any other pointer every
+  change completes at once. No call keeps travel or a spring or skips the
+  touch cross-fade. A `decay` keeps moving: momentum after a throw is
+  direct movement.
+
+### How it stays on the compositor
+
+Each curve is baked into keyframes, sampled adaptively until linear
+interpolation is within 0.05 px, and played with `easing: linear` and an
+explicit `startTime`. The element's inline style already holds the end values,
+and the keyframes hold the end state for a few seconds past the curve's end;
+the main thread drops the animation as soon as it runs after that end. So the
+frame an animation ends needs no main thread and shows no flicker, even when
+the main thread is blocked as the curve ends (WebKit's compositor otherwise
+falls back to the last value its main thread committed, mid-flight).
+
+Keyframes rather than one `linear()` easing: measured in Chromium, both are
+composited and, for the same samples, equally precise; but WebKit's Core
+Animation path does not accelerate an effect whose easing is `linear()` with
+points (`KeyframeEffect::canBeAccelerated`) unless its newer threaded
+animations are on, so on older iOS Safari a `linear()` spring would run on the
+main thread. Linear segments between keyframes map directly onto Core
+Animation keyframe animations.
+
 ## Math
 
 `spring.ts` solves m·x″ + c·x′ + k·x = 0 in closed form in all three regimes: