PRÉCISION LOCALE POUR CHESS.COM — VERSION 0.3.0

Installation dans Chrome (ordinateur)

1. Extraire entièrement le fichier ZIP dans un dossier conservé sur l’ordinateur.
2. Ouvrir chrome://extensions et activer « Mode développeur ».
3. Cliquer sur « Charger l’extension non empaquetée » et sélectionner le dossier
   chess-precision contenant manifest.json.
4. Recharger les onglets Chess.com déjà ouverts. On peut épingler l’extension
   dans la barre d’outils à l’aide du menu en forme de pièce de puzzle.

Mise à jour depuis la V1 ou V2

Remplacer les fichiers dans le même dossier d’installation, puis cliquer sur
le bouton de rechargement de l’extension dans chrome://extensions. Recharger
aussi les onglets Chess.com. Conserver le même chemin garde le même cache.
Les anciens scores sont invalidés : les parties visibles sont recalculées
avec la V3. Les autres sont accessibles avec le bouton « Recalculer ».
Le mode Approfondi est sélectionné lors de cette mise à jour pour privilégier
la qualité. Il peut ensuite être changé dans la fenêtre de l’extension.

Utilisation

Aucun pseudo à renseigner, aucun compte supplémentaire : les joueurs sont
détectés depuis la page. Chaque utilisateur installe sa propre copie.

Garder un onglet Chess.com ouvert. Après une partie, l’extension recherche les
parties terminées publiées dans l’API de Chess.com. Si les deux précisions
officielles sont publiées, elle les affiche directement, sans lancer le moteur.
Sinon, elle analyse leur PGN avec Stockfish sur l’ordinateur. Elle ne télécharge
aucun moteur à l’exécution.

Dans l’historique, les lignes reconnues affichent « En attente », puis la
progression et les deux scores à la place du bouton d’analyse. L’ordre suit
les joueurs affichés. Les précisions officielles déjà visibles sont conservées.
La provenance est indiquée : « Chess.com · précision officielle » ou
« Stockfish · estimation locale ». Une estimation locale est remplacée lorsque
les précisions officielles deviennent disponibles. Un calcul devenu inutile
est arrêté ; sa réponse tardive ne peut pas écraser le résultat officiel.

La fenêtre de l’extension affiche les Blancs et les Noirs explicitement,
permet de télécharger le PGN, de choisir la qualité d’analyse et de suspendre
le calcul. Une analyse interrompue par le bouton de pause reprend depuis son
début à la réactivation. « Effacer les résultats » vide le cache ; les parties
visibles pourront être récupérées de nouveau lors d’une synchronisation.

Les résultats sont enregistrés dans ce profil Chrome et retrouvés lors des
visites suivantes. Le cache conserve au maximum environ 300 parties, avec
une limite de volume de 6 Mo. La file est limitée à 20 analyses simultanément
en attente ; un seul moteur calcule à la fois. L’historique est parcouru par
lots, jusqu’à 50 lignes reconnues par page.

Limites à connaître

- L’extension utilise uniquement l’API publique officielle. Son cache
  peut retarder l’arrivée du PGN, parfois fortement. Le calcul n’est donc pas
  garanti immédiatement à la fin de la partie. Une vérification est lancée
  environ chaque minute lorsque la page est visible ; elle respecte aussi le
  cache et les erreurs du serveur. Aucune connexion à un compte n’est requise.
- Les scores calculés sont des estimations locales sur 100, distinctes du
  score CAPS2 de Chess.com. Il ne s’agit pas d’un déblocage de Game Review.
- Le moteur intégré est Stockfish.js 19 complet, à un seul fil de calcul.
  Les budgets sont de 100 000, 500 000 ou 2 000 000 de nœuds par recherche,
  avec des plafonds de 3, 8 ou 20 secondes pour borner les ressources utilisées.
  Les coups critiques sont revérifiés avec respectivement 400 000, 2 millions
  ou 8 millions de nœuds, avec des plafonds de 6, 20 ou 45 secondes. Les quotas
  de vérification sont de 8, 20 ou 40 positions selon le mode. Le mode Approfondi
  est sélectionné par défaut. Une partie peut demander plusieurs minutes, ou
  davantage si elle est longue. Les plafonds et quotas atteints sont signalés.
- Les parties standard sont prises en charge. Chess960, variantes et parties
  contre les robots absentes de l’API ne le sont pas. Les parties en cours ne
  sont pas envoyées au moteur. Limites : PGN de 64 000 caractères et 600
  demi-coups ; au moins un coup par joueur.
- Les dates textuelles françaises et anglaises et les dates HTML normalisées
  sont reconnues. Une ancienne partie avec une date différente peut nécessiter
  une adaptation du détecteur. Les changements futurs de la page Chess.com
  peuvent également demander une mise à jour.
- Cette version a été testée dans un navigateur isolé avec le vrai moteur et
  des réponses API de test, dont un vrai PGN public. Son installation dans une
  session Chess.com connectée et la fin d’une partie en direct restent à valider.
- Elle est fournie en installation locale, sans publication sur le Chrome Web
  Store. Chrome mobile ne charge pas ces extensions.

Calcul du score local

Le moteur compare le meilleur coup trouvé au coup joué, depuis la même
position et avec le même budget. Si le coup joué est le meilleur, sa précision
vaut 100. Sinon, une recherche limitée à ce coup mesure sa valeur. L’historique
des coups est transmis au moteur, notamment pour reconnaître les répétitions.
Le cache du moteur est vidé entre les recherches pour égaliser leur budget.

Chaque évaluation est convertie en chance de gain estimée, avec une courbe
ajustée au classement du joueur :
  a = 0,00368208 × 1,18 × (classement / 1500)^0,15
  E(cp, classement) = 100 / (1 + exp(-a × cp))
Un classement absent ou invalide est remplacé par 1500 pour cette conversion.
Cela ne réduit jamais la force du moteur Stockfish.
Pour chaque coup, on mesure la baisse de E du point de vue de son joueur :
  perte = max(0, E(avant) - E(après))
  précision du coup = borne[0,100](103,1668 × exp(-0,04354 × perte) - 3,1668)
La V3 agrège les précisions de coups avec une moyenne généralisée régularisée :
  précision = moyenne[(précision_du_coup + 17)^(-1,02)]^(1 / -1,02) - 17
Le résultat est borné entre 0 et 100. Cette régularisation pénalise les mauvais
coups sans qu’un seul zéro annule toute la partie. Une série entièrement à
zéro reste à zéro, et une série parfaite reste à 100.

Les quatre paramètres ont été ajustés sur 23 parties publiques avec précisions
officielles, puis figés. Ils ont été contrôlés sur 32 autres parties (64 notes),
dont un deuxième lot indépendant de 16 parties. Sur cette validation en mode
Rapide avec vérification des coups critiques, l’écart moyen absolu est passé
de 7,6 points pour la V2 à 4,6 pour la V3. Voir QUALITE.txt et les instantanés
reproductibles dans sources/calibration-validation.json.

Cette calibration est une approximation mesurée ; ce n’est pas l’algorithme
CAPS2 de Chess.com. Elle ne reproduit pas non plus le score global Lichess.
Le jeu de données comporte 55 parties issues de 5 comptes publics et de leurs
adversaires, couvrant des classements de 1094 à 3496. Il ne représente pas tous
les joueurs, les cadences ou les positions, notamment aux très faibles niveaux.

La fenêtre « Comprendre les scores » indique aussi la perte moyenne en
centipions (100 cp = un pion d’évaluation, pas toujours de matériel) hors mats,
et des catégories basées sur la perte estimée de chance : imprécision à partir
de 5 points, erreur à partir de 10, gaffe à partir de 20. Ces catégories sont
exclusives et propres à cette méthode. Les mats utilisent +10 000 ou -10 000
pour le score de précision ; ils sont exclus de la perte moyenne en cp.

Une forte baisse d’évaluation, un changement de mat ou une recherche contrainte
qui contredit la meilleure recherche déclenche une vérification plus poussée.
Les mats, pat, matériel insuffisant et répétitions sont résolus avec les règles
d’échecs et l’historique, sans transformer un abandon en évaluation arbitraire.

Il n’existe pas de précision universelle entièrement objective. La recherche
reste finie, et la difficulté humaine des coups n’est pas mesurée. Une partie
simple ou déjà gagnée peut conserver une précision élevée. Le mode Approfondi
et les pertes en cp permettent de vérifier au-delà du seul pourcentage.

Données et permissions

Seuls les noms des joueurs et les identifiants des parties visibles servent à
interroger api.chess.com. Pas de mot de passe, pas de clé d’API, pas de serveur
d’analyse tiers, pas de télémétrie. PGN et résultats sont stockés localement.
L’extension peut lire et modifier les pages https://www.chess.com/ et
https://chess.com/ ; ses requêtes réseau ciblent uniquement api.chess.com.
Les autorisations storage et offscreen servent au cache et au moteur local.

Sources et licences

Le code et ses dépendances sont fournis dans cette archive. Voir LICENSE,
THIRD-PARTY.txt, licenses/ et sources/. Les moteurs intégrés et les sources
correspondantes sont inclus pour permettre leur redistribution et adaptation.
Les 55 instantanés de parties publiques, les notes de référence et les données
de validation sont inclus dans sources/calibration-validation.json.

Documentation de référence
https://www.chess.com/news/view/published-data-api
https://support.chess.com/en/articles/8708970-how-is-accuracy-in-analysis-determined
https://github.com/nmrugg/stockfish.js/tree/v19.0.1
https://lichess.org/page/accuracy
https://official-stockfish.github.io/docs/stockfish-wiki/Stockfish-FAQ.html

Vérification pour un développeur

Avec Node.js : npm test
Pour les tests navigateur : installer Playwright séparément, puis exécuter
node tests/browser.cjs. PLAYWRIGHT_MODULE peut indiquer un paquet Playwright
existant et CHROMIUM_PATH un binaire Chromium compatible avec les extensions.
Le test ouvre un profil isolé en mode invisible et ne touche pas au profil
Chrome habituel. Il crée ses captures et son profil de test dans le dossier
parent de l’extension.
