overlay-animation-debugging

name	overlay-animation-debugging
description	Diagnose Autodarts overlay, board, and animation bugs that may stem from DOM churn, node replacement, observer rerenders, or weak CSS motion. Use when a blink, pulse, glow, or board overlay looks stuck, barely visible, twitchy, or inconsistent between targets, themes, or cards, especially when MCP browser evidence is needed.

Goal

Find whether the real fault is:

• semantic target logic
• render lifecycle or observer churn
• node identity loss
• animation design that is technically running but visually too weak

Workflow

1. Freeze the repro first

• Record the exact theme, route, target, and visible symptom.
• Find one good reference effect and one failing effect on the same page if possible.
• Prefer concrete comparisons such as S19 blinks cleanly, T20 only twitches.

2. Separate logic from rendering

• Confirm the intended target or state is actually selected in source and in the live DOM.
• If the wrong target is chosen, fix logic first.
• If the right target is chosen but the effect looks wrong, inspect rendering and animation next.

3. Measure node stability in MCP

• Check whether the same DOM or SVG node survives across passive rerenders.
• Sample the target node over multiple frames and record:
  • node identity
  • opacity
  • transform
  • filter
  • class list
• Add a mutation observer on the overlay host when churn is suspected.

Strong reset signal:

• unchanged semantic state
• repeated add/remove activity
• sampled node identity changes
• sampled styles stay near the animation start state

4. Compare against the reference path

• Inspect the stable reference effect with the same measurements.
• Note whether the difference is:
  • different renderer path
  • different class or keyframes
  • stable node versus recreated node
  • stronger motion values versus barely visible values

5. Fix the earliest correct layer

• Fix semantic route or state derivation if the wrong target is chosen.
• Fix render reconciliation if identical nodes are recreated.
• Fix keyframes only after confirming node stability.
• Do not switch animation libraries just because CSS looks suspect; recreated nodes will also restart JS-driven animations.

Regression guidance

Prefer narrow runtime tests that lock in the behavior contract:

• unchanged semantic state keeps the same overlay or host children
• structural self-heal rebuilds only when the subtree is actually damaged
• passive resync does not restart a running effect
• route fallback keeps a visible target when no finish remains

Output requirements

A valid result from this skill must:

• name the real failing layer
• include MCP evidence, not only source guesses
• distinguish stable reference behavior from failing behavior
• add or update at least one regression test when code changes follow