Annotations

Ce guide vous explique en détail comment fonctionne le système d'annotations d'EchoPastel et ses fonctionnalités avancées.

Vue d'ensemble

Le système d'annotations d'EchoPastel utilise une technologie avancée de fingerprint multi-stratégies pour garantir que vos annotations restent attachées aux bons éléments, même lorsque la page change.

Système de fingerprint multi-stratégies

Contrairement aux systèmes qui utilisent uniquement un sélecteur CSS (qui peut facilement se casser), EchoPastel utilise plusieurs stratégies d'identification :

1. Sélecteur CSS

Le sélecteur CSS traditionnel utilisant les classes et IDs de l'élément. C'est la méthode la plus rapide mais peut être fragile si les classes changent.

2. XPath

Un chemin XPath basé sur la structure DOM. Plus stable que le CSS, il fonctionne même si les classes changent.

3. Empreinte de contenu

Une signature basée sur :

• Le nom de la balise
• Les attributs de l'élément
• Le contenu textuel
• Le HTML interne

4. Informations de contexte

Informations sur les relations parent-enfant :

• Le sélecteur du parent
• L'index de l'élément parmi ses frères
• La détection de conteneurs dynamiques

Cascade de résolution

Lorsqu'EchoPastel doit retrouver un élément annoté, il essaie plusieurs stratégies dans l'ordre :

1. Sélecteur CSS - Méthode la plus rapide
2. XPath - Plus stable, fonctionne même si les classes changent
3. Parent + Index - Utilise la position relative dans le parent
4. Correspondance de contenu - Trouve l'élément par similarité de contenu

Cette cascade garantit une fiabilité maximale : si une méthode échoue, les autres peuvent toujours trouver l'élément.

Gestion du contenu dynamique

Détection automatique

EchoPastel détecte automatiquement les éléments dans des conteneurs dynamiques :

• Carrousels : Swiper, Slick, Splide, etc.
• Conteneurs scrollables : Zones avec overflow
• Sliders personnalisés : Implémentations custom

La détection se fait en vérifiant :

• Les noms de classes contenant des mots-clés de carrousel
• Les attributs data (ex: data-carousel, data-swiper)
• Les propriétés CSS overflow

Observateurs intelligents

Pour les éléments dans des conteneurs dynamiques, le système attache des observateurs spécialisés :

1. ResizeObserver - Détecte les changements de taille
2. MutationObserver - Surveille les modifications du DOM
3. Écouteurs de scroll - Suit le défilement dans les conteneurs
4. IntersectionObserver - Détecte les changements de visibilité

Ces observateurs repositionnent automatiquement les annotations quand :

• Les slides du carrousel changent
• Les éléments sont animés
• Le contenu est chargé en lazy loading
• La mise en page de la page change

États des annotations

Annotation active

L'élément a été trouvé et l'annotation est correctement positionnée. C'est l'état normal d'une annotation.

Annotation orpheline

L'élément annoté n'existe plus sur la page. Dans ce cas :

• L'annotation est marquée comme "orpheline"
• Elle est affichée avec une opacité réduite et en niveaux de gris
• La capture d'écran est toujours accessible
• Vous pouvez toujours voir et répondre à l'annotation

Important : Les annotations orphelines ne sont pas perdues ! Elles conservent leur capture d'écran et restent accessibles pour référence.

Annotation dynamique

L'annotation est dans un carrousel/slider et est activement suivie. Le système ajuste automatiquement sa position lors des changements.

Captures d'écran automatiques

Chaque annotation génère automatiquement une capture d'écran qui :

• Préserve le contexte visuel de votre feedback
• Montre l'élément annoté au moment de la création
• Reste accessible même si l'élément disparaît (annotation orpheline)
• Aide à comprendre le contexte même après des changements de page

Les captures d'écran sont générées automatiquement et ne nécessitent aucune action de votre part.

Position relative

Chaque annotation stocke sa position comme un pourcentage (0-1) relatif aux dimensions de l'élément :

• x : Position horizontale (0 = gauche, 1 = droite)
• y : Position verticale (0 = haut, 1 = bas)

Cela permet :

• Plusieurs annotations sur le même élément à différentes positions
• Repositionnement précis même si la taille de l'élément change
• Préservation de l'emplacement lors des changements de design responsive

Bonnes pratiques

Annoter des éléments stables

Privilégiez les éléments avec :

• Des IDs uniques
• Des classes sémantiques
• Une structure DOM stable

Éviter les éléments temporaires

Évitez d'annoter :

• Les éléments générés dynamiquement sans identifiants stables
• Les éléments dans des iframes non contrôlées
• Les éléments qui changent fréquemment de structure

Vérifier les annotations orphelines

Périodiquement, vérifiez vos annotations orphelines :

• Elles peuvent indiquer des changements importants dans votre site
• Utilisez-les pour documenter l'évolution de votre interface
• Réannotez si nécessaire après des refactorisations majeures

Optimisations de performance

EchoPastel utilise plusieurs optimisations pour garantir des performances optimales :

1. Repositionnement debounced - Évite les recalculs excessifs lors de changements DOM rapides
2. Observateurs ciblés - Observe uniquement les conteneurs qui ont des annotations
3. Écouteurs passifs - Les événements de scroll utilisent le mode passif pour de meilleures performances
4. Mises à jour throttlées - Les positions des annotations se mettent à jour au maximum toutes les 50-100ms

Compatibilité navigateur

Le système d'annotations fonctionne sur :

• ✅ Chrome/Edge : Support complet
• ✅ Firefox : Support complet
• ✅ Safari : Support complet
• ❌ IE11 : Non supporté (utilise des APIs modernes)

Prochaines étapes

• Découvrez la collaboration - Partagez et collaborez sur vos annotations
• Explorez le système de fingerprint - Comprenez en détail comment fonctionne l'identification
• Utilisez sur mobile - Testez vos interfaces sur tous les appareils