ai-debug-local-mcp/dist/handlers/hydration-handler.js

🎯 ENHANCED AI GUIDANCE v4.1.2: Dramatically improved tool descriptions help AI users choose the right tools instead of 'close enough' options. Ultra-fast keyboard automation (10x speed), universal recording, multi-ecosystem debugging support, and compreh

/**
 * Handler for SSR/CSR hydration mismatch detection
 * Helps identify and debug hydration errors in React, Next.js, Remix, and other SSR frameworks
 */
export class HydrationHandler {
    localEngine;
    tools = [
        {
            name: 'debug_hydration',
            description: 'Detect SSR/CSR hydration mismatches that cause React, Next.js, Remix, and other framework errors. Shows server vs client HTML differences.',
            inputSchema: {
                type: 'object',
                properties: {
                    sessionId: {
                        type: 'string',
                        description: 'Debug session ID'
                    }
                },
                required: ['sessionId']
            }
        }
    ];
    constructor(localEngine) {
        this.localEngine = localEngine;
    }
    async handle(toolName, args, sessions) {
        if (toolName !== 'debug_hydration') {
            throw new Error(`Unknown tool: ${toolName}`);
        }
        const { sessionId } = args;
        const session = sessions.get(sessionId);
        if (!session) {
            throw new Error(`Debug session ${sessionId} not found`);
        }
        try {
            const issues = await this.localEngine.getHydrationIssues();
            if (!issues || issues.length === 0) {
                return {
                    content: [{
                            type: 'text',
                            text: `## Hydration Analysis Results

✅ **No Hydration Issues Detected**

Your application hydrated successfully without any mismatches between server and client rendering.

### Tips for preventing hydration issues:

1. **Avoid using browser-only APIs during SSR**
   - Don't use \`window\`, \`document\`, or \`localStorage\` in initial render
   - Use \`useEffect\` or check \`typeof window !== 'undefined'\`

2. **Ensure consistent date/time rendering**
   - Use stable timestamps or timezone-aware formatting
   - Consider using libraries like date-fns with consistent locales

3. **Handle random values carefully**
   - Don't use \`Math.random()\` in render
   - Generate IDs on the server and pass them as props
   - Use stable unique IDs (e.g., database IDs)

4. **Check conditional rendering**
   - Ensure server and client have same initial state
   - Avoid user-agent based rendering differences
   - Handle authentication state consistently

5. **Debug hydration warnings**
   - Enable React's development mode
   - Check browser console for specific mismatch details
   - Use React DevTools to inspect component tree`
                        }]
                };
            }
            // Format hydration issues report
            let report = `## Hydration Analysis Results

⚠️ **Hydration Mismatches Detected**

Found **${issues.length}** hydration error${issues.length > 1 ? 's' : ''} where server-rendered HTML doesn't match client-rendered HTML.

### Detailed Issues:\n\n`;
            issues.forEach((issue, index) => {
                report += `#### ${index + 1}. Element: \`${issue.element}\`\n\n`;
                report += `- **Server HTML:** \`${issue.serverHTML}\`\n`;
                report += `- **Client HTML:** \`${issue.clientHTML}\`\n`;
                if (issue.stackTrace) {
                    report += `- **Stack Trace:**\n\`\`\`\n${issue.stackTrace}\n\`\`\`\n`;
                }
                report += '\n';
            });
            // Add common causes based on detected patterns
            report += `### Common Causes:\n\n`;
            const hasTimeIssue = issues.some((i) => i.serverHTML.match(/\d{1,2}:\d{2}/) ||
                i.clientHTML.match(/\d{1,2}:\d{2}/));
            const hasIdIssue = issues.some((i) => i.serverHTML.match(/id-\d+/) ||
                i.clientHTML.match(/id-\d+/));
            if (hasTimeIssue) {
                report += `- **Date/Time rendering**: Detected time-related mismatches. Use consistent timezone handling.\n`;
            }
            if (hasIdIssue) {
                report += `- **Random IDs**: Detected ID mismatches. Use stable ID generation.\n`;
            }
            report += `- **Browser-only APIs**: Check for \`window\` or \`document\` usage during SSR\n`;
            report += `- **Conditional rendering**: Ensure same conditions on server and client\n`;
            report += `- **Third-party scripts**: External scripts may modify DOM before hydration\n`;
            // Add framework-specific documentation
            report += `\n### Framework-Specific Docs:\n\n`;
            report += `- **React**: https://react.dev/link/hydration-mismatch\n`;
            report += `- **Next.js**: https://nextjs.org/docs/messages/react-hydration-error\n`;
            report += `- **Remix**: https://remix.run/docs/en/main/guides/gotchas#hydration\n`;
            report += `- **Gatsby**: https://www.gatsbyjs.com/docs/debugging-html-builds/\n`;
            report += `- **Vite SSR**: https://vitejs.dev/guide/ssr.html#hydration-mismatch\n`;
            report += `\n### Quick Fixes:\n\n`;
            report += `1. **Wrap dynamic content**: Use \`suppressHydrationWarning\` for truly dynamic content\n`;
            report += `2. **Client-only components**: Use dynamic imports with \`ssr: false\` (Next.js)\n`;
            report += `3. **UseEffect for browser APIs**: Move browser-specific code to \`useEffect\`\n`;
            report += `4. **Stable keys**: Use consistent \`key\` props for lists\n`;
            return {
                content: [{
                        type: 'text',
                        text: report
                    }]
            };
        }
        catch (error) {
            throw new Error(`Failed to analyze hydration: ${error.message}`);
        }
    }
}
//# sourceMappingURL=hydration-handler.js.map