animation-profiler

What this skill does

# Animation Profiler

Instrument a page to capture and analyze all CSS and JavaScript animations.
Uses the CDP Animation domain to enumerate active animations, PerformanceObserver
for long animation frames (jank detection), and requestAnimationFrame hooks for
frame timing analysis.

## When to Use

- Diagnosing janky animations or low frame rates.
- Finding animations that trigger layout/paint instead of using compositor-only properties.
- Auditing `will-change` usage (overuse causes memory waste, underuse causes jank).
- Profiling animation performance before a launch.
- Identifying which animations are running and their durations/timing functions.

## Prerequisites

- **Playwright MCP server** connected and responding (all `mcp__playwright__browser_*` tools available).
- **Chromium-based browser** required for CDP `Animation.enable`, `LayerTree.enable`, and `Rendering.setShowPaintRects`.
- Target page must have visible animations (CSS transitions, CSS animations, or JS-driven animations).

## Workflow

### Step 1 -- Navigate to the Target Page

```
browser_navigate({ url: "<target_url>" })
```

### Step 2 -- Enable CDP Animation Domain

Capture all animation start events via CDP.

```javascript
browser_run_code({
  code: `async (page) => {
    const client = await page.context().newCDPSession(page);

    // Enable Animation domain
    await client.send('Animation.enable');

    const animations = [];
    client.on('Animation.animationStarted', (params) => {
      const anim = params.animation;
      animations.push({
        id: anim.id,
        name: anim.name || '(unnamed)',
        type: anim.type, // CSSTransition, CSSAnimation, WebAnimation
        duration: anim.source ? anim.source.duration : null,
        delay: anim.source ? anim.source.delay : null,
        iterationStart: anim.source ? anim.source.iterationStart : null,
        iterations: anim.source ? anim.source.iterations : null,
        easing: anim.source ? anim.source.easing : null,
        backendNodeId: anim.source ? anim.source.backendNodeId : null,
        keyframesRule: anim.source ? anim.source.keyframesRule : null,
        startTime: anim.startTime,
        playbackRate: anim.playbackRate,
        cssId: anim.cssId || null
      });
    });

    page.__animationData = animations;
    return 'Animation domain enabled, listening for animations';
  }`
})
```

### Step 3 -- Enable Layer Tree Inspection

Inspect compositor layers to understand which elements have their own layers.

```javascript
browser_run_code({
  code: `async (page) => {
    const client = await page.context().newCDPSession(page);
    await client.send('LayerTree.enable');

    const layers = [];
    client.on('LayerTree.layerTreeDidChange', (params) => {
      if (params.layers) {
        layers.length = 0;
        for (const layer of params.layers) {
          layers.push({
            layerId: layer.layerId,
            parentLayerId: layer.parentLayerId || null,
            backendNodeId: layer.backendNodeId || null,
            width: layer.width,
            height: layer.height,
            paintCount: layer.paintCount,
            drawsContent: layer.drawsContent,
            compositingReasons: layer.compositingReasonIds || []
          });
        }
      }
    });

    page.__layerData = layers;
    return 'LayerTree domain enabled';
  }`
})
```

### Step 4 -- Install Frame Timing Monitor

Hook `requestAnimationFrame` to measure actual frame durations and detect
dropped frames.

```javascript
browser_evaluate({
  function: `() => {
    window.__frameTiming = {
      frames: [],
      startTime: performance.now(),
      frameCount: 0,
      droppedFrames: 0,
      maxFrameTime: 0,
      running: true
    };

    let lastTimestamp = performance.now();

    function measureFrame(timestamp) {
      if (!window.__frameTiming.running) return;

      const delta = timestamp - lastTimestamp;
      window.__frameTiming.frameCount++;
      window.__frameTiming.frames.push(delta);

      // Keep only last 300 frames to limit memory
      if (window.__frameTiming.frames.length > 300) {
        window.__frameTiming.frames.shift();
      }

      // Frame longer than 33.33ms means we dropped below 30fps
      if (delta > 33.33) {
        window.__frameTiming.droppedFrames++;
      }
      if (delta > window.__frameTiming.maxFrameTime) {
        window.__frameTiming.maxFrameTime = delta;
      }

      lastTimestamp = timestamp;
      requestAnimationFrame(measureFrame);
    }

    requestAnimationFrame(measureFrame);
    return 'Frame timing monitor installed';
  }`
})
```

### Step 5 -- Install Long Animation Frame Observer

Use the `long-animation-frame` PerformanceObserver to detect jank.

```javascript
browser_evaluate({
  function: `() => {
    window.__longFrames = [];

    try {
      const observer = new PerformanceObserver((list) => {
        for (const entry of list.getEntries()) {
          window.__longFrames.push({
            startTime: entry.startTime,
            duration: entry.duration,
            blockingDuration: entry.blockingDuration,
            renderStart: entry.renderStart,
            styleAndLayoutStart: entry.styleAndLayoutStart,
            scripts: (entry.scripts || []).map(s => ({
              name: s.name,
              entryType: s.entryType,
              startTime: s.startTime,
              duration: s.duration,
              sourceURL: s.sourceURL,
              sourceFunctionName: s.sourceFunctionName,
              sourceCharPosition: s.sourceCharPosition
            }))
          });
        }
      });
      observer.observe({ type: 'long-animation-frame', buffered: true });
      return 'Long animation frame observer installed';
    } catch (e) {
      return 'long-animation-frame not supported: ' + e.message;
    }
  }`
})
```

### Step 6 -- Trigger Animations and Wait

Scroll the page and interact with elements to trigger animations. Wait for
a collection period.

```javascript
browser_evaluate({
  function: `() => {
    // Scroll to trigger scroll-based animations
    window.scrollBy(0, window.innerHeight);
    return 'Scrolled one viewport';
  }`
})
```

```
browser_wait_for({ time: 3 })
```

```javascript
browser_evaluate({
  function: `() => {
    window.scrollBy(0, window.innerHeight);
    return 'Scrolled another viewport';
  }`
})
```

```
browser_wait_for({ time: 3 })
```

Hover over interactive elements to trigger hover animations. Use
`browser_snapshot` to find elements, then `browser_click` or `browser_hover`.

```
browser_snapshot()
```

Use refs from the snapshot to hover over buttons, cards, or navigation items
that may have hover animations:

```
browser_hover({ ref: "<ref_from_snapshot>", element: "Interactive element" })
```

```
browser_wait_for({ time: 5 })
```

### Step 7 -- Detect Expensive Property Animations

Identify which CSS properties are being animated and classify them as
compositor-only (cheap) or layout/paint-triggering (expensive).

```javascript
browser_evaluate({
  function: `() => {
    const compositorOnly = new Set([
      'transform', 'opacity', 'filter', 'backdrop-filter',
      'offset-distance', 'offset-path', 'offset-rotate'
    ]);

    const paintOnly = new Set([
      'color', 'background-color', 'background-image', 'border-color',
      'outline-color', 'text-decoration-color', 'box-shadow', 'visibility'
    ]);

    // Layout-triggering = everything else that's animated

    const allAnimations = document.getAnimations();
    const analysis = [];

    for (const anim of allAnimations) {
      const effect = anim.effect;
      if (!effect || !effect.getKeyframes) continue;

      const target = effect.target;
      const keyframes = effect.getKeyframes();
      const animatedProps = new Set();

      for (const kf of keyframes) {
        for (const prop of Object.keys(kf)) {
          if (['offset', 'composite', 'easing', 'computedOffset'].includes(prop)) continue;
          animatedProps.add(prop);
        }
      }