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.mdnew file mode 100644index 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.++@vjeuxdiff --git a/docs/specs/AST-094-touch-presentations/spec.md b/docs/specs/AST-094-touch-presentations/spec.mdindex 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.tsindex 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.tsindex 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.tsindex 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),