fix(animations): account for Element.animate exceptions (#64506)

JoostK · thePunderWoman · commit bd38cd45a5fb · 2025-10-21T16:49:43.000Z
In certain scenarios `Element.animate` fails, manifesting in an exception (Firefox) or a null return value (Chromium). The null value is not conform WebIDL but handled gracefully in this commit regardless. Closes #64486 PR Close #64506
diff --git a/packages/animations/browser/src/render/web_animations/web_animations_player.ts b/packages/animations/browser/src/render/web_animations/web_animations_player.ts
@@ -28,8 +28,7 @@ export class WebAnimationsPlayer implements AnimationPlayer {
   private _originalOnDoneFns: Function[] = [];
   private _originalOnStartFns: Function[] = [];
 
-  // using non-null assertion because it's re(set) by init();
-  public readonly domPlayer!: Animation;
+  public domPlayer: Animation | null = null;
   public time = 0;
 
   public parentPlayer: AnimationPlayer | null = null;
@@ -55,34 +54,43 @@ export class WebAnimationsPlayer implements AnimationPlayer {
   }
 
   init(): void {
-    this._buildPlayer();
+    if (!this._buildPlayer()) {
+      return;
+    }
     this._preparePlayerBeforeStart();
   }
 
-  private _buildPlayer(): void {
-    if (this._initialized) return;
+  private _buildPlayer(): Animation | null {
+    if (this._initialized) return this.domPlayer;
     this._initialized = true;
 
     const keyframes = this.keyframes;
-    // @ts-expect-error overwriting a readonly property
-    this.domPlayer = this._triggerWebAnimation(this.element, keyframes, this.options);
+
+    const animation = this._triggerWebAnimation(this.element, keyframes, this.options);
+    if (!animation) {
+      this._onFinish();
+      return null;
+    }
+
+    this.domPlayer = animation;
     this._finalKeyframe = keyframes.length ? keyframes[keyframes.length - 1] : new Map();
     const onFinish = () => this._onFinish();
-    this.domPlayer.addEventListener('finish', onFinish);
+    animation.addEventListener('finish', onFinish);
     this.onDestroy(() => {
       // We must remove the `finish` event listener once an animation has completed all its
       // iterations. This action is necessary to prevent a memory leak since the listener captures
       // `this`, creating a closure that prevents `this` from being garbage collected.
-      this.domPlayer.removeEventListener('finish', onFinish);
+      animation.removeEventListener('finish', onFinish);
     });
+    return animation;
   }
 
   private _preparePlayerBeforeStart() {
     // this is required so that the player doesn't start to animate right away
     if (this._delay) {
       this._resetDomPlayerState();
     } else {
-      this.domPlayer.pause();
+      this.domPlayer?.pause();
     }
   }
 
@@ -99,8 +107,16 @@ export class WebAnimationsPlayer implements AnimationPlayer {
     element: HTMLElement,
     keyframes: Array<ɵStyleDataMap>,
     options: any,
-  ): Animation {
-    return element.animate(this._convertKeyframesToObject(keyframes), options);
+  ): Animation | null {
+    const keyframesObject = this._convertKeyframesToObject(keyframes);
+
+    // Account for `Element.animate` throwing an exception (Firefox) or returning null (Chromium) in certain
+    // conditions. See https://github.com/angular/angular/issues/64486
+    try {
+      return element.animate(keyframesObject, options);
+    } catch {
+      return null;
+    }
   }
 
   onStart(fn: () => void): void {
@@ -118,7 +134,10 @@ export class WebAnimationsPlayer implements AnimationPlayer {
   }
 
   play(): void {
-    this._buildPlayer();
+    const player = this._buildPlayer();
+    if (!player) {
+      return;
+    }
     if (!this.hasStarted()) {
       this._onStartFns.forEach((fn) => fn());
       this._onStartFns = [];
@@ -127,16 +146,17 @@ export class WebAnimationsPlayer implements AnimationPlayer {
         this._specialStyles.start();
       }
     }
-    this.domPlayer.play();
+    player.play();
   }
 
   pause(): void {
     this.init();
-    this.domPlayer.pause();
+    this.domPlayer?.pause();
   }
 
   finish(): void {
     this.init();
+    if (!this.domPlayer) return;
     if (this._specialStyles) {
       this._specialStyles.finish();
     }
@@ -154,9 +174,7 @@ export class WebAnimationsPlayer implements AnimationPlayer {
   }
 
   private _resetDomPlayerState() {
-    if (this.domPlayer) {
-      this.domPlayer.cancel();
-    }
+    this.domPlayer?.cancel();
   }
 
   restart(): void {
@@ -182,13 +200,18 @@ export class WebAnimationsPlayer implements AnimationPlayer {
   }
 
   setPosition(p: number): void {
-    if (this.domPlayer === undefined) {
+    if (!this.domPlayer) {
       this.init();
     }
-    this.domPlayer.currentTime = p * this.time;
+    if (this.domPlayer) {
+      this.domPlayer.currentTime = p * this.time;
+    }
   }
 
   getPosition(): number {
+    if (!this.domPlayer) {
+      return this._initialized ? 1 : 0;
+    }
     // tsc is complaining with TS2362 without the conversion to number
     return +(this.domPlayer.currentTime ?? 0) / this.time;
   }
diff --git a/packages/animations/browser/test/render/web_animations/web_animations_player_spec.ts b/packages/animations/browser/test/render/web_animations/web_animations_player_spec.ts
@@ -98,6 +98,60 @@ describe('WebAnimationsPlayer tests', () => {
     expect(p.currentTime).toEqual(500);
     expect(p.log).toEqual(['play']);
   });
+
+  // https://github.com/angular/angular/issues/64486
+  it('should gracefully handle animation being null in Chromium-based browsers', () => {
+    element['animate'] = () => {
+      return null;
+    };
+    const player = new WebAnimationsPlayer(element, [], {duration: 1000});
+
+    let started = false;
+    let done = false;
+    player.onStart(() => (started = true));
+    player.onDone(() => (done = true));
+
+    player.play();
+
+    expect(player.hasStarted()).toBe(false);
+    expect(started).toBe(false);
+    expect(done).toBe(true);
+
+    player.pause();
+    player.play();
+    player.restart();
+
+    expect(player.getPosition()).toBe(1);
+    player.setPosition(0.5);
+    expect(player.getPosition()).toBe(1);
+  });
+
+  // https://github.com/angular/angular/issues/64486
+  it('should gracefully handle animation exceptions in Firefox', () => {
+    element['animate'] = () => {
+      throw new Error('Simulated error');
+    };
+    const player = new WebAnimationsPlayer(element, [], {duration: 1000});
+
+    let started = false;
+    let done = false;
+    player.onStart(() => (started = true));
+    player.onDone(() => (done = true));
+
+    player.play();
+
+    expect(player.hasStarted()).toBe(false);
+    expect(started).toBe(false);
+    expect(done).toBe(true);
+
+    player.pause();
+    player.play();
+    player.restart();
+
+    expect(player.getPosition()).toBe(1);
+    player.setPosition(0.5);
+    expect(player.getPosition()).toBe(1);
+  });
 });
 
 class MockDomAnimation implements Animation {
