feat(core) Add animationsInProgress + layersRendered to onFrameComplete

Extends the onFrameComplete callback payload with animation state so
consumers (notably headless capture pipelines) can tell when a frame is
visually settled vs. when timer-driven animations would change the next
frame.

`animationsInProgress` aggregates three sources:
- layer uniform transitions (existing `Layer#hasUniformTransition`)
- GPU attribute interpolations (new `AttributeManager#hasActiveTransitions`,
  delegating to a new `AttributeTransitionManager#isInProgress`)
- viewport transitions (new `Controller#hasActiveTransition`, surfaced
  through new `ViewManager#hasActiveTransitions`)

A new `Layer#hasActiveTransitions` aggregates uniform + attribute state
per layer; `LayerManager#hasActiveTransitions` aggregates across layers.
Time-based layer props such as `TripsLayer.currentTime` are intentionally
not tracked — they are driven explicitly by the application each frame.

`layersRendered` exposes the count of layers submitted to the renderer
for the just-finished pass, useful for instrumentation.

Animation state is re-read at fire time so that values reported via the
async GPU-timing poll path reflect the freshest state.

Tests:
- updated existing onFrameComplete tests to assert the new fields
- added a viewport-transition test that confirms animationsInProgress
  flips true → false across the lifetime of a flyTo-style transition

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: akre54

docs/api-reference/core/deck.md

@@ -576,22 +576,29 @@ Receives arguments:
 
 #### `onFrameComplete` (Function) {#onframecomplete}
 
-Called after each on-screen frame completes rendering, with CPU and (when supported) GPU timing information. Picking and other off-screen passes do not invoke this callback.
+Called after each on-screen frame completes rendering, with CPU and (when supported) GPU timing information plus animation state. Picking and other off-screen passes do not invoke this callback.
 
-This is useful for performance instrumentation, frame-pacing logic, and headless capture pipelines that need to know when the GPU has finished a frame before reading pixels.
+This is useful for performance instrumentation, frame-pacing logic, and headless capture pipelines that need to know when the GPU has finished a frame before reading pixels and whether any animations would change the next frame.
 
 Receives a single object argument with:
 
 * `cpuTime` (number) - CPU time spent in the deck.gl draw pipeline for this frame, in milliseconds.
 * `gpuTime` (number | null) - GPU time for this frame in milliseconds, when available. `null` if GPU timing is not supported on the current device or the timing query did not resolve in time.
 * `gpuTimingSupported` (boolean) - whether the underlying device exposes the `timestamp-query` feature (WebGL2: `EXT_disjoint_timer_query_webgl2`, WebGPU: `timestamp-query`).
 * `timestamp` (number) - high-resolution `performance.now()` timestamp of when the callback fired.
+* `layersRendered` (number) - the number of layers submitted to the renderer for this frame (includes sub-layers expanded from composite layers).
+* `animationsInProgress` (boolean) - `true` while any timer-driven animation is still running:
+  - layer uniform transitions (e.g. `transitions: {opacity: 300}`)
+  - GPU attribute interpolations (e.g. `transitions: {getRadius: {duration: 300}}`)
+  - viewport transitions (e.g. `flyTo`/`linearTransition` triggered by setting `transitionDuration`).
+
+  Time-based layer props such as `TripsLayer.currentTime` are *not* included since they are driven explicitly by the application each frame. For headless video export, treating each frame as independent (no transitions) is preferred — disable layer/viewport transitions in your scene rather than relying on `animationsInProgress` to settle.
 
 GPU timing is read asynchronously: the callback may be deferred a few frames while the GPU pipeline flushes. If the timing query does not resolve after a small number of `requestAnimationFrame` polls, `gpuTime` is reported as `null`.
 
 Errors thrown from `onFrameComplete` are caught and logged via `log.warn` and do not interrupt the render loop.
 
-Example:
+Example — performance instrumentation:
 
 ```js
 new Deck({
@@ -606,6 +613,19 @@ new Deck({
 });
 ```
 
+Example — headless capture: wait until animations settle before capturing.
+
+```js
+const deck = new Deck({
+  // ...
+  onFrameComplete: ({animationsInProgress}) => {
+    if (!animationsInProgress) {
+      capturePixels(deck);
+    }
+  }
+});
+```
+
 
 #### `onError` (Function) {#onerror}
 

modules/core/src/controllers/controller.ts

@@ -199,6 +199,11 @@ export default abstract class Controller<ControllerState extends IViewState<Cont
     this.transitionManager.finalize();
   }
 
+  /** Returns `true` if a viewport transition (e.g. flyTo) is currently animating. */
+  hasActiveTransition(): boolean {
+    return Boolean(this.transitionManager.transition?.inProgress);
+  }
+
   /**
    * Callback for events
    */

modules/core/src/lib/attribute/attribute-manager.ts

@@ -115,6 +115,11 @@ export default class AttributeManager {
     this.needsRedraw = true;
   }
 
+  /** Returns `true` if any attribute is currently being interpolated by a GPU transition. */
+  hasActiveTransitions(): boolean {
+    return this.attributeTransitionManager.isInProgress();
+  }
+
   // Adds attributes
   add(attributes: {[id: string]: AttributeOptions}) {
     this._add(attributes);

modules/core/src/lib/attribute/attribute-transition-manager.ts

@@ -96,6 +96,16 @@ export default class AttributeTransitionManager {
     return transition && transition.inProgress;
   }
 
+  /** Returns `true` if any tracked attribute is currently transitioning. */
+  isInProgress(): boolean {
+    for (const attributeName in this.transitions) {
+      if (this.transitions[attributeName].inProgress) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   // Get all the animated attributes
   getAttributes(): {[id: string]: Attribute} {
     const animatedAttributes = {};

modules/core/src/lib/deck.ts

@@ -209,19 +209,30 @@ export type DeckProps<ViewsT extends ViewOrViews = null> = {
   /** Called right after the canvas rerenders. */
   onAfterRender?: (context: {device: Device; gl: WebGL2RenderingContext}) => void;
   /**
-   * Called after each frame completes rendering, with CPU and GPU timing info.
+   * Called after each on-screen frame completes rendering, with CPU and GPU
+   * timing info plus animation state.
+   *
    * GPU timing is reported when supported by the underlying device
-   * (WebGL: `EXT_disjoint_timer_query_webgl2`, WebGPU: `timestamp-query`); otherwise
-   * `gpuTime` is `null` and `gpuTimingSupported` is `false`.
+   * (WebGL: `EXT_disjoint_timer_query_webgl2`, WebGPU: `timestamp-query`);
+   * otherwise `gpuTime` is `null` and `gpuTimingSupported` is `false`.
+   *
+   * `animationsInProgress` is `true` while any timer-driven animation is still
+   * running: layer uniform transitions, GPU attribute interpolations, or
+   * viewport transitions (e.g. `flyTo`). Time-based layer props such as
+   * `TripsLayer.currentTime` are not included since they are driven explicitly
+   * by the application each frame.
    *
    * Useful for performance instrumentation, frame pacing, and headless capture
-   * pipelines that need to know when the GPU is finished with a frame.
+   * pipelines that need to know when the GPU is finished with a frame and
+   * whether any animations would change the next frame.
    */
   onFrameComplete?: (info: {
     cpuTime: number;
     gpuTime: number | null;
     gpuTimingSupported: boolean;
     timestamp: number;
+    layersRendered: number;
+    animationsInProgress: boolean;
   }) => void;
   /** Called once after gl context and all Deck components are created. */
   onLoad?: () => void;
@@ -1515,7 +1526,8 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
     // passes don't pollute the timing stream consumed by capture pipelines.
     if (opts.pass === 'screen' && this.props.onFrameComplete !== noop) {
       const cpuTime = (typeof performance !== 'undefined' ? performance.now() : 0) - cpuStart;
-      this._fireFrameComplete(device, cpuTime);
+      const layersRendered = opts.layers.length;
+      this._fireFrameComplete(device, cpuTime, layersRendered);
     }
   }
 
@@ -1526,16 +1538,23 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
    * timestamp-query). When unavailable, we still fire the callback so consumers
    * can track frame completion and CPU timing.
    */
-  private _fireFrameComplete(device: Device, cpuTime: number): void {
+  private _fireFrameComplete(device: Device, cpuTime: number, layersRendered: number): void {
     const gpuTimingSupported = Boolean(device?.features?.has?.('timestamp-query'));
 
     const fire = (gpuTime: number | null) => {
+      // Re-read animation state at fire time so async GPU-poll deferrals
+      // still report the freshest value.
+      const animationsInProgress =
+        Boolean(this.layerManager?.hasActiveTransitions()) ||
+        Boolean(this.viewManager?.hasActiveTransitions());
       try {
         this.props.onFrameComplete?.({
           cpuTime,
           gpuTime,
           gpuTimingSupported,
-          timestamp: typeof performance !== 'undefined' ? performance.now() : 0
+          timestamp: typeof performance !== 'undefined' ? performance.now() : 0,
+          layersRendered,
+          animationsInProgress
         });
       } catch (error) {
         log.warn('onFrameComplete handler threw', error)();

modules/core/src/lib/layer-manager.ts

@@ -166,6 +166,14 @@ export default class LayerManager {
       : this.layers;
   }
 
+  /** Returns `true` if any managed layer has an in-progress uniform or attribute transition. */
+  hasActiveTransitions(): boolean {
+    for (const layer of this.layers) {
+      if (layer.hasActiveTransitions()) return true;
+    }
+    return false;
+  }
+
   /** Set props needed for layer rendering and picking. */
   setProps(props: any): void {
     if ('debug' in props) {

modules/core/src/lib/layer.ts

@@ -613,6 +613,18 @@ export default abstract class Layer<PropsT extends {} = {}> extends Component<
     return this.internalState?.uniformTransitions.active || false;
   }
 
+  /**
+   * Checks whether the layer has any in-progress timer-driven animations:
+   * uniform transitions or GPU attribute interpolations. Used by Deck to
+   * report animation state to `onFrameComplete` consumers.
+   */
+  hasActiveTransitions(): boolean {
+    if (this.hasUniformTransition()) return true;
+    const attributeManager = this.getAttributeManager();
+    if (attributeManager?.hasActiveTransitions()) return true;
+    return false;
+  }
+
   /** Called when this layer is rendered into the given viewport */
   activateViewport(viewport: Viewport): void {
     if (!this.internalState) {

modules/core/src/lib/view-manager.ts

@@ -133,6 +133,14 @@ export default class ViewManager<ViewsT extends View[]> {
     this._needsRedraw = this._needsRedraw || reason;
   }
 
+  /** Returns `true` if any controller is currently animating a viewport transition. */
+  hasActiveTransitions(): boolean {
+    for (const id in this.controllers) {
+      if (this.controllers[id]?.hasActiveTransition()) return true;
+    }
+    return false;
+  }
+
   /** Checks each viewport for transition updates */
   updateViewStates(): void {
     for (const viewId in this.controllers) {

test/modules/core/lib/deck.spec.ts

@@ -887,12 +887,14 @@ test('Deck#getView with multiple views', async () => {
   });
 });
 
-test('Deck#onFrameComplete fires per frame with timing info', async () => {
+test('Deck#onFrameComplete fires per frame with timing and animation info', async () => {
   const calls: Array<{
     cpuTime: number;
     gpuTime: number | null;
     gpuTimingSupported: boolean;
     timestamp: number;
+    layersRendered: number;
+    animationsInProgress: boolean;
   }> = [];
 
   await new Promise<void>((resolve, reject) => {
@@ -930,6 +932,13 @@ test('Deck#onFrameComplete fires per frame with timing info', async () => {
               'boolean'
             );
             expect(typeof call.timestamp, 'timestamp is a number').toBe('number');
+            expect(typeof call.layersRendered, 'layersRendered is a number').toBe('number');
+            expect(call.layersRendered, 'layersRendered is non-negative').toBeGreaterThanOrEqual(0);
+            expect(typeof call.animationsInProgress, 'animationsInProgress is a boolean').toBe(
+              'boolean'
+            );
+            // No layer transitions or viewport transitions in this scene.
+            expect(call.animationsInProgress, 'no animations active in static scene').toBe(false);
             if (call.gpuTime !== null) {
               expect(call.gpuTime).toBeGreaterThanOrEqual(0);
             }
@@ -945,6 +954,63 @@ test('Deck#onFrameComplete fires per frame with timing info', async () => {
   });
 });
 
+test('Deck#onFrameComplete reports animationsInProgress during viewport transition', async () => {
+  let sawTransitionInProgress = false;
+  let sawTransitionEnded = false;
+
+  await new Promise<void>((resolve, reject) => {
+    const deck = new Deck({
+      device,
+      width: 1,
+      height: 1,
+
+      controller: true,
+      initialViewState: {
+        longitude: 0,
+        latitude: 0,
+        zoom: 0
+      },
+
+      views: [new MapView({id: 'main'})],
+      layers: [],
+
+      onFrameComplete: info => {
+        if (info.animationsInProgress) sawTransitionInProgress = true;
+        else if (sawTransitionInProgress) sawTransitionEnded = true;
+      },
+
+      onLoad: async () => {
+        try {
+          // Trigger a viewport transition.
+          deck.setProps({
+            initialViewState: {
+              longitude: 10,
+              latitude: 10,
+              zoom: 5,
+              transitionDuration: 200
+            }
+          });
+          // Wait for transition to start, run, and complete.
+          await sleep(500);
+
+          expect(sawTransitionInProgress, 'animationsInProgress observed during transition').toBe(
+            true
+          );
+          expect(sawTransitionEnded, 'animationsInProgress flips back to false after end').toBe(
+            true
+          );
+
+          deck.finalize();
+          resolve();
+        } catch (error) {
+          deck.finalize();
+          reject(error);
+        }
+      }
+    });
+  });
+});
+
 test('Deck#onFrameComplete is not called for picking passes', async () => {
   let frameCallCount = 0;