perf: schedule engine frames at the composition frame rate (throttled ticker) (#426)

Follow-up to the discussion in #420 (and #419): as measured there, the
rebuild gate from #423 was not enough — the auto-animation's ticker
still re-armed a frame callback on every vsync, so the engine kept
running the full pipeline (frame scheduling, build/paint flush, scene
submission, raster) at the display refresh rate. Gating rebuilds alone
recovered only ~2% CPU because that per-frame engine overhead dominates.

## Approach

Drive the auto-animation with a **throttled `Ticker`**: after each tick,
re-arming the vsync callback is delayed with a one-shot timer aimed at
the last vsync preceding the next composition-frame boundary (each tick
timestamp *is* a vsync timestamp, so the vsync phase is known). Timers
never fire early, so the frame request goes out one vsync ahead and the
tick lands on the first vsync at or after the boundary:

- no *skipped* frames when the rates don't divide (24/25fps content on a
60Hz display),
- no *slipped* frames when they match (60fps content on 60Hz stays at
60, the throttle becomes a no-op),
- elapsed time still comes from frame timestamps, so a late timer
**drops** frames instead of slowing the animation down.

Because the ticker parks on a timer between composition frames, no
engine frame is even scheduled in between — the whole pipeline runs at
the composition rate, which is where the savings come from. This
achieves the gains of the Timer-drive proposal in #420 while keeping
`AnimationController` semantics (statuses, wall-clock accuracy, curves),
`TickerMode` (including `forceFrames`), and app-lifecycle behavior (in
the background the timer chain parks itself after a single fire), with
no new public controller API.

## Measured results (macOS profile build, 120Hz display, composition in
a ListView)

| | Engine frames/s | Process CPU |
|---|---|---|
| master | 120 | 13.8% |
| this PR | 30 (LottieLogo1, 30fps) | 6.3% |

Composition-rate accuracy across assets: 24fps → 24 frames/s, 25fps →
~25, 30fps → ~30, 60fps → ~60.

## Behavior notes

- **External `AnimationController`s are unaffected** — they keep the
vsync-driven path (plus the #423 gate).
- **`flutter test` is unaffected**: the throttle is inactive under the
test runner so `tester.pumpAndSettle()` keeps observing the animation
exactly as before. `debugThrottleAnimationsInTests` re-enables it (used
by this package's own throttle tests).
- `FrameRate.max` keeps rendering every display frame; `frameRate:
FrameRate(x)` throttles to x.
- The vsync period is resolved from the widget's own `View` (multi-view
safe, 60Hz fallback).

## Extras

- `FrameRate.resolveFps` — single resolver for the `composition`/`max`
sentinels (previously duplicated in `roundProgress` and the widget).
- `example/lib/frame_rate_demo.dart` — interactive test page with live
engine-fps/build/raster metrics, asset & frame-rate pickers,
TickerMode/lifecycle/external-controller toggles, concurrent staggered
animations, and a side-by-side pacing comparison (`flutter run -t
lib/frame_rate_demo.dart --profile`).
- `example/lib/bench_main.dart` — headless benchmark entrypoint
(`--dart-define=ASSET=...`).

## Testing

9 dedicated widget tests in `test/frame_rate_throttle_test.dart`
(throttled rebuild rate, no engine frame scheduled between composition
frames, no-op at/above display rate, wall-clock correctness, no skipped
frames at 25fps-on-60Hz, TickerMode pause/resume, zero frames when
mounted under a disabled TickerMode, pumpAndSettle compatibility). Full
suite: 1025 tests pass, goldens unchanged.

Author: xvrh

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 3.6.0
+- Reduce CPU usage by only scheduling animation frames at the composition frame rate instead of on every vsync
+
 ## 3.5.2
 - Fix a CanvasKit stack overflow when drawing animated Trim Paths on Flutter web
 

example/android/app/build.gradle

@@ -1,6 +1,6 @@
 plugins {
     id "com.android.application"
-    id "kotlin-android"
+    id "org.jetbrains.kotlin.android"
     id "dev.flutter.flutter-gradle-plugin"
 }
 

example/android/build.gradle

@@ -1,16 +1,3 @@
-buildscript {
-    ext.kotlin_version = '1.7.10'
-    repositories {
-        google()
-        mavenCentral()
-    }
-
-    dependencies {
-        classpath 'com.android.tools.build:gradle:7.3.0'
-        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
-    }
-}
-
 allprojects {
     repositories {
         google()

example/android/gradle.properties

@@ -1,3 +1,7 @@
 org.gradle.jvmargs=-Xmx1536M
 android.useAndroidX=true
 android.enableJetifier=true
+# This builtInKotlin flag was added automatically by Flutter migrator
+android.builtInKotlin=false
+# This newDsl flag was added automatically by Flutter migrator
+android.newDsl=false

example/android/gradle/wrapper/gradle-wrapper.properties

@@ -2,4 +2,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.5-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-all.zip

example/android/settings.gradle

@@ -5,16 +5,21 @@ pluginManagement {
         def flutterSdkPath = properties.getProperty("flutter.sdk")
         assert flutterSdkPath != null, "flutter.sdk not set in local.properties"
         return flutterSdkPath
-    }
-    settings.ext.flutterSdkPath = flutterSdkPath()
+    }()
 
-    includeBuild("${settings.ext.flutterSdkPath}/packages/flutter_tools/gradle")
+    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")
 
-    plugins {
-        id "dev.flutter.flutter-gradle-plugin" version "1.0.0" apply false
+    repositories {
+        google()
+        mavenCentral()
+        gradlePluginPortal()
     }
 }
 
-include ":app"
+plugins {
+    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
+    id "com.android.application" version "8.6.0" apply false
+    id "org.jetbrains.kotlin.android" version "1.8.22" apply false
+}
 
-apply from: "${settings.ext.flutterSdkPath}/packages/flutter_tools/gradle/app_plugin_loader.gradle"
+include ":app"

example/lib/bench_main.dart

@@ -0,0 +1,40 @@
+import 'dart:async';
+import 'package:flutter/material.dart';
+import 'package:flutter/scheduler.dart';
+import 'package:lottie/lottie.dart';
+
+void main() {
+  WidgetsFlutterBinding.ensureInitialized();
+  var frames = 0;
+  SchedulerBinding.instance.addTimingsCallback((timings) {
+    frames += timings.length;
+  });
+  Timer.periodic(const Duration(seconds: 1), (_) {
+    // ignore: avoid_print
+    print('frames/s: $frames');
+    frames = 0;
+  });
+  runApp(const BenchApp());
+}
+
+class BenchApp extends StatelessWidget {
+  const BenchApp({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      home: Scaffold(
+        body: ListView(
+          children: [
+            Lottie.asset(
+              const String.fromEnvironment(
+                'ASSET',
+                defaultValue: 'assets/LottieLogo1.json',
+              ),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}