Wahajolla/annotate

Annoter

L'utilisateur clique sur un élément d'une page, écrit une note, et Claude reçoit la note avec un sélecteur, le texte avoisinant, la boîte englobante et l'URL, afin de pouvoir trouver l'élément dans le code et le corriger.

Construit sur Agentation : la barre d'outils agentation (React 18+, bureau uniquement) et le serveur de notes agentation-mcp (API HTTP sur SQLite, avec outils MCP optionnels).

Choisir d'abord le mode

Demandez à l'utilisateur si ce n'est pas évident :

• Local : seulement l'utilisateur et Claude, sur cette machine. Le serveur de notes tourne sur localhost:4747. Rien n'est déployé. C'est le mode par défaut.
• Partagé : des collègues commentent un site hébergé, et tout le monde voit les notes de chacun. Cela nécessite un serveur de notes sur un hôte HTTPS public. Voir references/shared.md. Cette page décrit l'architecture et les prérequis ; l'utilisateur choisit l'hébergement.

Où placer la barre d'outils

Choisissez en fonction de la page. Les mêmes options fonctionnent dans les deux modes ; seuls endpoint et session changent.

1. Dans l'application React de l'utilisateur. npm i -D agentation, puis affichez-la à côté de l'application, en la protégeant pour qu'elle n'atteigne jamais la production :

   {import.meta.env.DEV && <Agentation endpoint="http://localhost:4747" />}
   

   Ajoutez useHashLocation pour les routeurs à hash et appName pour étiqueter les commentaires.
2. Sur toute page HTML qu'ils contrôlent, React ou non. Ajoutez une seule balise script. Le chargeur monte la barre d'outils dans son propre conteneur et sa propre racine React, donc il ne touche pas à la page hôte :

   <script type="module" src="https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747"></script>
   

   Paramètres de requête : endpoint, session, app, hash=1. Alternativement, définissez window.ANNOTATOR_CONFIG = {endpoint, session, app, hash} avant que le script ne se charge.
3. Sur n'importe quel site, sans toucher à son code. Utilisez un bookmarklet. Donnez à l'utilisateur cette ligne à enregistrer en tant que favori ; un clic active ou désactive la barre d'outils :

   javascript:(()=>{const s=document.createElement('script');s.type='module';s.src='https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/annotator.js?endpoint=http://localhost:4747&t='+Date.now();document.head.appendChild(s)})()
   

   Limites à signaler à l'utilisateur :
   • Les sites avec une politique de sécurité du contenu (CSP) stricte (GitHub, de nombreuses banques et grandes applications) bloquent les scripts injectés, donc la barre d'outils n'apparaîtra pas.
   • Sur un site public https:// qui communique avec localhost, le navigateur peut demander l'accès au réseau local : autorisez-le.
   • Le serveur de notes doit autoriser l'origine de ce site (voir CORS ci-dessous).
   • Les notes sont liées à l'URL du site, et les brouillons locaux de la barre d'outils vivent dans le localStorage de ce site.
4. Extension Chrome. C'est la manière la plus robuste d'annoter n'importe quel site. Elle s'active en un clic ou avec Alt+Shift+A, fonctionne sur les sites avec CSP strict (GitHub, Notion, etc.), et ne nécessite aucune configuration CORS : les requêtes passent par l'extension. Installation : téléchargez annotator-extension.zip depuis https://github.com/Wahajolla/annotator-skill/releases/latest, puis allez dans chrome://extensions → Mode développeur → Charger l'extension non empaquetée. Le serveur de notes est défini dans les options de l'extension. Par défaut, il s'agit de http://localhost:4747 ; pour le mode partagé, utilisez l'URL hébergée ainsi que l'identifiant de session. La synchronisation en direct se fait par interrogation toutes les 5 secondes. Si le serveur de notes est inaccessible, l'extension affiche une carte « Le serveur de notes est hors ligne » avec la commande de démarrage, et #annotator-ext-root reçoit data-annotator-server="offline" (devient "online" une fois qu'il répond) : si vous pilotez le navigateur, vérifiez cela avant de dire à l'utilisateur que ses notes ont été sauvegardées. Dans les options, « Se connecter avec GitHub » signe chaque note avec le login de l'utilisateur, afin que les notes des collègues montrent qui les a laissées.

Sans endpoint, la barre d'outils fonctionne en mode copie uniquement. Les notes restent dans le navigateur, et l'utilisateur appuie sur Copier et colle le markdown dans le chat. Cela ne nécessite aucun serveur, donc utilisez-le lorsque l'utilisateur n'en a besoin qu'une seule fois.

Mode local

1. Lancez le serveur de notes. Choisissez l'une des options :

   • MCP (meilleur pour une utilisation répétée). Avec l'accord de l'utilisateur : claude mcp add agentation -- npx -y agentation-mcp server. Claude Code le démarre alors à chaque session, et les outils agentation_* apparaissent après un redémarrage : get_all_pending, resolve, reply, et watch_annotations pour des boucles mains libres.
   • HTTP simple (pas de redémarrage). Exécutez npx -y agentation-mcp server comme commande d'arrière-plan, et lisez les notes via HTTP (voir ci-dessous).

   Vérifiez avec curl http://localhost:4747/health, qui devrait retourner {"status":"ok"}.

2. CORS. Par défaut, seules les origines de développement sont autorisées (localhost, *.localhost, 127.0.0.1, IP privées, .local, .test, .internal). Pour un bookmarklet sur un site public, démarrez le serveur avec AGENTATION_CORS_ORIGINS=https://ce-site.com (origines exactes, séparées par des virgules). * fonctionne aussi, mais cela permet à n'importe quel onglet ouvert d'écrire des notes, donc préférez des origines exactes.

3. Placez la barre d'outils sur la page en utilisant l'une des options ci-dessus, avec endpoint=http://localhost:4747.

4. Vérifiez. Ajoutez une note de test via la barre d'outils, vérifiez que curl localhost:4747/pending l'affiche, puis supprimez-la.

Les notes persistent dans ~/.agentation/store.db.

Lecture et action sur les notes (les deux modes)

• MCP : agentation_get_all_pending, puis corrigez le code, puis agentation_resolve avec un court résumé.
• HTTP : GET /pending (toutes les notes ouvertes), GET /sessions, GET /sessions/:id. Après avoir corrigé une note, envoyez PATCH /annotations/:id avec {"status":"resolved"}.
• Qui a écrit : les notes provenant de l'extension Chrome avec connexion GitHub portent authorId: "github:<login>", et par défaut le commentaire commence par @<login>: . Une note sans authorId est anonyme (toute autre façon de charger la barre d'outils). Mentionnez l'auteur lorsque vous faites votre rapport.
• Les champs utiles sont comment, url, element, elementPath, fullPath, nearbyText, selectedText, boundingBox et reactComponents (uniquement pour les builds de développement).
• Laissez l'utilisateur décider avant de supprimer quoi que ce soit.

Afficher les notes pour les captures d'écran

Agentation n'affiche le texte d'une note que lorsque vous survolez son marqueur. Pour les afficher toutes en même temps, utilisez la couche de notes : un contour, un numéro et une carte en texte intégral pour chaque note. Lorsque le rendu est terminé, <html> reçoit data-annotator-notes="<nombre>".

• L'utilisateur, dans Chrome : Alt+Shift+N dans l'extension (ou clic droit sur l'icône → Afficher toutes les notes sur cette page).
• Vous, sur une page que vous pilotez (Playwright, Chrome DevTools MCP, etc.) : définissez vos propres notes et chargez la couche, puis attendez l'attribut et faites la capture :

  window.ANNOTATOR_NOTES = [
    { selector: "h1", comment: "Trop long. Faites « Tarification simple »", author: "claude" },
    { selector: "#cta", comment: "Utilisez le bleu de la marque" },
  ]
  const s = document.createElement("script"); s.type = "module"
  s.src = "https://cdn.jsdelivr.net/gh/Wahajolla/[email protected]/embed/notes.js?t=" + Date.now()
  document.head.appendChild(s)
  

  Chaque note prend selector (ou boundingBox: {x, y, width, height} en coordonnées de page), comment, et un author optionnel. Les notes dont le sélecteur ne correspond à rien sont ignorées avec un avertissement dans la console, donc vérifiez que le nombre correspond. Au lieu de ANNOTATOR_NOTES, passez ?endpoint=http://localhost:4747 pour afficher les notes du serveur pour cette page ; ajoutez &all=1 pour inclure les notes résolues. Le recharger avec un nouveau t masque la couche.
• Les sites avec CSP strict (GitHub et autres) bloquent ce script. Dans Playwright, créez le contexte avec bypassCSP: true ; sinon, utilisez l'extension.
• Pour rendre vos notes réelles (l'utilisateur les voit aussi dans sa barre d'outils, et peut les résoudre) : POST /sessions avec {"url": "<url de la page>"} puis POST /sessions/:id/annotations avec comment, element, elementPath (un sélecteur CSS), url, boundingBox et x/y (coordonnées de la page). Ensuite, affichez-les avec ?endpoint=…. Demandez d'abord à l'utilisateur : elles deviennent des notes partagées.

Pièges

• La barre d'outils est uniquement pour ordinateur de bureau.
• Le serveur de notes n'a pas d'authentification, seulement du CORS. Toute personne dont l'origine du navigateur est autorisée peut écrire et supprimer des notes.
• useHashLocation conserve les notes par #route. L'activer plus tard ne déplace pas les notes existantes.
• Agentation est sous licence PolyForm Shield, ce qui convient pour un usage interne de feedback.