feat: add animate in MTS

Author: f0rdream

.changeset/weak-animals-search.md

@@ -0,0 +1,19 @@
+---
+'@lynx-js/react': patch
+---
+
+Add `animate` API in Main Thread Script(MTS), so you can now control a CSS animation imperatively
+
+```
+function startAnimation() {
+  'main thread'
+  const animation = ele.animate([
+    { opacity: 0 },
+    { opacity: 1 },
+  ], {
+    duration: 3000
+  })
+
+  animation.pause()
+}
+```

packages/react/worklet-runtime/__test__/api/element.test.js

@@ -3,6 +3,7 @@
 // LICENSE file in the root directory of this source tree.
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
+import { AnimationOperation } from '../../src/api/animation/animation';
 import { Element } from '../../src/api/element';
 import { initWorklet } from '../../src/workletRuntime';
 
@@ -21,6 +22,7 @@ beforeEach(() => {
   globalThis.__QuerySelectorAll = vi.fn();
   globalThis.__InvokeUIMethod = vi.fn();
   globalThis.__FlushElementTree = vi.fn();
+  globalThis.__ElementAnimate = vi.fn();
 });
 
 afterEach(() => {
@@ -142,4 +144,51 @@ describe('Element', () => {
     await vi.runAllTimersAsync();
     expect(globalThis.__FlushElementTree).toHaveBeenCalledTimes(1);
   });
+
+  it('should start animation when created', () => {
+    const element = new Element('element-instance');
+    const animation = element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 1000 });
+    expect(globalThis.__ElementAnimate).toHaveBeenCalledWith('element-instance', [
+      AnimationOperation.START,
+      animation.id,
+      [{ opacity: 0 }, { opacity: 1 }],
+      { duration: 1000 },
+    ]);
+  });
+
+  it('should cancel animation when canceled', () => {
+    const element = new Element('element-instance');
+    const animation = element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 1000 });
+    animation.cancel();
+    expect(globalThis.__ElementAnimate).toHaveBeenCalledWith('element-instance', [
+      AnimationOperation.CANCEL,
+      animation.id,
+    ]);
+  });
+
+  it('should pause animation when paused', () => {
+    const element = new Element('element-instance');
+    const animation = element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 1000 });
+    animation.pause();
+    expect(globalThis.__ElementAnimate).toHaveBeenCalledWith('element-instance', [
+      AnimationOperation.PAUSE,
+      animation.id,
+    ]);
+  });
+
+  it('should play animation when played', () => {
+    const element = new Element('element-instance');
+    const animation = element.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 1000 });
+    expect(globalThis.__ElementAnimate).toHaveBeenCalledWith('element-instance', [
+      AnimationOperation.START,
+      animation.id,
+      [{ opacity: 0 }, { opacity: 1 }],
+      { duration: 1000 },
+    ]);
+    animation.play();
+    expect(globalThis.__ElementAnimate).toHaveBeenCalledWith('element-instance', [
+      AnimationOperation.PLAY,
+      animation.id,
+    ]);
+  });
 });

packages/react/worklet-runtime/src/api/animation/animation.ts

@@ -0,0 +1,48 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import type { KeyframeEffect } from './effect.js';
+
+export enum AnimationOperation {
+  START = 0, // Start a new animation
+  PLAY = 1, // Play/resume a paused animation
+  PAUSE = 2, // Pause an existing animation
+  CANCEL = 3, // Cancel an animation
+}
+
+export class Animation {
+  static count = 0;
+  public readonly effect: KeyframeEffect;
+  public readonly id: string;
+
+  constructor(effect: KeyframeEffect) {
+    this.effect = effect;
+    this.id = '__lynx-inner-js-animation-' + Animation.count++;
+    this.start();
+  }
+
+  public cancel(): void {
+    // @ts-expect-error expected
+    return __ElementAnimate(this.effect.target.element, [AnimationOperation.CANCEL, this.id]);
+  }
+
+  public pause(): void {
+    // @ts-expect-error expected
+    return __ElementAnimate(this.effect.target.element, [AnimationOperation.PAUSE, this.id]);
+  }
+
+  public play(): void {
+    // @ts-expect-error expected
+    return __ElementAnimate(this.effect.target.element, [AnimationOperation.PLAY, this.id]);
+  }
+
+  private start(): void {
+    // @ts-expect-error expected
+    return __ElementAnimate(this.effect.target.element, [
+      AnimationOperation.START,
+      this.id,
+      this.effect.keyframes,
+      this.effect.options,
+    ]);
+  }
+}

packages/react/worklet-runtime/src/api/animation/effect.ts

@@ -0,0 +1,20 @@
+// Copyright 2025 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import type { Element } from '../element.js';
+
+export class KeyframeEffect {
+  public readonly target: Element;
+  public readonly keyframes: Record<string, number | string>[];
+  public readonly options: Record<string, number | string>;
+
+  constructor(
+    target: Element,
+    keyframes: Record<string, number | string>[],
+    options: Record<string, number | string>,
+  ) {
+    this.target = target;
+    this.keyframes = keyframes;
+    this.options = options;
+  }
+}

packages/react/worklet-runtime/src/api/element.ts

@@ -1,6 +1,9 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
+import { Animation } from './animation/animation.js';
+import { KeyframeEffect } from './animation/effect.js';
+
 export class Element {
   private static willFlush = false;
 
@@ -54,6 +57,11 @@ export class Element {
     });
   }
 
+  public animate(effect: Record<string, number | string>[], options: Record<string, number | string>): Animation {
+    const animation = new Animation(new KeyframeEffect(this, effect, options));
+    return animation;
+  }
+
   public invoke(
     methodName: string,
     params?: Record<string, unknown>,

packages/react/worklet-runtime/src/types/elementApi.d.ts

@@ -46,3 +46,50 @@ declare function __QuerySelectorAll(
 ): ElementNode[];
 
 declare function __SetAttribute(e: ElementNode, key: string, value: unknown): void;
+
+/**
+ * Animation operation types for ElementAnimate function
+ */
+enum AnimationOperation {
+  START = 0, // Start a new animation
+  PAUSE = 1, // Pause an existing animation
+  PLAY = 2, // Play/resume a paused animation
+  CANCEL = 3, // Cancel an animation
+}
+
+/**
+ * Animation timing options configuration
+ */
+interface AnimationTimingOptions {
+  name?: string; // Animation name (optional, auto-generated if not provided)
+  duration?: number | string; // Animation duration
+  delay?: number | string; // Animation delay
+  iterationCount?: number | string; // Number of iterations (can be 'infinite')
+  fillMode?: string; // Animation fill mode
+  timingFunction?: string; // Animation timing function
+  direction?: string; // Animation direction
+}
+
+/**
+ * Keyframe definition for animation
+ */
+type Keyframe = Record<string, string | number>;
+
+/**
+ * ElementAnimate function - controls animations on DOM elements
+ * @param element - The DOM element to animate (FiberElement reference)
+ * @param args - Animation configuration array
+ * @returns undefined
+ */
+declare function __ElementAnimate(
+  element: FiberElement,
+  args: [
+    operation: AnimationOperation, // Animation operation type
+    name: string, // Animation name
+    keyframes: Keyframe[], // Array of keyframes
+    options?: AnimationTimingOptions, // Timing and configuration options
+  ] | [
+    operation: AnimationOperation.PAUSE | AnimationOperation.PLAY | AnimationOperation.CANCEL, // Only PAUSE or PLAY
+    name: string, // Animation name to pause/play
+  ],
+): void;