debug_animation_issue

Instructions

Implementation Reference

• index.ts:1415-1477 (registration)

  Tool registration and schema definition for debug_animation_issue. Defines the tool name, description, and input schema requiring 'issue', with optional 'code' and 'expected_behavior' parameters.

      name: 'debug_animation_issue',
      description: 'Expert debugging for GSAP animation problems with solutions',
      inputSchema: {
        type: 'object',
        properties: {
          issue: {
            type: 'string',
            description: 'Description of the animation problem or unexpected behavior'
          },
          code: {
            type: 'string',
            description: 'Problematic animation code (optional but helpful)'
          },
          expected_behavior: {
            type: 'string',
            description: 'What should happen vs what is happening'
          }
        },
        required: ['issue']
      }
    },
    {
      name: 'optimize_for_performance',
      description: 'Transform any animation into 60fps smoothness with expert optimizations',
      inputSchema: {
        type: 'object',
        properties: {
          animation_code: {
            type: 'string',
            description: 'Existing GSAP animation code to optimize'
          },
          target: {
            type: 'string',
            description: 'Optimization target',
            enum: ['60fps-desktop', 'mobile-smooth', 'battery-efficient', 'memory-optimized'],
            default: '60fps-desktop'
          }
        },
        required: ['animation_code']
      }
    },
    {
      name: 'create_production_pattern',
      description: 'Generate battle-tested, production-ready animation patterns',
      inputSchema: {
        type: 'object',
        properties: {
          pattern_type: {
            type: 'string',
            description: 'Type of production pattern needed',
            enum: ['hero-section', 'scroll-system', 'text-effects', 'interactive-ui', 'loading-sequence', 'page-transitions', 'micro-interactions', 'data-visualization']
          },
          industry: {
            type: 'string',
            description: 'Industry or use case',
            enum: ['portfolio', 'ecommerce', 'saas', 'agency', 'blog', 'app', 'game'],
            default: 'portfolio'
          }
        },
        required: ['pattern_type']
      }
    }
  ]

• index.ts:1852-2026 (handler)

  Handler implementation for debug_animation_issue. Performs keyword-based issue classification (performance, scroll, mobile, timeline, plugin issues), provides matched solutions with confidence scores, analyzes provided code for common mistakes, and returns a comprehensive debugging guide.

  case 'debug_animation_issue': {
    const issue = args?.issue as string;
    const code = args?.code as string;
    const expected_behavior = args?.expected_behavior as string;
    
    if (!issue) {
      throw new Error('Issue description is required');
    }
  
    let result = `# 🔧 GSAP Animation Debugger\n\n`;
    result += `**Issue**: ${issue}\n\n`;
    
    if (expected_behavior) {
      result += `**Expected**: ${expected_behavior}\n\n`;
    }
  
    // Advanced issue detection patterns
    const debugPatterns = {
      performance: {
        keywords: ['lag', 'stutter', 'slow', 'janky', 'choppy', '60fps', 'performance'],
        solutions: [
          'Use transform properties (x, y, scale, rotation) instead of CSS positioning',
          'Add force3D: true to enable GPU acceleration',
          'Set will-change: transform on animated elements',
          'Use ScrollTrigger.batch() for multiple elements',
          'Clear properties after animation with clearProps: "all"',
          'Avoid animating layout properties (width, height, top, left)'
        ]
      },
      scroll_issues: {
        keywords: ['scroll', 'scrolltrigger', 'not triggering', 'refresh', 'positions'],
        solutions: [
          'Call ScrollTrigger.refresh() after DOM changes',
          'Use invalidateOnRefresh: true for dynamic content',
          'Check if elements exist before creating triggers',
          'Add markers: true for debugging trigger positions',
          'Ensure trigger element has proper positioning context',
          'Use ScrollTrigger.update() force update positions'
        ]
      },
      mobile_issues: {
        keywords: ['mobile', 'ios', 'android', 'touch', 'safari', 'viewport'],
        solutions: [
          'Add touch-action: none for draggable elements',
          'Use -webkit-transform for iOS compatibility',
          'Test with real devices, not just browser dev tools',
          'Reduce animation complexity on mobile',
          'Use matchMedia for responsive animations',
          'Handle viewport changes with resize listeners'
        ]
      },
      timeline_issues: {
        keywords: ['timeline', 'sequence', 'order', 'timing', 'delay', 'overlap'],
        solutions: [
          'Use timeline labels for complex sequences',
          'Check timeline positioning with relative values',
          'Use timeline.progress() to debug current position',
          'Add onUpdate callbacks to track progress',
          'Verify timeline.duration() matches expectations',
          'Use timeline.getChildren() to inspect child tweens'
        ]
      },
      plugin_issues: {
        keywords: ['plugin', 'splittext', 'scrolltrigger', 'morphsvg', 'drawsvg', 'not working'],
        solutions: [
          'Ensure plugins are registered with gsap.registerPlugin()',
          'Check plugin import paths are correct',
          'Verify you have the correct GSAP version',
          'Test plugin functionality in isolation',
          'Check browser console for plugin errors',
          'Ensure elements exist before applying plugins'
        ]
      }
    };
  
    let detectedIssues = [];
    const lowerIssue = issue.toLowerCase();
    
    for (const [pattern, data] of Object.entries(debugPatterns)) {
      const matches = data.keywords.filter(keyword => lowerIssue.includes(keyword));
      if (matches.length > 0) {
        detectedIssues.push({
          category: pattern,
          confidence: matches.length / data.keywords.length,
          solutions: data.solutions
        });
      }
    }
  
    if (detectedIssues.length > 0) {
      result += `## 🎯 Detected Issues\n\n`;
      detectedIssues.sort((a, b) => b.confidence - a.confidence);
      
      detectedIssues.forEach((detected, index) => {
        result += `### ${index + 1}. ${detected.category.replace('_', ' ').toUpperCase()} Issue\n`;
        result += `**Confidence**: ${(detected.confidence * 100).toFixed(1)}%\n\n`;
        result += `**Solutions**:\n`;
        detected.solutions.forEach(solution => {
          result += `- ${solution}\n`;
        });
        result += '\n';
      });
    }
  
    // Code analysis if provided
    if (code) {
      result += `## 📝 Code Analysis\n\n`;
      result += `\`\`\`javascript\n${code}\n\`\`\`\n\n`;
      
      const codeIssues = [];
      
      // Check for common issues
      if (!code.includes('gsap.registerPlugin') && (code.includes('ScrollTrigger') || code.includes('SplitText'))) {
        codeIssues.push('⚠️ **Missing Plugin Registration**: Add `gsap.registerPlugin(ScrollTrigger, SplitText)` before using plugins');
      }
      
      if (code.includes('width:') || code.includes('height:') || code.includes('left:') || code.includes('top:')) {
        codeIssues.push('⚠️ **Performance Warning**: Consider using transform properties (x, y, scale) instead of layout properties for better performance');
      }
      
      if (code.includes('ScrollTrigger') && !code.includes('markers')) {
        codeIssues.push('💡 **Debug Tip**: Add `markers: true` to ScrollTrigger for visual debugging');
      }
      
      if (code.includes('.to(') && !code.includes('force3D')) {
        codeIssues.push('💡 **Performance Tip**: Add `force3D: true` for GPU acceleration on complex animations');
      }
  
      if (codeIssues.length > 0) {
        result += `**Potential Issues Found**:\n`;
        codeIssues.forEach(issue => {
          result += `${issue}\n\n`;
        });
      }
    }
  
    // Generic debugging checklist
    result += `## ✅ Complete Debugging Checklist\n\n`;
    result += `### 1. Basic Setup\n`;
    result += `- [ ] GSAP is properly imported\n`;
    result += `- [ ] Required plugins are registered\n`;
    result += `- [ ] Elements exist in DOM before animation\n`;
    result += `- [ ] No console errors\n\n`;
    
    result += `### 2. Performance\n`;
    result += `- [ ] Using transform properties when possible\n`;
    result += `- [ ] GPU acceleration enabled (force3D: true)\n`;
    result += `- [ ] will-change CSS property set\n`;
    result += `- [ ] Proper cleanup with clearProps\n\n`;
    
    result += `### 3. ScrollTrigger Specific\n`;
    result += `- [ ] Trigger elements have proper positioning\n`;
    result += `- [ ] Start/end values are correct\n`;
    result += `- [ ] ScrollTrigger.refresh() called after DOM changes\n`;
    result += `- [ ] Using markers: true for debugging\n\n`;
    
    result += `### 4. Mobile Compatibility\n`;
    result += `- [ ] Tested on real devices\n`;
    result += `- [ ] touch-action CSS property set\n`;
    result += `- [ ] Reduced animation complexity\n`;
    result += `- [ ] Proper viewport handling\n\n`;
  
    result += `## 🚀 Quick Fixes\n\n`;
    result += `\`\`\`javascript\n// Emergency reset - clears all animations\ngsap.globalTimeline.clear();\nScrollTrigger.getAll().forEach(t => t.kill());\ngsap.set("*", { clearProps: "all" });\n\n// Performance boost\ngsap.defaults({ force3D: true, lazy: false });\n\n// ScrollTrigger debug\nScrollTrigger.create({\n  trigger: ".your-element",\n  markers: true, // Shows trigger points\n  onToggle: self => console.log("Triggered:", self.isActive)\n});\n\`\`\`\n\n`;
    
    result += `Need more specific help? Provide:\n`;
    result += `1. **Browser/device** where issue occurs\n`;
    result += `2. **Complete code** including HTML structure\n`;
    result += `3. **Console errors** (if any)\n`;
    result += `4. **Expected vs actual behavior** in detail`;
  
    return {
      content: [{ type: 'text', text: result }]
    };
  }