npm package: @sutsikinws/visual-debugger
Description: A draggable visual debugger for Next.js applications with automatic network request capture
Author: sutsiki
Latest version: 1.2.0

# @sutsikinws/visual-debugger

Un debugger visuel draggable pour Next.js avec capture automatique des requêtes réseau.

![Version](https://img.shields.io/badge/version-1.2.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)

## ✨ Fonctionnalités

- 🪟 **Fenêtre draggable & resizable** - Déplacez et redimensionnez la fenêtre comme sur Windows
- 🎨 **Design minimaliste moderne** - Interface épurée avec contrôles style macOS
- 🔝 **Toujours au premier plan** - Z-index ultra-élevé pour ne jamais perdre le debugger
- 📊 **Niveaux de log multiples** - `log`, `info`, `warn`, `error`
- 🔍 **Recherche dans les logs** - Filtrez vos logs avec une barre de recherche
- 🎯 **Filtrage par niveau** - Affichez uniquement les logs qui vous intéressent
- 🌐 **Capture réseau automatique** - Intercepte automatiquement fetch et XMLHttpRequest
- ⏱️ **Timestamps lisibles** - Format intelligent selon la date (HH:mm:ss.SSS)
- 📦 **Objets structurés** - Affichez des objets JSON avec formatage
- 🐛 **Stack traces** - Les erreurs affichent leur stack trace complète
- 🌙 **Dark mode** - Support automatique du dark mode via prefers-color-scheme
- 🚀 **SSR safe** - Compatible avec Next.js Server Components
- 👁️ **Bouton intelligent** - Se cache automatiquement quand la fenêtre est ouverte

## 📦 Installation

```bash
npm install @sutsikinws/visual-debugger
```

## 🚀 Quick Start

### 1. Ajouter le Debugger à votre Layout

Dans votre `app/layout.tsx` :

```typescript
import { VisualDebugger } from '@sutsikinws/visual-debugger'
import './globals.css'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <VisualDebugger />
        {children}
      </body>
    </html>
  )
}
```

### 2. Utiliser l'API de Debug

Dans n'importe quel composant ou page :

```typescript
'use client'

import { debug } from '@sutsikinws/visual-debugger'

export default function MyComponent() {
  const handleClick = () => {
    // Log simple
    debug.log('Button clicked!')

    // Log avec données
    debug.info('User action', { action: 'click', button: 'submit' })

    // Warning
    debug.warn('Deprecated API usage', { api: 'oldFunction()' })

    // Error
    debug.error(new Error('Something went wrong!'), { context: 'MyComponent' })
  }

  return <button onClick={handleClick}>Click me</button>
}
```

## 📚 API Reference

### `debug.log(message, data?)`

Enregistre un message général.

```typescript
debug.log('Simple message')
debug.log('User data', { userId: 123, name: 'John' })
```

### `debug.info(message, data?)`

Enregistre un message d'information (badge bleu).

```typescript
debug.info('Component mounted', { componentName: 'Header' })
```

### `debug.warn(message, data?)`

Enregistre un avertissement (badge jaune).

```typescript
debug.warn('Deprecated API', { api: 'oldMethod()' })
```

### `debug.error(error, data?)`

Enregistre une erreur (badge rouge) avec stack trace.

```typescript
debug.error(new Error('Failed to fetch'))
debug.error('Error message', { context: 'API call' })
```

### `debug.clear()`

Efface tous les logs.

```typescript
debug.clear()
```

## 🌐 Capture Réseau

Le debugger capture **automatiquement** toutes les requêtes réseau :

```typescript
// Cette requête sera automatiquement loggée
const response = await fetch('https://api.example.com/data')

// Vous verrez dans le debugger :
// [FETCH] GET https://api.example.com/data
// - status: 200
// - duration: 245.32ms
// - response: { ... }
```

Supporte :
- ✅ `fetch()` API
- ✅ `XMLHttpRequest`
- ✅ Axios (utilise fetch/XHR sous le capot)

## 🎨 Interface Utilisateur

### Bouton Toggle

Un bouton bleu en haut à droite de l'écran affiche :
- Le nombre de logs (badge rouge)
- Cliquez pour ouvrir/fermer la fenêtre

### Fenêtre de Debug

La fenêtre contient :
- **Header** : Titre, bouton Clear, bouton Close
- **Filtres** : Boutons pour filtrer par niveau (LOG/INFO/WARN/ERROR)
- **Recherche** : Barre de recherche en temps réel
- **Liste de logs** : Défilement automatique vers le bas

### Expansion des Logs

Cliquez sur la flèche à droite d'un log pour :
- Voir les données structurées (JSON formaté)
- Voir la stack trace (pour les erreurs)

## ⚙️ Configuration Avancée

### Désactiver la Capture Réseau

Si vous ne voulez pas capturer les requêtes réseau, vous pouvez créer un wrapper :

```typescript
// components/ConditionalDebugger.tsx
'use client'

import { VisualDebugger } from '@sutsikinws/visual-debugger'

export function ConditionalDebugger() {
  // Désactivez en production si nécessaire
  if (process.env.NODE_ENV === 'production') {
    return null
  }

  return <VisualDebugger />
}
```

### Utiliser uniquement l'API de Log

Vous pouvez utiliser uniquement l'API sans afficher l'interface :

```typescript
import { debug } from '@sutsikinws/visual-debugger'

// N'importez PAS <VisualDebugger />
// Utilisez seulement debug.log(), debug.info(), etc.
```

Les logs seront stockés en mémoire mais pas affichés.

## 🔧 Dépannage

### Erreur "Module not found"

**Problème** : `Cannot find module '@sutsikinws/visual-debugger'`

**Solution** :
1. Vérifiez que le package est installé : `npm list @sutsikinws/visual-debugger`
2. Essayez de réinstaller : `npm install @sutsikinws/visual-debugger`
3. Redémarrez votre serveur de développement

### Les requêtes réseau ne sont pas capturées

**Problème** : Les fetch ne s'affichent pas dans le debugger.

**Solution** :
- Assurez-vous que `<VisualDebugger />` est bien monté avant les requêtes
- Vérifiez que vous n'avez pas d'autres interceptors qui entrent en conflit
- Les requêtes côté serveur (Server Components) ne sont PAS capturées (par design)

### Erreur d'hydration

**Problème** : Warning d'hydration dans la console.

**Solution** : Le composant utilise déjà `useState` avec `mounted` pour éviter ça. Si vous voyez toujours l'erreur, assurez-vous d'utiliser la dernière version du package.

## 📄 License

MIT © sutsiki

## 🤝 Contributing

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request.

## 🐛 Report Bugs

Si vous trouvez un bug, créez une issue sur GitHub avec :
- Description du problème
- Steps pour reproduire
- Version de Next.js
- Version du package

## 📝 Changelog

### 1.2.0 (2026-01-05)

- 🎨 **Removed Tailwind CSS dependency** - Switched to standalone CSS for better compatibility and easier setup
- ⚡ **No configuration required** - CSS is automatically included with the component
- 🔧 **Simplified installation** - No need to configure Tailwind anymore
- 📦 **Smaller bundle** - Removed clsx dependency
- 🎯 **Better styling reliability** - Styles work out of the box regardless of consuming app's Tailwind configuration

### 1.1.1 (2026-01-05)

- 🐛 **Fixed React Hooks error** - Moved `useCallback` before conditional return to comply with Rules of Hooks

### 1.1.0 (2026-01-05)

- 🎨 **Major UI redesign** - Modern minimalist style with cleaner aesthetics
- 🪟 **Resizable window** - Resize from any edge or corner, like Windows Explorer
- 🎯 **macOS-style controls** - Beautiful traffic light buttons (red/yellow/green)
- 🔝 **Higher z-index** - Window now stays above everything (z-99998)
- 👁️ **Smart toggle button** - Automatically hides when window is open
- ⏱️ **Better timestamps** - More human-readable time format
- 🐛 **Fixed drag & drop** - Removed bounds restriction for smoother dragging
- 🎨 **Updated colors** - Using slate palette for modern look

### 1.0.1 (2026-01-05)

- 🐛 Fix React 19 compatibility - Added `nodeRef` to Draggable component to avoid `findDOMNode` deprecation error

### 1.0.0 (2026-01-05)

- 🎉 Initial release
- ✨ Fenêtre draggable
- 📊 Multiple log levels
- 🔍 Search & filters
- 🌐 Network interception
- 🎨 Dark mode support
- 🚀 SSR safe