Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(motion): a call on a settle tail starts at the browser's commit (#9733)

Christopher Chedeau49ac70d6b3db
diff --git a/.changeset/animator-settle-tail-start.md b/.changeset/animator-settle-tail-start.md
new file mode 100644
index 0000000000..42c5a20c9d
--- /dev/null
+++ b/.changeset/animator-settle-tail-start.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Motion: a call made while an animation settles, with the element already still on screen, waits for the browser's first frame as a call from rest does. A busy page no longer skips the start of the new motion, a jump of up to about 14 px at a Switch's return.
+
+@vjeux
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index 75d702c804..6c7bc29078 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -204,7 +204,9 @@ a measured, sourced difference exists.
velocity to the settle. The floor is a guess inside the measured bracket
(UIKit zeroes steady releases at 175 and 200 pt/s and keeps 249 pt/s, iOS
26.2 simulator, 2026-10-23) until a measurement replaces it (FR2). A page
- change during a drag starts from rest (DEC-25).
+ change during a drag starts from rest (DEC-25). On a starved page, a
+ retarget may skip ahead by up to the browser's commit delay
+ (start-at-call).
- **FR7 — Exits animate as the native counterpart's do.** A touch
presentation MUST play the exit its UIKit counterpart plays, on every touch
platform. FR8 governs their reduced-motion form. Each overlay's own record states its
@@ -762,6 +764,7 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
| FR5 | Browser proof: an animation keeps advancing frame by frame through a 1 s main-thread block, with no layout or paint per frame | Chromium phone emulation; WebKit | a script-driven or layout-animating implementation freezes or lays out |
| FR6 | Unit and browser tests catching an animation mid-flight and retargeting it | catch at peak velocity; retarget with a new spring; a retarget before the browser reports the call's start | a layout read, a jump, or a lost velocity fails |
| FR6 pager | Unit and browser tests of a pager's settle start | releases just under and over 225 pt/s; a catch mid-settle; a programmatic page change mid-settle | a release under the floor whose settle starts moving, a release over it whose settle starts from rest, a catch that loses the on-screen velocity, or a programmatic page change mid-settle that starts from rest fails; a page change during a drag starts from rest |
+| FR6 starved | Switch frame proofs on a starved main thread (4 workers on 2 cores); a unit test of a retarget on a settle tail | a second tap mid-travel, with frames read late or its lift handled 100 ms late; a first frame committed late; a retarget once the thumb is still | a jump out of a thumb that is still fails; a mid-travel step within the browser's commit delay is the known limit |
| FR7, FR8 | Component browser tests and storyboards with and without Reduce Motion | entrance, exit, move; a drag and its lift under Reduce Motion | a missing exit, any travel, scale or spring under Reduce Motion other than a coast after a throw and its settle at an edge (`design:reduced-motion` DR2), or an opacity fade over 200 ms fails |
| FR9, FR10 | Recognizer unit tests on synthetic streams and browser tests with real touch input | drag, second finger, pinch, page zoom, main-thread block | a second finger that breaks a drag, or a page pinch blocked other than by the author's `touch-action`, fails |
| FR11, FR12 | Press and long-press tests on synthetic streams with explicit timestamps | inside and outside a scroll view; a drag the browser takes; a lift inside; a menu row under a finger; a press on a row of a menu whose rows fit and of one that scrolls; a slide-off lift on a Switch and on a Radio | the wrong profile's timing, a press that survives the browser taking the touch, or a control outside an action group activated other than by the browser's click, outside `spec:AST-020` FR9's slide-off exception, a row of a menu whose rows fit that waits 150 ms, or one of a scrolling menu that does not, or a slide-off lift that completes a control outside `spec:AST-020` FR9's exception, fails |
diff --git a/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json b/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json
index ad209ed676..f03efe1d9b 100644
--- a/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json
+++ b/internal/eslint-plugin-astryx/no-comment-provenance.baseline.json
@@ -2071,7 +2071,6 @@
"FR5",
"FR6",
"FR6",
- "FR6",
"INV5",
"architecture:react-component-runtime",
"design:reduced-motion",
@@ -2091,7 +2090,6 @@
"spec quote",
"spec:AST-094",
"spec:AST-094",
- "spec:AST-094",
"spec:AST-094"
],
"packages/core/src/motion/coast.ts": [
diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.md
index 2f255c73a0..4a21eb3f43 100644
--- a/packages/core/src/motion/README.md
+++ b/packages/core/src/motion/README.md
@@ -138,8 +138,10 @@ await handle.finished; // true if it ran to the end, false if interrupted
presented call's second frame) runs on over two frames, the start moves to
the call's first read after it, with every call of that task. Everything
the call starts shares that start
- (`handle.started`); a retarget keeps an explicit one, and `{at}` puts
- several animators on one clock. `{start: 'commit'}` lets the browser date
+ (`handle.started`); a retarget of a curve that still moves keeps an
+ explicit one, while one on a tail that already shows as at rest (within two
+ sample tolerances of its target, and slower than one a frame) counts as a
+ call from rest. `{at}` puts several animators on one clock. `{start: 'commit'}` lets the browser date
a retarget too; `{start: 'presented'}` waits two frames, until the
element at rest has been presented. `handle.curve(property)` is the curve
a call plays, for a companion to follow. `{additive: true}` retargets the
diff --git a/packages/core/src/motion/animator.test.ts b/packages/core/src/motion/animator.test.ts
index f65cb41dd3..da166eef64 100644
--- a/packages/core/src/motion/animator.test.ts
+++ b/packages/core/src/motion/animator.test.ts
@@ -584,10 +584,16 @@ describe('animate: keyframes on the compositor', () => {
clock += firstCurve - 10;
await vi.advanceTimersByTimeAsync(firstCurve - 10);
expect(frameQueue.length).toBeGreaterThan(0);
- // Retargeted before that frame comes; the page then draws no frame until
- // the new curve is inside its own last frame.
+ // Retargeted before that frame comes. The first curve shows as at rest
+ // by now, so the call waits for the browser's start, as one from rest
+ // does. The frame the old look waits for starts it, and that look leaves
+ // it running. The page then draws no frame until the new curve is inside
+ // its own last frame.
animator.animate({x: 200}, {spring: springs.settle});
const second = live('translate').at(-1) as Recorded;
+ expect(second.startTime).toBeNull();
+ await commitFrame(clock);
+ expect(second.cancelled).toBe(false);
datedPerFrame(second);
const secondCurve = Number(second.options.duration) - END_HOLD_MS;
const secondEnd = (second.startTime as number) + secondCurve;
@@ -667,6 +673,48 @@ describe('a call from rest starts at the commit, as Core Animation does', () =>
);
});
+ it('a call on a settle tail starts at the commit too, so a late first frame skips none of its curve', async () => {
+ const {animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ const [first] = live('translate');
+ await commitFrame(1000);
+ // A time inside the first curve's tail: within half a pixel of its
+ // target and slower than a quarter pixel a frame, before its end.
+ let t = 0;
+ while (
+ (Math.abs(curve.value(t) - 300) > 0.5 ||
+ Math.abs(curve.velocity(t)) > 15) &&
+ t < 5
+ ) {
+ t += 0.001;
+ }
+ expect(t).toBeLessThan(5);
+ const at = 1000 + Math.ceil(t * 1000);
+ expect(at - 1000).toBeLessThan(
+ Number(first.options.duration) - END_HOLD_MS,
+ );
+ clock = at;
+ const from = animator.get('x');
+ const handle = animator.animate({x: 0}, {spring: springs.settle});
+ const second = live('translate').at(-1) as Recorded;
+ expect(second.startTime).toBeNull();
+ // The main thread is blocked for 80 ms; the first frame shows the new
+ // curve's first value, not 80 ms into it.
+ clock = at + 80;
+ await commitFrame(clock);
+ await expect(handle.started).resolves.toBe(clock);
+ expect(animator.get('x', clock)).toBeCloseTo(from, 6);
+ });
+
+ it('a call while the curve still moves starts at the call, from the value and velocity on screen', async () => {
+ const {animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ await commitFrame(1000);
+ clock = 1100;
+ animator.animate({x: 0}, {spring: springs.settle});
+ expect((live('translate').at(-1) as Recorded).startTime).toBe(1100);
+ });
+
it('a start the browser dates before the block (WebKit) moves to after it', async () => {
// WebKit dates a pending animation at its last frame time before the
// task that made it, so after a block its first frame would show the
diff --git a/packages/core/src/motion/animator.ts b/packages/core/src/motion/animator.ts
index 8d39ccc5d7..dbe6bdd362 100644
--- a/packages/core/src/motion/animator.ts
+++ b/packages/core/src/motion/animator.ts
@@ -244,18 +244,18 @@ export interface AnimateOptions {
crossfadeAs?: 'entrance' | 'exit';
/**
* When the call's animations start. By default a call from rest starts
- * when the browser commits it, and a call that continues motion on screen
- * (a retarget) starts now, from the value on screen. Ignored with `at`.
+ * when the browser commits it. A call that continues motion on screen (a
+ * retarget) starts now, from the value on screen. A curve whose tail
+ * already shows as at rest counts as rest. Ignored with `at`.
* - `'commit'`: a call that continues motion also starts when the browser
- * commits it, dated by the browser rather than by the main thread, as a
- * call from rest is.
- * - `'presented'`: a call from rest leaves its element at rest and creates
- * its animations two frames later, once the frame that carries the
- * element at rest has been presented; they then start at their commit. A
- * busy UI process delays the motion instead of skipping into it, for two
- * frames more before an idle start. Any other change to the animator
- * before then creates the animations first, in call order. A call that
- * continues motion on screen (a retarget) starts now, as by default.
+ * commits it. The browser dates it, as it dates a call from rest.
+ * - `'presented'`: a call from rest leaves its element at rest. Its
+ * animations are created two frames later, once the frame with the
+ * element at rest has been presented. They then start at their commit,
+ * so a busy UI process delays the motion instead of skipping into it.
+ * Any other change to the animator before then creates the animations
+ * first, in call order. A call that continues motion on screen starts
+ * now, as by default.
*/
start?: 'commit' | 'presented';
/**
@@ -652,6 +652,18 @@ const SAMPLE_TOLERANCE: Record<MotionProperty, number> = {
/** Keyframes start on this grid (ms) and are split where the curve needs it. */
const SAMPLE_GRID_MS = 1000 / 30;
+/**
+ * A curve within this many sample tolerances of its target can show as at
+ * rest. A call on it then starts as one from rest does, at the browser's start.
+ */
+const REST_DISTANCE_TOLERANCES = 2;
+
+/**
+ * A curve shows as at rest only while it moves at most one `SAMPLE_TOLERANCE`
+ * a frame at this rate.
+ */
+const REST_FRAMES_PER_SECOND = 60;
+
/** A curve that has not settled by then (an undamped spring) snaps. */
const MAX_DURATION_MS = 30_000;
@@ -1165,6 +1177,22 @@ export function createAnimator(
return curveAt(property, time);
};
+ /**
+ * Whether a curve's tail already shows as at rest at `time`. Under a
+ * starved main thread the browser commits a call late. A call that starts
+ * at its own time then skips that far into its curve. One that starts at
+ * the commit holds an element that hardly moves.
+ */
+ const showsAtRest = (
+ property: MotionProperty,
+ segment: Segment,
+ time: number,
+ ): boolean =>
+ Math.abs(valueAt(property, time) - segment.target) <=
+ REST_DISTANCE_TOLERANCES * SAMPLE_TOLERANCE[property] &&
+ Math.abs(velocityAt(property, time)) <=
+ SAMPLE_TOLERANCE[property] * REST_FRAMES_PER_SECOND;
+
const velocityAt = (property: MotionProperty, time: number): number => {
const held = segments.get(property);
if (held != null && isHeld(held)) {
@@ -2033,10 +2061,10 @@ export function createAnimator(
// -- starting from rest ---------------------------------------------------
/**
- * A call starts from rest when nothing on the channels it drives is moving
- * (a curve still waiting for its first frame counts as rest) and nothing
- * pins its clock (`at`). Returns its start group, or null for an explicit
- * start.
+ * A call starts from rest when nothing on the channels it drives moves on
+ * screen and nothing pins its clock (`at`). A curve still waiting for its
+ * first frame counts as rest, as does one whose tail already shows as at
+ * rest. Returns its start group, or null for an explicit start.
*/
const beginGroup = (
time: number,
@@ -2070,10 +2098,12 @@ export function createAnimator(
}
return null;
}
- // A call that continues motion starts now unless it asks for the
- // browser's start (`commit`). `presented` asks only for a call from rest:
- // an element still moving is not at rest, so a retarget starts now, from
- // the value and velocity on screen (spec:AST-094 FR6).
+ // A call that continues motion starts now, unless it asks for the
+ // browser's start (`commit`). `presented` asks only for a call from rest.
+ // A curve that still moves is not at rest, so a call on it starts now,
+ // from the value and velocity on screen. A tail that shows as at rest
+ // counts as rest, so a call on it waits, under `presented` for its two
+ // frames.
for (const channel of start === 'commit' ? [] : channels) {
for (const property of CHANNELS[channel]) {
const segment = segments.get(property);
@@ -2084,7 +2114,8 @@ export function createAnimator(
time < endOf(property, segment) &&
(segment.group == null ||
segment.group.resolved ||
- shownSince(property, segment) != null)
+ shownSince(property, segment) != null) &&
+ !showsAtRest(property, segment, time)
) {
return null;
}