Skip to content

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

TypeScript

fix(core): a retarget before Chromium reports a call's start continues from the screen (#9255)

Christopher Chedeaud29d841f4158
diff --git a/.changeset/animator-start-at-commit-frame.md b/.changeset/animator-start-at-commit-frame.md
new file mode 100644
index 0000000000..2782464c48
--- /dev/null
+++ b/.changeset/animator-start-at-commit-frame.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the touch presentations' animator starts a call from rest, made in a task, at the first frame after it when the browser has not yet told the page that start (Chromium reports a compositor's start a frame or more later), so a retarget or a rebase in that window continues from the value on screen instead of replaying the curve from its start. A call made in a frame callback, or one whose first frame comes after a block, keeps the browser's start. Not exported from the package entry point.
+
+@vjeux
diff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.md
index 59bff85461..ea94298319 100644
--- a/docs/specs/AST-094-touch-presentations/spec.md
+++ b/docs/specs/AST-094-touch-presentations/spec.md
@@ -701,7 +701,7 @@ under a finger, and a mouse follows `module:DropdownMenu/useMenuPress` FR3 and
| FR3 | Unit tests of the spring, decay, rubber band and projection math against an independent integration and values read from UIKit | under-, critically and overdamped springs; release velocities; both rates; overscroll depths | changing a formula or a constant breaks the agreement with UIKit's values |
| FR4 | Role unit tests over every touch motion | each role at its table value; a theme that writes `motion` | a literal played in place of a role, a value that differs from the table at `tempo` 1 and `'standard'`, or a theme that changes a role other than through its motion knobs fails |
| 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 layout read, a jump, or a lost velocity fails |
+| 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 |
| 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/packages/core/src/motion/__tests__/animator.interaction.browser.spec.ts b/packages/core/src/motion/__tests__/animator.interaction.browser.spec.ts
index aa972b53e8..282204ee2b 100644
--- a/packages/core/src/motion/__tests__/animator.interaction.browser.spec.ts
+++ b/packages/core/src/motion/__tests__/animator.interaction.browser.spec.ts
@@ -523,6 +523,152 @@ test('a spring started right before a block plays in full after it', async ({
expect(Math.max(...later.map(f => f.x))).toBeGreaterThan((first?.x ?? 0) + 1);
});
+test('a retarget made before the page can read a call\u2019s start begins where the screen shows the element (spec:AST-094 FR6)', async ({
+ page,
+ browserName,
+}) => {
+ test.skip(
+ browserName !== 'chromium',
+ 'screencast frame evidence is Chromium-only in Playwright, and Chromium is the engine that tells the page a composited start late',
+ );
+ await open(page);
+ const box = page.locator('#box');
+ await markElement(box, {inset: MARKER_INSET});
+ const cast = await startScreencast(page);
+ // A call from rest in one task. In the task after the frame that commits
+ // it, the page is busy for 150 ms while the compositor moves the box, so
+ // the browser's notice of the start waits behind it; then it retargets.
+ const spring = {response: 0.6, dampingRatio: 1};
+ const result = await page.evaluate(
+ async ({s, first, second}) =>
+ new Promise<{held: number; at: number}>(resolve => {
+ setTimeout(() => {
+ window.animator.animate({x: first}, {spring: s});
+ // The frame that commits it; a task queued there runs after it.
+ requestAnimationFrame(() => {
+ setTimeout(() => {
+ const end = performance.now() + 150;
+ while (performance.now() < end) {
+ // the page's main thread is busy
+ }
+ const at = performance.timeOrigin + performance.now();
+ const held = window.animator.get('x');
+ window.animator.animate({x: second}, {spring: s});
+ resolve({held, at});
+ }, 0);
+ });
+ }, 0);
+ }),
+ {s: spring, first: TRAVEL / 2, second: TRAVEL},
+ );
+ // Wait for the motion, not a wall clock: most of the way to the new
+ // target, then three more frames.
+ await page.waitForFunction(
+ min =>
+ (document.getElementById('box')?.getBoundingClientRect().left ?? 0) > min,
+ TRAVEL * 0.8,
+ {polling: 'raf', timeout: 0},
+ );
+ const seen = cast.frameCount();
+ await expect
+ .poll(() => cast.frameCount(), {timeout: 0})
+ .toBeGreaterThan(seen + 2);
+ const tracked = await trackMarker(page, await cast.stop());
+ const xs = tracked
+ .filter(f => f.box != null && f.box.width > 0 && f.box.height > 0)
+ .map(f => ({t: f.t, x: (f.box?.x ?? NaN) - MARKER_INSET}));
+ test.info().annotations.push({
+ type: 'retarget before the start notice',
+ description: JSON.stringify({held: result.held, at: result.at, xs}),
+ });
+ // Present and painted first: the marked box in the frames.
+ expect(xs.length).toBeGreaterThan(10);
+ // The screen never steps back: each presented frame is at or past the one
+ // before (both targets lie ahead)...
+ for (let i = 1; i < xs.length; i++) {
+ expect(xs[i].x, JSON.stringify(xs)).toBeGreaterThanOrEqual(xs[i - 1].x - 1);
+ }
+ // ...because the page reads the curve under way when it retargets.
+ expect(result.held).toBeGreaterThan(5);
+});
+
+for (const how of ['from a page frame callback', 'presented'] as const) {
+ test(`a call made in an animation-frame callback (${how}), whose next frame a busy task delays, keeps the start its own frame gave it: the screen never steps back (spec:AST-094 FR6)`, async ({
+ page,
+ browserName,
+ }) => {
+ test.skip(
+ browserName !== 'chromium',
+ 'screencast frame evidence is Chromium-only in Playwright, and Chromium is the engine that tells the page a composited start late',
+ );
+ await open(page);
+ const box = page.locator('#box');
+ await markElement(box, {inset: MARKER_INSET});
+ const cast = await startScreencast(page);
+ // Made in a frame, which commits it; a task queued in that frame runs
+ // after it and keeps the page busy for 150 ms, so the frame after it,
+ // and the browser's notice of the start, come late.
+ const spring = {response: 0.6, dampingRatio: 1};
+ await page.evaluate(
+ async ({s, travel, presented}) =>
+ new Promise<void>(resolve => {
+ const busy = () => {
+ setTimeout(() => {
+ const end = performance.now() + 150;
+ while (performance.now() < end) {
+ // the page's main thread is busy
+ }
+ resolve();
+ }, 0);
+ };
+ if (presented) {
+ // Its animations are made in its second frame's callback; this
+ // pair of frame callbacks runs right after the animator's.
+ window.animator.animate(
+ {x: travel},
+ {spring: s},
+ {start: 'presented'},
+ );
+ requestAnimationFrame(() => requestAnimationFrame(busy));
+ } else {
+ requestAnimationFrame(() => {
+ window.animator.animate({x: travel}, {spring: s});
+ busy();
+ });
+ }
+ }),
+ {s: spring, travel: TRAVEL, presented: how === 'presented'},
+ );
+ await page.waitForFunction(
+ min =>
+ (document.getElementById('box')?.getBoundingClientRect().left ?? 0) >
+ min,
+ TRAVEL * 0.8,
+ {polling: 'raf', timeout: 0},
+ );
+ const seen = cast.frameCount();
+ await expect
+ .poll(() => cast.frameCount(), {timeout: 0})
+ .toBeGreaterThan(seen + 2);
+ const tracked = await trackMarker(page, await cast.stop());
+ const xs = tracked
+ .filter(f => f.box != null && f.box.width > 0 && f.box.height > 0)
+ .map(f => ({t: f.t, x: (f.box?.x ?? NaN) - MARKER_INSET}));
+ test.info().annotations.push({
+ type: 'frame-made call behind a busy task',
+ description: JSON.stringify(xs),
+ });
+ expect(xs.length).toBeGreaterThan(10);
+ // The screen never steps back: each presented frame is at or past the
+ // one before.
+ for (let i = 1; i < xs.length; i++) {
+ expect(xs[i].x, JSON.stringify(xs)).toBeGreaterThanOrEqual(
+ xs[i - 1].x - 1,
+ );
+ }
+ });
+}
+
test('no Layout or Paint runs while it animates', async ({
page,
browserName,
diff --git a/packages/core/src/motion/animator.test.ts b/packages/core/src/motion/animator.test.ts
index 546ef04b51..01846d89af 100644
--- a/packages/core/src/motion/animator.test.ts
+++ b/packages/core/src/motion/animator.test.ts
@@ -208,11 +208,22 @@ function setup({
return {element, animator};
}
-/** The browser commits a frame at `at`: pending animations start there. */
-async function commitFrame(at: number) {
- for (const animation of recorded) {
- if (animation.startTime == null && !animation.cancelled) {
- animation.commit(at);
+/**
+ * The browser commits a frame at `at`: pending animations start there. With
+ * `startUnread`, the frame's callbacks run before the page can read those
+ * starts, as in Chromium, whose compositor starts a composited animation at
+ * the frame that commits it and tells the page that start a frame or more
+ * later.
+ */
+async function commitFrame(
+ at: number,
+ {startUnread = false}: {startUnread?: boolean} = {},
+) {
+ if (!startUnread) {
+ for (const animation of recorded) {
+ if (animation.startTime == null && !animation.cancelled) {
+ animation.commit(at);
+ }
}
}
const frames = frameQueue;
@@ -715,6 +726,115 @@ describe('a call from rest starts at the commit, as Core Animation does', () =>
}
});
+ describe('a start the page reads a frame or more after the compositor uses it (Chromium)', () => {
+ it('starts at the frame that commits it, on the page as on the compositor', async () => {
+ const {animator} = setup();
+ const handle = animator.animate({x: 300}, {spring: springs.settle});
+ const [animation] = live('translate');
+ // The frame that commits it runs at 1016 while its start is unread.
+ clock = 1016;
+ await commitFrame(1016, {startUnread: true});
+ expect(animation.startTime).toBe(1016);
+ await expect(handle.started).resolves.toBe(1016);
+ clock = 1116;
+ expect(animator.get('x')).toBeCloseTo(curve.value(0.1), 9);
+ });
+
+ it('a retarget before the page reads the start starts where the screen shows it', async () => {
+ const {animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ clock = 1016;
+ await commitFrame(1016, {startUnread: true});
+ // 100 ms into the curve on screen; the page still has no start to read.
+ clock = 1116;
+ animator.animate({x: 400}, {spring: springs.settle});
+ const retarget = live('translate').at(-1) as Recorded;
+ expect(retarget.startTime).toBe(1116);
+ expect(sampleAt(retarget, 'translate', 1116)[0]).toBeCloseTo(
+ curve.value(0.1),
+ 1,
+ );
+ });
+
+ it('a rebase before the page reads the start keeps the value on screen', async () => {
+ const {animator} = setup();
+ animator.animate({x: 300}, {spring: springs.settle});
+ clock = 1016;
+ await commitFrame(1016, {startUnread: true});
+ clock = 1116;
+ animator.rebase({x: -16});
+ const rebased = live('translate').at(-1) as Recorded;
+ // On the curve's own clock, 100 ms in, shifted by the rebase.
+ expect(rebased.startTime).not.toBeNull();
+ expect(sampleAt(rebased, 'translate', 1116)[0]).toBeCloseTo(
+ curve.value(0.1) - 16,
+ 1,
+ );
+ });
+
+ it('a call made in a frame callback keeps the start the browser gives it, however late its next frame', async () => {
+ // A presented call's animations are made in its second frame's
+ // callback, so that frame commits them: the frame after it, here late
+ // behind a busy task, is not the one that starts them.
+ const {animator} = setup();
+ const handle = animator.animate(
+ {x: 300},
+ {spring: springs.settle},
+ {start: 'presented'},
+ );
+ clock = 1016;
+ await commitFrame(1016);
+ clock = 1033;
+ await commitFrame(1033);
+ const [animation] = live('translate');
+ clock = 1180;
+ await commitFrame(1180, {startUnread: true});
+ expect(animation.startTime).toBeNull();
+ let started = false;
+ void handle.started.then(() => {
+ started = true;
+ });
+ await Promise.resolve();
+ expect(started).toBe(false);
+ });
+
+ it('a call whose first frame comes after a block keeps the start the browser gives it', async () => {
+ // A block between the call and its first frame: that frame cannot tell
+ // a call made in a task from one a page's own frame callback made, so
+ // it sets no start of its own.
+ const {animator} = setup();
+ const handle = animator.animate({x: 300}, {spring: springs.settle});
+ const [animation] = live('translate');
+ clock = 1150;
+ await commitFrame(1150, {startUnread: true});
+ expect(animation.startTime).toBeNull();
+ let started = false;
+ void handle.started.then(() => {
+ started = true;
+ });
+ await Promise.resolve();
+ expect(started).toBe(false);
+ });
+
+ 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.
+ const {animator} = setup();
+ const handle = animator.animate({x: 300}, {spring: springs.settle});
+ const [animation] = live('translate');
+ animation.paused = true;
+ clock = 1016;
+ await commitFrame(1016, {startUnread: true});
+ expect(animation.startTime).toBeNull();
+ let started = false;
+ void handle.started.then(() => {
+ started = true;
+ });
+ await Promise.resolve();
+ expect(started).toBe(false);
+ });
+ });
+
it('holds its start until the browser starts it', async () => {
const {animator} = setup();
animator.animate({x: 300}, {spring: springs.settle});
diff --git a/packages/core/src/motion/animator.ts b/packages/core/src/motion/animator.ts
index a02bca5b55..a2335b3975 100644
--- a/packages/core/src/motion/animator.ts
+++ b/packages/core/src/motion/animator.ts
@@ -59,7 +59,11 @@
* commit: a main-thread block before that frame delays the motion instead of
* skipping into it. Everything the call starts, and every
* call from rest in the same task, starts at that one time, which
- * `handle.started` reports. A call that continues motion on
+ * `handle.started` reports. Where the compositor starts it and the page
+ * learns that start only a frame or more later (Chromium), the call starts
+ * at the frame that commits it, the start the compositor takes, so a
+ * retarget or a rebase before then continues from the frame on screen. A
+ * call that continues motion on
* screen (a retarget, a catch) keeps an explicit start at the call time, or
* `options.at` to line several animators up, so the new curve continues
* from the frame on screen. Keyframes are sampled from the call's start, so
@@ -504,6 +508,12 @@ interface StartGroup {
* browser's, whatever it says (startAfterBlock).
*/
framed?: boolean;
+ /**
+ * Made in an animation-frame callback of an animator's own (a presented
+ * call's second frame): the browser commits its animations in that frame,
+ * so the frame after it is not the one that starts them.
+ */
+ madeInFrame?: boolean;
/** The task it was made in, with every call made in that task. */
task?: TaskMark;
/** A later call in the same task that took over its curves. */
@@ -663,6 +673,9 @@ interface TaskMark {
/** The task the current calls from rest are made in, until it ends. */
let openTask: TaskMark | null = null;
+/** How many of the animators' animation-frame callbacks are running now. */
+let frameDepth = 0;
+
/** The mark of the running task, opened by its first call from rest. */
function markTask(time: number, clock: () => number): TaskMark {
if (openTask == null) {
@@ -909,13 +922,28 @@ export function createAnimator(
options: AnimatorOptions = {},
): Animator {
const now = options.now ?? defaultNow;
- const requestFrame =
+ const frameSource =
options.requestFrame ??
(typeof requestAnimationFrame === 'function'
? (callback: () => void) => {
requestAnimationFrame(() => callback());
}
: null);
+ // Every frame callback of an animator's counts itself, so a call made in
+ // one knows its animations commit in that frame.
+ const requestFrame =
+ frameSource == null
+ ? null
+ : (callback: () => void) => {
+ frameSource(() => {
+ frameDepth += 1;
+ try {
+ callback();
+ } finally {
+ frameDepth -= 1;
+ }
+ });
+ };
const pseudoElement = options.pseudoElement;
// Reduced Motion reads the person's settings and nothing else: no option
// overrides them (design:reduced-motion DR4).
@@ -1921,6 +1949,7 @@ export function createAnimator(
// call's is its second frame's callback, wherever in its frame the call
// was made.
group.task = markTask(now(), now);
+ group.madeInFrame = frameDepth > 0;
queueMicrotask(() => {
group.fresh = false;
});
@@ -1940,6 +1969,30 @@ export function createAnimator(
requestFrame?.(() => {
syncGroup(group);
group.framed = true;
+ // Chromium's compositor starts a composited animation when the frame
+ // that commits it reaches it, and tells the page that start a frame or
+ // more later (longer under load). Until then the call would read as
+ // not started while the screen moves it, and a retarget or a rebase
+ // would replay its curve from the start. A call made in a task, still
+ // waiting in the first frame after it, starts now, which the compositor
+ // then takes as its start: the time this frame runs, not its timestamp,
+ // which after a block is the frame time from before the block. Only
+ // when this frame is the one that commits it: not for a call made in a
+ // frame callback, whose frame committed it already, nor when a block
+ // ran between the call and this frame (more than LATE_START_MS), after
+ // which this frame cannot tell a call made in a task from one a page's
+ // own frame callback made; those keep the browser's start.
+ if (
+ !group.resolved &&
+ group.madeInFrame !== true &&
+ now() - (group.task?.first ?? group.provisional) <= LATE_START_MS &&
+ group.animations.some(
+ animation =>
+ animation.startTime == null && animation.playState === 'running',
+ )
+ ) {
+ resolveGroup(group, now());
+ }
});
ready.then(
() => syncGroup(group),