feat(core) Add Deck#onFrameComplete callback with CPU/GPU timing

Adds a per-frame callback that fires after each on-screen render with
CPU time, optional GPU time, and a flag indicating whether GPU timing
is supported on the device.

GPU timing is sourced from luma.gl's command-encoder timer (timestamp-query
feature, backed by EXT_disjoint_timer_query_webgl2 on WebGL2 and
timestamp-query on WebGPU). When the timing query is unresolved or the
extension is unavailable, gpuTime is reported as null and the callback
still fires so consumers can rely on it as a frame-completion signal.

Use cases:
- Performance instrumentation
- Frame-pacing logic in custom render loops
- Headless capture pipelines that need to know when the GPU is finished
  with a frame before reading pixels

Picking and other off-screen passes do not invoke the callback. Errors
thrown from the user handler are caught and logged so they do not
interrupt the render loop.

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

Author: akre54

docs/api-reference/core/deck.md

@@ -574,6 +574,39 @@ Receives arguments:
 * `gl` - the WebGL context.
 
 
+#### `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.
+
+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.
+
+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.
+
+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:
+
+```js
+new Deck({
+  // ...
+  onFrameComplete: ({cpuTime, gpuTime, gpuTimingSupported}) => {
+    if (gpuTimingSupported && gpuTime !== null) {
+      console.log(`frame: cpu=${cpuTime.toFixed(2)}ms gpu=${gpuTime.toFixed(2)}ms`);
+    } else {
+      console.log(`frame: cpu=${cpuTime.toFixed(2)}ms (no gpu timing)`);
+    }
+  }
+});
+```
+
+
 #### `onError` (Function) {#onerror}
 
 * Default: `console.error`

modules/core/src/lib/deck.ts

@@ -208,6 +208,21 @@ export type DeckProps<ViewsT extends ViewOrViews = null> = {
   onBeforeRender?: (context: {device: Device; gl: WebGL2RenderingContext}) => void;
   /** 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.
+   * 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`.
+   *
+   * Useful for performance instrumentation, frame pacing, and headless capture
+   * pipelines that need to know when the GPU is finished with a frame.
+   */
+  onFrameComplete?: (info: {
+    cpuTime: number;
+    gpuTime: number | null;
+    gpuTimingSupported: boolean;
+    timestamp: number;
+  }) => void;
   /** Called once after gl context and all Deck components are created. */
   onLoad?: () => void;
   /** Called if deck.gl encounters an error.
@@ -279,6 +294,7 @@ const defaultProps: DeckProps = {
   onInteractionStateChange: noop,
   onBeforeRender: noop,
   onAfterRender: noop,
+  onFrameComplete: noop,
   onLoad: noop,
   onError: (error: Error) => log.error(error.message, error.cause)(),
   onHover: null,
@@ -1470,6 +1486,8 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
 
     this.props.onBeforeRender({device, gl});
 
+    const cpuStart = typeof performance !== 'undefined' ? performance.now() : 0;
+
     const opts = {
       target: this.props._framebuffer,
       layers: this.layerManager!.getLayers(),
@@ -1492,6 +1510,68 @@ export default class Deck<ViewsT extends ViewOrViews = null> {
     }
 
     this.props.onAfterRender({device, gl});
+
+    // Fire onFrameComplete only for actual on-screen draws so picking/texture
+    // 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);
+    }
+  }
+
+  /**
+   * Resolve GPU timing for the just-rendered frame and fire onFrameComplete.
+   * GPU time is read asynchronously from the device's command encoder when
+   * available (WebGL2 via EXT_disjoint_timer_query_webgl2, WebGPU via
+   * 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 {
+    const gpuTimingSupported = Boolean(device?.features?.has?.('timestamp-query'));
+
+    const fire = (gpuTime: number | null) => {
+      try {
+        this.props.onFrameComplete?.({
+          cpuTime,
+          gpuTime,
+          gpuTimingSupported,
+          timestamp: typeof performance !== 'undefined' ? performance.now() : 0
+        });
+      } catch (error) {
+        log.warn('onFrameComplete handler threw', error)();
+      }
+    };
+
+    if (!gpuTimingSupported) {
+      fire(null);
+      return;
+    }
+
+    // luma.gl writes the resolved GPU duration to commandEncoder._gpuTimeMs
+    // once the timer query result is available. Poll a few frames to give the
+    // GPU pipeline time to flush, then deliver whatever we have.
+    const commandEncoder = (device as unknown as {commandEncoder?: {_gpuTimeMs?: number}})
+      .commandEncoder;
+    let attempts = 0;
+    const maxAttempts = 10;
+    const poll = () => {
+      const gpuTimeMs = commandEncoder?._gpuTimeMs;
+      if (typeof gpuTimeMs === 'number') {
+        fire(gpuTimeMs);
+        return;
+      }
+      if (++attempts >= maxAttempts) {
+        fire(null);
+        return;
+      }
+      if (typeof requestAnimationFrame === 'function') {
+        requestAnimationFrame(poll);
+      } else {
+        // Headless fallback (Node, tests): don't busy-loop.
+        fire(null);
+      }
+    };
+    poll();
   }
 
   // Callbacks

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

@@ -887,6 +887,168 @@ test('Deck#getView with multiple views', async () => {
   });
 });
 
+test('Deck#onFrameComplete fires per frame with timing info', async () => {
+  const calls: Array<{
+    cpuTime: number;
+    gpuTime: number | null;
+    gpuTimingSupported: boolean;
+    timestamp: number;
+  }> = [];
+
+  await new Promise<void>((resolve, reject) => {
+    const deck = new Deck({
+      device,
+      width: 1,
+      height: 1,
+
+      viewState: {
+        longitude: 0,
+        latitude: 0,
+        zoom: 0
+      },
+
+      layers: [],
+
+      onFrameComplete: info => {
+        calls.push(info);
+      },
+
+      onAfterRender: async () => {
+        // Use the very first onAfterRender to run assertions and finalize.
+        if (calls.length === 0) {
+          // GPU polling is async via rAF; give it time.
+          await sleep(100);
+        }
+        if (calls.length === 0) {
+          return;
+        }
+        try {
+          for (const call of calls) {
+            expect(typeof call.cpuTime, 'cpuTime is a number').toBe('number');
+            expect(call.cpuTime, 'cpuTime is non-negative').toBeGreaterThanOrEqual(0);
+            expect(typeof call.gpuTimingSupported, 'gpuTimingSupported is a boolean').toBe(
+              'boolean'
+            );
+            expect(typeof call.timestamp, 'timestamp is a number').toBe('number');
+            if (call.gpuTime !== null) {
+              expect(call.gpuTime).toBeGreaterThanOrEqual(0);
+            }
+          }
+          deck.finalize();
+          resolve();
+        } catch (error) {
+          deck.finalize();
+          reject(error);
+        }
+      }
+    });
+  });
+});
+
+test('Deck#onFrameComplete is not called for picking passes', async () => {
+  let frameCallCount = 0;
+
+  await new Promise<void>((resolve, reject) => {
+    const deck = new Deck({
+      device,
+      width: 1,
+      height: 1,
+
+      viewState: {
+        longitude: 0,
+        latitude: 0,
+        zoom: 0
+      },
+
+      layers: [
+        new ScatterplotLayer({
+          id: 'pick-test',
+          data: [{position: [0, 0]}],
+          getPosition: d => d.position,
+          pickable: true,
+          radiusMinPixels: 10
+        })
+      ],
+
+      onFrameComplete: () => {
+        frameCallCount++;
+      },
+
+      onLoad: async () => {
+        try {
+          await waitForRender(deck);
+          const baseline = frameCallCount;
+          // Trigger a picking pass; this should not fire onFrameComplete.
+          deck.pickObject({x: 0, y: 0, radius: 1});
+          await sleep(50);
+          expect(frameCallCount, 'picking pass does not fire onFrameComplete').toBe(baseline);
+
+          deck.finalize();
+          resolve();
+        } catch (error) {
+          deck.finalize();
+          reject(error);
+        }
+      }
+    });
+  });
+});
+
+test('Deck#onFrameComplete handler errors do not crash render loop', async () => {
+  let throwCount = 0;
+  let postThrowFrameCount = 0;
+
+  await new Promise<void>((resolve, reject) => {
+    const deck = new Deck({
+      device,
+      width: 1,
+      height: 1,
+
+      viewState: {
+        longitude: 0,
+        latitude: 0,
+        zoom: 0
+      },
+
+      layers: [],
+
+      onLoad: async () => {
+        try {
+          // Wait for first render to complete from initial load.
+          await waitForRender(deck);
+
+          // Install a throwing handler and trigger another redraw.
+          deck.setProps({
+            onFrameComplete: () => {
+              throwCount++;
+              throw new Error('intentional test error');
+            },
+            onAfterRender: () => {
+              if (throwCount > 0) postThrowFrameCount++;
+            }
+          });
+          deck.redraw('error-trigger');
+          // Allow the throwing handler + a follow-up render to occur.
+          await sleep(100);
+          deck.redraw('error-trigger-2');
+          await sleep(100);
+
+          expect(throwCount, 'handler executed and threw').toBeGreaterThanOrEqual(1);
+          expect(postThrowFrameCount, 'render loop continues after handler throw').toBeGreaterThan(
+            0
+          );
+
+          deck.finalize();
+          resolve();
+        } catch (error) {
+          deck.finalize();
+          reject(error);
+        }
+      }
+    });
+  });
+});
+
 test('Deck#props omitted are unchanged', async () => {
   const layer = new ScatterplotLayer({
     id: 'scatterplot-global-data',