Skip to content

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

TypeScript

fix(core): a retarget after a late first frame continues from the screen (#9401)

Christopher Chedeau4a7a6f21ea4e
diff --git a/.changeset/animator-late-first-frame.md b/.changeset/animator-late-first-frame.md
new file mode 100644
index 0000000000..f48fa19068
--- /dev/null
+++ b/.changeset/animator-late-first-frame.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the touch presentations' animator reads a call whose first frame came late, and left its start unread, as started at that frame. A retarget or a read before the browser reports the start, of now or of a later time, continues near where the screen has it instead of from the call's first value. A rebase or set that rebuilds one channel's animation in that window reads that channel's first value until the frame that commits it, and the call's other channels keep reading from the first frame. The browser's start, once read, still decides. Not exported from the package entry point.
+
+@vjeux
diff --git a/packages/core/src/motion/animator.test.ts b/packages/core/src/motion/animator.test.ts
index 89aefce585..23cd42add7 100644
--- a/packages/core/src/motion/animator.test.ts
+++ b/packages/core/src/motion/animator.test.ts
@@ -262,6 +262,12 @@ function parse(value: string | number | null | undefined): number[] {
.map(part => Number.parseFloat(part));
}
+/** The x of the element's inline translate; `none` is no translate. */
+function inlineX(element: HTMLElement): number {
+ const value = element.style.translate;
+ return value === 'none' ? 0 : parse(value)[0];
+}
+
/** What the browser would show: the keyframes interpolated linearly at `time`. */
function sampleAt(
animation: Recorded,
@@ -902,6 +908,202 @@ describe('a call from rest starts at the commit, as Core Animation does', () =>
expect(started).toBe(false);
});
+ it('a late first frame that leaves the start unread: a read and a retarget take the curve from that frame', async () => {
+ // The first frame comes 70 ms after the call, late behind other work.
+ // The page itself does not block. The page still has no start to read,
+ // but the compositor has the call moving by then.
+ const {animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ const [animation] = live('translate');
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ expect(animation.startTime).toBeNull();
+ clock = 1170;
+ expect(animator.get('x')).toBeCloseTo(curve.value(0.1), 9);
+ animator.animate({x: 400}, {spring: springs.settle});
+ const retarget = live('translate').at(-1) as Recorded;
+ expect(sampleAt(retarget, 'translate', 1170)[0]).toBeCloseTo(
+ curve.value(0.1),
+ 1,
+ );
+ });
+
+ it('a late first frame that leaves the start unread: the browser\u2019s start, once read, still decides', async () => {
+ const {animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ const [animation] = live('translate');
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ // The browser started it at 1060 and tells the page now.
+ animation.commit(1060);
+ await Promise.resolve();
+ await Promise.resolve();
+ clock = 1170;
+ expect(animator.get('x')).toBeCloseTo(curve.value(0.11), 9);
+ });
+
+ it('a rebase after a late first frame reads what the rebuilt animation shows, from the first value it starts at the frame that commits it', async () => {
+ const {element, animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ clock = 1170;
+ animator.rebase({x: -16});
+ const rebuilt = live('translate').at(-1) as Recorded;
+ expect(rebuilt.startTime).toBeNull();
+ // Until the frame that commits it, the screen shows its first keyframe.
+ // The inline value and the hit-test origin show it too.
+ const first = parse(rebuilt.keyframes[0].translate)[0];
+ expect(animator.get('x')).toBeCloseTo(first, 1);
+ expect(inlineX(element)).toBeCloseTo(first, 1);
+ expect(presentedOffsetOf(element).x).toBeCloseTo(0, 1);
+ // It starts at that frame, which bounds its start again.
+ clock = 1186;
+ await commitFrame(1186, {startUnread: true});
+ clock = 1202;
+ const shown = sampleAt(rebuilt, 'translate', rebuilt.createdAt + 16)[0];
+ expect(animator.get('x')).toBeCloseTo(shown, 1);
+ animator.animate({x: 400}, {spring: springs.settle});
+ const retarget = live('translate').at(-1) as Recorded;
+ expect(sampleAt(retarget, 'translate', 1202)[0]).toBeCloseTo(shown, 1);
+ });
+
+ it('a set of the other axis after a late first frame reads what the rebuilt animation shows, from the first value it starts at the frame that commits it', async () => {
+ const {element, animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ clock = 1170;
+ animator.set({y: 10});
+ const rebuilt = live('translate').at(-1) as Recorded;
+ expect(rebuilt.startTime).toBeNull();
+ const first = parse(rebuilt.keyframes[0].translate)[0];
+ expect(animator.get('x')).toBeCloseTo(first, 1);
+ expect(inlineX(element)).toBeCloseTo(first, 1);
+ expect(presentedOffsetOf(element).x).toBeCloseTo(0, 1);
+ clock = 1186;
+ await commitFrame(1186, {startUnread: true});
+ clock = 1202;
+ const shown = sampleAt(rebuilt, 'translate', rebuilt.createdAt + 16)[0];
+ expect(animator.get('x')).toBeCloseTo(shown, 1);
+ });
+
+ it('a retarget of the other axis without a clock after a late first frame reads the first value the adopted curve starts from', async () => {
+ const {element, animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ clock = 1170;
+ animator.animate({y: 50}, {spring: springs.settle});
+ const rebuilt = live('translate').at(-1) as Recorded;
+ expect(rebuilt.startTime).toBeNull();
+ // The new call takes the x curve and starts it again from its first
+ // keyframe. The reads, the inline value and the hit-test origin show it.
+ const first = parse(rebuilt.keyframes[0].translate)[0];
+ expect(animator.get('x')).toBeCloseTo(first, 1);
+ expect(inlineX(element)).toBeCloseTo(first, 1);
+ expect(presentedOffsetOf(element).x).toBeCloseTo(0, 1);
+ });
+
+ it('a retarget that joins a call by its clock after a late first frame reads the first value the rebuilt animation starts from', async () => {
+ const {element, animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ clock = 1170;
+ animator.animate({y: 50}, {spring: springs.settle}, {at: 1000});
+ const rebuilt = live('translate').at(-1) as Recorded;
+ expect(rebuilt.startTime).toBeNull();
+ const first = parse(rebuilt.keyframes[0].translate)[0];
+ expect(animator.get('x')).toBeCloseTo(first, 1);
+ expect(inlineX(element)).toBeCloseTo(first, 1);
+ expect(presentedOffsetOf(element).x).toBeCloseTo(0, 1);
+ // The frame that commits it starts the joined call: the call is that
+ // frame's own task's.
+ clock = 1186;
+ await commitFrame(1186, {startUnread: true});
+ clock = 1202;
+ expect(animator.get('x')).toBeCloseTo(
+ sampleAt(rebuilt, 'translate', 1202)[0],
+ 1,
+ );
+ });
+
+ it('a curve that joins a call by an older clock reads, after a late first frame, where the compositor has it', async () => {
+ const {animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ animator.animate({y: 50}, {spring: springs.settle}, {at: 990});
+ const [joined] = live('translate').slice(-1);
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ clock = 1170;
+ // The compositor started the joined animation at that frame: 100 ms
+ // into its keyframes, which run from the call's own time.
+ const shown = sampleAt(joined, 'translate', joined.createdAt + 100);
+ expect(animator.get('x')).toBeCloseTo(shown[0], 1);
+ expect(animator.get('y')).toBeCloseTo(shown[1], 1);
+ });
+
+ it('a late first frame that leaves the start unread: a read of a later time takes the curve from that frame, as the velocity does', async () => {
+ const {animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ clock = 1170;
+ // A companion samples a frame ahead of now.
+ expect(animator.get('x', 1186)).toBeCloseTo(curve.value(0.116), 9);
+ expect(animator.getVelocity('x', 1186)).toBeCloseTo(
+ curve.velocity(0.116),
+ 9,
+ );
+ });
+
+ it("a rebase of one channel after a late first frame keeps the call's other channels reading from that frame", async () => {
+ const {animator} = setup();
+ animator.animate({x: 300, opacity: 0}, {spring: springs.settle});
+ const fade = live('opacity').at(-1) as Recorded;
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ clock = 1170;
+ animator.rebase({x: -16});
+ expect(live('opacity').at(-1)).toBe(fade);
+ expect(animator.get('opacity')).toBeCloseTo(
+ sampleAt(fade, 'opacity', fade.createdAt + 100)[0],
+ 2,
+ );
+ clock = 1186;
+ await commitFrame(1186, {startUnread: true});
+ clock = 1202;
+ const shown = sampleAt(fade, 'opacity', fade.createdAt + 132)[0];
+ expect(animator.get('opacity')).toBeCloseTo(shown, 2);
+ animator.animate({opacity: 1}, {spring: springs.settle});
+ const retarget = live('opacity').at(-1) as Recorded;
+ expect(sampleAt(retarget, 'opacity', 1202)[0]).toBeCloseTo(shown, 2);
+ });
+
+ it("a set of the other axis after a late first frame keeps the call's other channels reading from that frame", async () => {
+ const {animator} = setup();
+ animator.animate({x: 300, opacity: 0}, {spring: springs.settle});
+ const fade = live('opacity').at(-1) as Recorded;
+ clock = 1070;
+ await commitFrame(1070, {startUnread: true});
+ clock = 1170;
+ animator.set({y: 10});
+ expect(live('opacity').at(-1)).toBe(fade);
+ expect(animator.get('opacity')).toBeCloseTo(
+ sampleAt(fade, 'opacity', fade.createdAt + 100)[0],
+ 2,
+ );
+ clock = 1186;
+ await commitFrame(1186, {startUnread: true});
+ clock = 1202;
+ const shown = sampleAt(fade, 'opacity', fade.createdAt + 132)[0];
+ expect(animator.get('opacity')).toBeCloseTo(shown, 2);
+ animator.animate({opacity: 1}, {spring: springs.settle});
+ const retarget = live('opacity').at(-1) as Recorded;
+ expect(sampleAt(retarget, 'opacity', 1202)[0]).toBeCloseTo(shown, 2);
+ });
+
it('a call the page pauses before its first frame waits for its start', async () => {
// A harness or a page that pauses the animation: nothing starts it at
// the commit, so nothing sets a start for it either.
diff --git a/packages/core/src/motion/animator.ts b/packages/core/src/motion/animator.ts
index 715e8be267..3f5585890a 100644
--- a/packages/core/src/motion/animator.ts
+++ b/packages/core/src/motion/animator.ts
@@ -517,6 +517,14 @@ interface StartGroup {
madeInFrame?: boolean;
/** The task it was made in, with every call made in that task. */
task?: TaskMark;
+ /**
+ * Per channel, when its animation's first frame ran without a known start.
+ * That frame came too late to stand for the start, and the browser had not
+ * told it yet. The compositor starts the animation within about a frame of
+ * this time. Until the browser tells its start, a read of the channel takes
+ * the curve from here.
+ */
+ latest?: Map<Channel, number>;
/** A later call in the same task that took over its curves. */
adoptedBy?: StartGroup;
readonly resolve: (start: number) => void;
@@ -1070,16 +1078,42 @@ export function createAnimator(
};
/**
- * The value on screen at `time`. A curve the browser has not started is at
- * its start up to now; a later time reads the curve from its provisional
- * start, the model's best guess until the browser's start moves it (a
- * companion that samples a curve ahead follows its shape).
+ * A held curve's start once a frame dated its call, as the browser's start
+ * moves it: by that frame's lead over the call's own time.
+ */
+ const datedFromLatest = (
+ segment: Segment,
+ latest: number | undefined,
+ ): {latest: number; start: number} | null =>
+ latest == null || segment.group == null
+ ? null
+ : {latest, start: segment.start + latest - segment.group.provisional};
+
+ /**
+ * The value on screen at `time`. Until the browser reports its start, a
+ * held curve shows its first value. A frame that ran without that start
+ * dates the curve. Without that frame, a later time reads from the
+ * provisional start, so a companion that samples ahead follows the curve's
+ * shape.
*/
const valueAt = (property: MotionProperty, time: number): number => {
const segment = segments.get(property);
- if (segment != null && isHeld(segment) && time <= now()) {
+ if (segment != null && isHeld(segment)) {
+ // The compositor starts the call near its first frame. The curve is
+ // dated as the browser's start would date it. A curve that joined by an
+ // older clock keeps its lead over the call's own time.
+ const latest = segment.group?.latest?.get(CHANNEL_OF[property]);
+ const dated = datedFromLatest(segment, latest);
+ if (dated != null) {
+ const elapsed = Math.max(time, dated.latest) - dated.start;
+ return elapsed >= segment.duration
+ ? segment.target
+ : segment.at(elapsed);
+ }
// Nothing has moved on screen until the browser starts the call.
- return segment.at(0);
+ if (time <= now()) {
+ return segment.at(0);
+ }
}
return curveAt(property, time);
};
@@ -1087,10 +1121,22 @@ export function createAnimator(
const velocityAt = (property: MotionProperty, time: number): number => {
const held = segments.get(property);
if (held != null && isHeld(held)) {
- // Still at its start on screen, but moving in the model: a retarget
- // carries the velocity the curve has reached by now, so a flick whose
- // moves all land before the browser starts any keeps its speed.
- return held.speed(Math.max(0, time - held.start));
+ // Still at its start on screen, but moving in the model. A retarget
+ // carries the velocity the curve has reached by now. So a flick whose
+ // moves all land before the browser starts any keeps its speed. Past
+ // its first frame, it reads from that frame, as its value does.
+ const dated = datedFromLatest(
+ held,
+ held.group?.latest?.get(CHANNEL_OF[property]),
+ );
+ return held.speed(
+ Math.max(
+ 0,
+ dated != null && time > dated.latest
+ ? time - dated.start
+ : time - held.start,
+ ),
+ );
}
const segment = segmentAt(property, time);
if (segment == null || time < segment.start) {
@@ -1276,6 +1322,35 @@ export function createAnimator(
}
}
const moving = properties.filter(p => segments.has(p));
+ // An explicit call can rebuild a channel while one of its curves still
+ // waits for the browser's start. The animation then joins the current
+ // call, or else that waiting call, with no start of its own.
+ const waiting =
+ callGroup ??
+ moving
+ .map(p => (segments.get(p) as Segment).group)
+ .find(group => group != null && !group.resolved) ??
+ null;
+ const rebuiltAfterFirstFrame = waiting?.framed === true;
+ // The new animation starts at the frame that commits it, from its first
+ // keyframe. That holds for a waiting call it joins after that call's
+ // first frame, and for every waiting call it takes a curve from. So this
+ // channel's reads below, and until that frame, take that first value.
+ const restarted = new Set<StartGroup>();
+ if (rebuiltAfterFirstFrame) {
+ restarted.add(waiting);
+ }
+ if (callGroup != null) {
+ for (const property of moving) {
+ const group = (segments.get(property) as Segment).group;
+ if (group != null && group !== callGroup && !group.resolved) {
+ restarted.add(group);
+ }
+ }
+ }
+ for (const group of restarted) {
+ group.latest?.delete(channel);
+ }
if (channel === 'translate') {
// The animation built below starts from the value at `time` (its first
// keyframe); a rebase or a retarget builds a new one, so a new start.
@@ -1308,15 +1383,6 @@ export function createAnimator(
previous?.cancel();
return;
}
- // A channel rebuilt by an explicit call (set, rebase, a retarget of
- // another axis) while one of its curves still waits for the browser's
- // start keeps that start: no explicit start for this animation.
- const waiting =
- callGroup ??
- moving
- .map(p => (segments.get(p) as Segment).group)
- .find(group => group != null && !group.resolved) ??
- null;
// The keyframes start where the animation will: at the waiting call's
// own time, which its start moves to the browser's (resolveGroup), so a
// write later in the task keeps the screen on the model's clock.
@@ -1431,6 +1497,20 @@ export function createAnimator(
waiting.channels.add(channel);
// A cancel before the first frame rejects its ready promise.
(animation as Partial<Animation>).ready?.catch(() => {});
+ if (rebuiltAfterFirstFrame) {
+ // The frame that commits it dates this channel's start again. The
+ // call's other channels keep their own.
+ requestFrame?.(() => {
+ if (
+ !waiting.resolved &&
+ running.get(channel) === animation &&
+ animation.startTime == null &&
+ animation.playState === 'running'
+ ) {
+ (waiting.latest ??= new Map()).set(channel, now());
+ }
+ });
+ }
} else {
// One clock: the keyframes were sampled from `time`.
animation.startTime = time;
@@ -2135,6 +2215,22 @@ export function createAnimator(
) {
resolveGroup(group, now());
}
+ // The browser's start is still unread. The compositor starts the call
+ // near this frame, so each moving channel's reads take the curve from
+ // now until the browser tells its start.
+ if (!group.resolved) {
+ for (const channel of group.channels) {
+ const animation = running.get(channel);
+ if (
+ animation != null &&
+ group.animations.includes(animation) &&
+ animation.startTime == null &&
+ animation.playState === 'running'
+ ) {
+ (group.latest ??= new Map()).set(channel, now());
+ }
+ }
+ }
});
ready.then(
() => syncGroup(group),