Fusion de la MR !46 : tutoriel, Jacoby

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/etape-1.md

@@ -20,7 +20,7 @@ Repris du cadrage (modules, écrans clés, IA générative en V1) et des ADR 001
 | 1a. Moteur pour l'analyse (fait) | Niveaux de jeu (plis et bruit de GNU Backgammon : débutant à expert), classement des coups d'un jet avec équités, analyse d'un coup joué et d'une décision de videau, chance d'un jet ; exposés par `engine.h`, `engine-cli` et le Worker, avec positions de référence comparées à gnubg de bureau | — |
 | 1b. Parties enregistrées (fait) | Stockage IndexedDB derrière l'interface de stockage existante : plusieurs parties, reprise automatique, branches (« Rejouer d'ici » crée une branche, l'originale reste intacte et rechargeable), export SGF avec variantes | — |
 | 1c. Match et réglages | Partie libre ou match en N points, règle Crawford, règle Jacoby, choix du niveau de l'ordinateur, conseil du maître activable ou non ; écran de nouvelle partie | 1a, 1b |
-| 1d. Conseil du maître | Après chaque coup du joueur, jamais avant (ADR 0011) : appréciation du moteur (bon coup, imprécision, erreur, gaffe) avec mot, icône et couleur, phrase du maître fondée sur les chiffres du moteur, coup recommandé montré sur demande ; aussi pour les décisions de videau ; calcul en arrière-plan sans retarder le jeu | 1a |
+| 1d. Conseil du maître | Après chaque coup du joueur, jamais avant (ADR 0011) : appréciation du moteur (bon coup, imprécision, erreur, grosse erreur) avec mot, icône et couleur, phrase du maître fondée sur les chiffres du moteur, coup recommandé montré sur demande ; aussi pour les décisions de videau ; calcul en arrière-plan sans retarder le jeu | 1a |
 | 1e. Fin de partie et analyse | Bilan (ADR 0011) : résultat, coups par appréciation, taux d'erreur comparé à la chance, « le coup à revoir » ; écran d'analyse : graphe d'équité (toucher un point ouvre la position), liste des erreurs filtrable, visualiseur pas à pas coup joué contre meilleur coup, « Rejouer d'ici » | 1a, 1b, 1d |
 | 1f. Prompts à copier | Gabarits versionnés et testés (`docs/prompts/` ou équivalent, source unique), bouton « Demander à une IA » sur le plateau, le conseil du maître, l'analyse et la fin de partie ; le moteur décide, l'IA explique | 1d, 1e |
 | 1g. Accueil, tutoriel et leçons | Accueil (reprendre, nouvelle partie, prochaine leçon, progression résumée), tutoriel des règles interactif et illustré (0e.5), cinq premières leçons numérotées (ADR 0011) avec positions et « à vous de jouer », progression locale ; contenus CC BY-SA 4.0 en brouillon, à relire par un joueur fort | 0e.5, 1a |

docs/feuille-de-route.md

@@ -24,7 +24,7 @@ Demandes de Pierre du 2026-11-03, traitées avant d'ouvrir l'étape 1.
 | Sous-étape | Contenu | État | Plan |
 | --- | --- | --- | --- |
 | 0e.4 | Une adresse par écran (aide, glossaire, menu, mes parties…) et par position, par de vrais liens (ADR 0013 amendé) | ⏳ | `plans/2026-11-03-position-dans-l-adresse.md` |
-| 0e.5 | Page d'accueil, installation en un toucher (« Ajouter à l'écran d'accueil », proposée par l'app), tutoriel des règles très didactique avec plateaux illustrés, aide réécrite sur un ton plus humain ; textes à valider par Pierre | ⏳ | `plans/2026-11-03-accueil-tutoriel-aide.md` |
+| 0e.5 | Page d'accueil, mise à jour de l'app en un toucher, installation en un toucher (« Ajouter à l'écran d'accueil », proposée par l'app), tutoriel des règles très didactique avec plateaux illustrés, aide réécrite sur un ton plus humain ; textes à valider par Pierre | ⏳ | `plans/2026-11-03-accueil-tutoriel-aide.md` |
 
 ## Étapes suivantes
 

docs/identite/charte/README.md

@@ -14,6 +14,7 @@ Décisions : ADR 0010. Fichiers du logo et des icônes : `../logo/`.
 | Fichier | Contenu |
 | --- | --- |
 | `guide-de-marque.md` | Règles d'usage : ton, couleurs, typographie, formes, mouvement, icônes, composants |
+| `ecrans-etape-1.md` | Écrans de l'étape 1, lot par lot : nouvelle partie et match (1c), conseil du maître (1d), bilan et analyse (1e), IA (1f), leçons (1g), progression (1h), gestes (1i) |
 | `accueil-tutoriel-aide.md` | Accueil, installation sans intrusion, tutoriel des règles (forme et première version du texte), aide en questions |
 | `recette-ux.md` | Critères de recette design de l'écran de jeu, à cocher sur les captures et sur le téléphone |
 | `interaction.md` | Comportement : réponse immédiate, annuler plutôt que confirmer, mouvement, vibrations, clavier, mises en page de l'écran de jeu (portrait, paysage, ordinateur), pictogrammes |

docs/identite/charte/accueil-tutoriel-aide.md

@@ -67,7 +67,8 @@ interrompre.
   deux ou trois phrases. Une étape sur deux finit par un écran **« à vous »**
   où le joueur fait le geste sur le vrai plateau, contrôlé par le moteur.
 - En haut : une barre de progression en huit segments (`accent` pour les
-  étapes faites) et « Passer » à droite. En bas : « Retour » et
+  étapes faites) et « Quitter » à droite (pas « Passer » : ce mot appartient au
+  videau, et le tutoriel enseigne les mots exacts du jeu). En bas : « Retour » et
   « Continuer ».
 - Les positions sont données par leurs identifiants gnubg (ADR 0013) ; le
   plateau est le composant de l'app, non jouable sauf sur les écrans
@@ -113,9 +114,10 @@ interrompre.
    flèche 6, un 1 un pion de la flèche 1. Touchez le pion, puis la sortie à
    droite. » *À vous* : sortir deux pions avec 6-3.
 7. **Gammon et backgammon.** « Une partie gagnée vaut 1 point. Si
-   l'adversaire n'a sorti aucun pion quand vous finissez, c'est un gammon :
-   2 points. S'il lui reste en plus un pion sur la barre ou dans votre camp,
-   c'est un backgammon : 3 points. »
+   l'adversaire n'a sorti aucun pion, c'est un gammon : 2 points ; s'il lui
+   reste en plus un pion sur la barre ou dans votre camp, c'est un
+   backgammon : 3 points. En partie libre, gammon et backgammon ne comptent
+   que si le videau a été doublé : c'est la règle de Jacoby. »
 8. **Le videau.** « Le cube aux faces 2, 4, 8, 16, 32 et 64 sert à miser.
    Avant de lancer vos dés, vous pouvez proposer de doubler la valeur de la
    partie. L'ordinateur prend, et la partie continue en valant le double, ou il

docs/identite/charte/ecrans-etape-1.md

@@ -0,0 +1,253 @@
+# Écrans de l'étape 1
+
+Règles de design des écrans de l'étape 1 (`docs/etape-1.md`), lot par lot.
+Maquettes : canevas https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe, rangées
+« Étape 1 ». Comportement général : `interaction.md` ; liens : ADR 0013.
+
+## 1c. Nouvelle partie et match
+
+### Écran « Nouvelle partie » (`#/nouvelle-partie`)
+
+Ouvert depuis le menu, l'accueil et la fin de partie. Une seule page, sans
+étapes, de haut en bas :
+
+1. **Type de partie** : un sélecteur à deux segments, « Partie libre » et
+   « Match » (fond `surface-sunken`, segment choisi en `surface` avec
+   `shadow-raised`).
+   - **Match** : « Le premier à [3] [5] [7] [11] points », quatre boutons
+     carrés de 44 px, le choisi en brique. Dessous, une phrase sur la règle de
+     Crawford, avec le lien vers sa fiche du glossaire.
+   - **Partie libre** : une phrase sur la règle de Jacoby, avec le lien vers
+     sa fiche. Pas d'interrupteur pour Crawford ni Jacoby : ce sont les règles
+     usuelles, et le joueur débutant n'a pas à les choisir.
+2. **Niveau de l'ordinateur** : six barres de hauteur croissante, à toucher
+   (Débutant, Amateur, Intermédiaire, Avancé, Expert, Champion) ; les barres
+   jusqu'au niveau choisi sont en brique, le niveau choisi porte l'anneau de
+   focus. Dessous, le nom en `heading` et une phrase qui le décrit en mots de
+   joueur, jamais en plis ni en bruit :
+   - Débutant : « Joue simplement et laisse passer des occasions. Idéal pour
+     vos premières parties. »
+   - Amateur : « Un joueur qui connaît les règles et commet encore des
+     erreurs. »
+   - Intermédiaire : « Un habitué de la table : solide, sans être
+     implacable. »
+   - Avancé : « Un bon joueur de club. Peu d'erreurs de pions, un videau
+     sérieux. »
+   - Expert : « Très peu d'erreurs. Chaque point se gagne. »
+   - Champion : « GNU Backgammon à son meilleur niveau sur ce téléphone. »
+3. **Pendant la partie** : interrupteur « Conseil du maître », sous-titre
+   « Une ligne après chacun de vos coups ».
+4. **Barre d'action collée en bas** : un seul bouton principal, qui dit ce
+   qu'il lance (« Commencer la partie » ou « Commencer le match en 5
+   points »), et la mention « Vos choix sont gardés pour la prochaine fois. ».
+
+Par défaut : partie libre, Intermédiaire, conseil activé. Fermer (croix en
+haut à gauche, ou retour du téléphone) ne change rien à la partie en cours.
+Commencer une nouvelle partie alors qu'une partie est en cours suit la règle
+« annuler plutôt que confirmer » (bandeau « Reprendre l'ancienne »).
+
+### Score de match sur l'écran de jeu
+
+- **Portrait** : une ligne `overline` centrée sous la barre haute, « Match en
+  5 points », complétée par « · partie Crawford » pendant la partie Crawford ;
+  dans chaque bandeau, une pastille carrée (contour `border-strong`, chiffre
+  gras) avec le score de ce joueur, juste avant son compte de points.
+- **Paysage** : dans la colonne de commandes, sous le menu, une case qui
+  empile le score de l'ordinateur, « sur 5 », puis le vôtre (même ordre que
+  les bandeaux : l'ordinateur en haut, vous en bas).
+- Le score se lit aussi au lecteur d'écran : « Match en 5 points :
+  l'ordinateur 4, vous 2 ».
+- Pendant la partie Crawford, le videau n'est pas affiché : il n'existe pas
+  pour cette partie.
+
+## 1d. Conseil du maître
+
+### La ligne du maître
+
+Maquette « Portrait révisé : conseil du maître après le coup ». Une ligne de
+44 px, réservée sous le bandeau du joueur (elle ne pousse rien) :
+
+- icône d'appréciation, puis le **mot en couleur** suivi d'un point
+  (« Bon coup. »), puis la **phrase du maître en italique**, sur une ligne,
+  tronquée par des points de suspension si elle est trop longue, et un
+  chevron ;
+- elle apparaît **après** la validation du coup du joueur (ou sa décision de
+  videau), dès que l'analyse est prête, en fondu de `duration-fast` ; elle
+  s'efface à l'action suivante du joueur (lancer les dés, toucher un pion) ;
+- **pendant que le joueur réfléchit, rien n'apparaît** ; si l'analyse arrive
+  trop tard (le joueur a déjà relancé), la ligne n'apparaît pas, et le coup
+  reste commenté dans le bilan ;
+- conseil désactivé : la ligne reste réservée et vide (la mise en page ne
+  bouge pas).
+
+### Les mots
+
+| Seuil gnubg (écart d'équité) | Mot | Couleur | Icône |
+| --- | --- | --- | --- |
+| meilleur coup, ou moins de 0,03 | Bon coup | `verdict-good` | coche |
+| 0,03 à 0,06 (doubtful) | Imprécision | `verdict-doubtful` | point d'interrogation |
+| 0,06 à 0,12 (bad) | Erreur | `verdict-bad` | croix |
+| plus de 0,12 (very bad) | Grosse erreur | `verdict-bad` | croix |
+
+Pour le videau : « Bon choix » et « Bonne décision » remplacent « Bon coup ».
+« Grosse erreur » est la recommandation de design ; `docs/etape-1.md` écrit
+« gaffe », et le choix final revient à Pierre (ton).
+
+### La feuille d'explication
+
+Maquette « Feuille d'explication du maître ». Toucher la ligne ouvre une
+feuille qui monte du bas (`duration-moderate`), au-dessus du plateau voilé :
+
+1. le mot d'appréciation et le contexte (« Erreur · votre 3-1 d'ouverture ») ;
+2. le titre : le coup du maître, à la première personne (« J'aurais joué
+   8/5 6/5 ») ; pour un bon coup : « C'est aussi le coup que j'aurais joué » ;
+3. la phrase du maître, en italique ;
+4. un sélecteur à deux segments, « Votre coup » et « Le coup du maître », au-
+   dessus d'un plateau qui montre la position d'avant le coup ; le coup choisi
+   se joue pion par pion (`duration-fast`), avec un tracé du départ à
+   l'arrivée : `text` pour votre coup, `verdict-good` pour celui du maître ;
+5. « Voir les chiffres du moteur » (repliée par défaut) : le classement des
+   coups avec leur écart d'équité et le niveau d'évaluation ; votre coup est en
+   gras ;
+6. « Demander à une IA » (1f) et « Fermer ».
+
+Le lien vers la fiche d'un concept du glossaire n'apparaît que si le moteur
+permet de le déterminer, sinon rien.
+
+### Les phrases du maître
+
+- **Le maître parle à la première personne et vouvoie** : « J'aurais joué… »,
+  jamais « Vous auriez dû… », jamais « Il fallait… ».
+- **Il ne cite que des faits** : le coup recommandé, le rang de votre coup,
+  les pions frappés, les points faits ou laissés (lisibles dans le coup
+  lui-même), l'écart d'équité sur demande. Aucune explication stratégique
+  inventée (« la case la plus précieuse », « trop risqué ») : celles-là
+  viendront des leçons, relues par un joueur fort.
+- **Trois parties au plus** : ce que vous avez fait, ce que le maître préfère,
+  un fait qui les distingue. Moins de 140 caractères pour la ligne ; la
+  feuille peut aller jusqu'à deux phrases.
+- **Ton** : encourageant et sobre. Pas de point d'exclamation, pas d'émoji, pas
+  de superlatif. Les bons coups ont plusieurs formules qui tournent
+  (« C'est le coup du maître. », « Exactement ce que j'aurais joué. »,
+  « Bien vu. »), pour ne pas lasser.
+- **Exemples** (gabarits à remplir avec les données du moteur) :
+  - Bon coup : « Bien vu. 8/5 6/5 fait votre point 5. »
+  - Imprécision : « J'aurais joué {meilleur}. Votre coup était le
+    {rang}e choix, tout près. »
+  - Erreur : « J'aurais joué {meilleur}. Votre {joué} était le {rang}e
+    choix. »
+  - Videau, prise juste : « Bonne décision : prendre était le bon choix. »
+  - Videau, double manqué : « Ici, j'aurais doublé. »
+
+## 1e. Bilan et analyse
+
+### Bilan (`#/parties/<id>/bilan`)
+
+Maquette « Bilan de fin de partie ». Il remplace le panneau de fin de partie
+quand l'analyse est prête ; avant, le panneau actuel s'affiche et le bilan le
+remplace en place, sans saut.
+
+1. `overline` « Fin de partie », titre `display` (« Vous gagnez », « L'ordinateur
+   gagne un gammon »), puis une phrase : le résultat en points et une
+   lecture simple du jeu et des dés (« Votre jeu a fait la différence, avec
+   des dés un peu contre vous. »), construite à partir du taux d'erreur et de
+   la chance donnés par le moteur, jamais inventée.
+2. Trois cases côte à côte : le nombre de bons coups, d'imprécisions et
+   d'erreurs (grosses erreurs comprises), chiffre en 28 px, mot et icône en
+   couleur d'appréciation.
+3. Deux jauges sur une ligne chacune :
+   - « Votre jeu » : le taux d'erreur traduit en niveau (correspondance avec
+     les classements de gnubg documentée, mêmes noms que les niveaux de
+     l'ordinateur), jauge en `verdict-good` ;
+   - « Les dés » : la chance, jauge centrée (à droite si elle vous a aidé, à
+     gauche sinon), en `border-strong`, avec trois mots possibles : « pour
+     vous », « équilibrés », « contre vous » (« un peu » ou « nettement »
+     selon l'écart).
+   Lien « Comment lire ces mesures » vers les fiches du glossaire.
+4. « Le coup à revoir » : la plus grosse erreur, mini-plateau, mot
+   d'appréciation, coup joué et coup du maître ; « Revoir ce coup » (ouvre
+   l'analyse sur ce coup) et « Demander à une IA ». Sans erreur ni
+   imprécision : la carte dit « Aucun coup à revoir : vous avez joué comme le
+   maître. »
+5. Barre d'actions : « Voir l'analyse » et « Nouvelle partie » (principale).
+
+### Analyse (`#/parties/<id>/analyse/<coup>`)
+
+Maquette interactive « Analyse ». Une page qui défile, de haut en bas :
+
+1. **Courbe de vos chances de gagner**, coup après coup, en pourcentage (pas
+   en équité : un débutant lit « 41 % », pas « −0,18 »). Tracé `text` de 2 px,
+   aire `accent-soft`, ligne pointillée à 50 %. Les coups commentés sont des
+   points de couleur d'appréciation, les autres de petits points `text`.
+   **On parcourt la courbe du doigt** : chaque coup possède une bande verticale
+   sur toute la hauteur du graphique, qui sert de cible tactile ; le coup
+   choisi porte un trait vertical brique et un point cerclé.
+2. **Visualiseur** : « ‹ Coup 7 sur 24 · 6-1 › », le plateau de la position
+   d'avant le coup, la phrase du maître, le sélecteur « Votre coup » / « Le
+   coup du maître » de la feuille 1d, puis « Rejouer d'ici » (crée une
+   branche, ADR 0011 et 1b) et « Demander à une IA ».
+3. **Les coups à revoir** : filtres en pastilles de 44 px (« Tout »,
+   « Erreurs », « Imprécisions », avec leurs nombres), puis une ligne par
+   coup : numéro, dés, coup joué, mot d'appréciation. Toucher une ligne place
+   le visualiseur et la courbe sur ce coup.
+
+Sur ordinateur, `←` et `→` passent d'un coup à l'autre.
+
+## 1f. Demander à une IA
+
+Le bouton est secondaire partout, jamais l'action principale, avec l'icône
+de copie : dans la feuille du maître (1d), dans la carte « Le coup à
+revoir » du bilan, dans le visualiseur de l'analyse, et dans une fiche du
+glossaire. Après la copie, le bandeau « Prompt copié » (`verdict-good`, 2 s),
+puis le texte du prompt reste lisible dans une zone `surface-sunken`
+repliable, pour qui veut le relire avant de le coller (composant `AskAI`).
+
+## 1g. Leçons (`#/lecons`, `#/lecons/<n>/<écran>`)
+
+Maquette « Leçons ». En tête, un rappel discret « Les règles du jeu ·
+revoir » (le tutoriel de 0e.5). Puis les cinq leçons numérotées, dans
+l'ordre, chacune avec une pastille ronde à son numéro :
+
+- terminée : pastille `verdict-good`, « Terminée » ;
+- en cours : carte bordée de brique, pastille brique, « 2 exercices sur 4 »,
+  barre de progression, bouton « Continuer » (seule action principale de
+  l'écran) ;
+- à commencer : pastille au contour `border-strong`.
+
+Toutes les leçons restent ouvertes : l'ordre est conseillé, jamais imposé.
+Les écrans d'une leçon suivent la forme du tutoriel (barre de progression,
+« Passer », « Retour », « Continuer », écrans « à vous » contrôlés par le
+moteur).
+
+## 1h. Progression (`#/progression`)
+
+Maquette « Progression ».
+
+- Une phrase de synthèse, factuelle (« Sur vos 8 dernières parties, vous
+  faites moins d'erreurs : votre taux d'erreur est passé de 14 à 7. »). Si la
+  tendance monte, la phrase reste encourageante et sans reproche (« Votre
+  taux d'erreur remonte un peu ces derniers jours. Les leçons sont là
+  pour reprendre un point. »).
+- La courbe du taux d'erreur par partie terminée, avec le rappel « plus bas,
+  c'est mieux » dans son titre, le dernier point en `verdict-good`, et un lien
+  vers la fiche « taux d'erreur ».
+- La liste des parties (résultat, date, niveau de l'ordinateur, taux d'erreur
+  en chiffre gras aligné à droite), chacune ouvrant son bilan.
+- Moins de trois parties analysées : pas de courbe, une phrase « Votre
+  courbe apparaîtra après trois parties. ».
+
+## 1i. Gestes sur le plateau
+
+- **Glisser-déposer** : le pion suit le doigt, agrandi à 115 % et décalé de
+  12 px vers le haut pour rester visible sous le doigt ; à son départ, un pion
+  fantôme en pointillés ; les cases d'arrivée permises gardent leur voile et
+  leur anneau (révision UX). Lâché sur une case permise : il s'y pose
+  (`duration-fast`, vibration « pion posé ») ; lâché ailleurs : il revient à
+  sa place en `duration-fast`, sans vibration ni message.
+- **Double toucher** : joue le coup évident quand il existe (un seul coup légal
+  complet commence par ce pion, ou le moteur n'en propose qu'un) ; sinon, il
+  vaut un simple toucher, sans message d'erreur.
+- **Toucher simple** : inchangé (pion puis case, ou avance directe s'il n'a
+  qu'une case d'arrivée).
+- Les trois gestes coexistent ; aucun n'est expliqué par une fenêtre : le
+  tutoriel et l'aide en parlent.

docs/plans/2026-11-03-accueil-tutoriel-aide.md

@@ -41,9 +41,24 @@ Traiter les points 2 et 3 du message de Pierre du 2026-11-03 et sa demande d'ins
    - « Les mots du jeu » : les cartes du glossaire, avec une recherche ;
    - « À propos » : licence, crédits, version ;
    - le tutoriel est proposé en tête de l'aide.
-5. **Scénarios Gherkin** : premier lancement, installation, suivre le tutoriel.
-6. **`make test-browser`** :
+5. **Mise à jour de l'application** (demande de Pierre du 2026-11-09). Quand
+   le service worker trouve une nouvelle version, l'app affiche un bandeau
+   discret « Nouvelle version disponible » avec « Mettre à jour », jamais
+   pendant un coup en cours. Toucher le bouton active la nouvelle version
+   (`skipWaiting`, puis rechargement au `controllerchange`), et la partie
+   reprend où elle en était. Le menu propose aussi « Rechercher une mise à
+   jour » (`registration.update()`), qui dit « Vous avez la dernière
+   version » sinon. L'onglet « À propos » affiche la version publiée (le
+   commit de `version.json`). Aujourd'hui, `web/sw.js` appelle
+   `skipWaiting()` dès l'installation et efface l'ancien cache : une page
+   ouverte garde son ancien code et peut ne plus trouver les anciens
+   fichiers. Le nouveau service worker doit attendre l'accord du joueur, sauf
+   à la toute première installation.
+6. **Scénarios Gherkin** : premier lancement, installation, suivre le tutoriel.
+7. **`make test-browser`** :
    - premier lancement, tutoriel complet avec ses écrans « à vous », aide ;
+   - mise à jour : publier deux versions du site de test l'une après
+     l'autre, voir le bandeau, mettre à jour, retrouver la partie ;
    - `beforeinstallprompt` simulé dans Chromium ;
    - captures dans `build/browser-shots/accueil-tutoriel/` pour la recette design.
 

docs/plans/2026-11-03-conseil-du-maitre.md

@@ -29,7 +29,7 @@ du moteur.
    (événement d'analyse rétrocompatible, ou cache séparé justifié) pour servir
    au bilan (1e) sans recalcul.
 2. **Ligne du maître** : icône d'appréciation, mot en couleur (« Bon coup. »,
-   « Imprécision. », « Erreur. », « Gaffe. » : correspondance avec les seuils
+   « Imprécision. », « Erreur. », « Grosse erreur. » (choix de Pierre du 2026-11-09, plutôt que « gaffe ») : correspondance avec les seuils
    de gnubg documentée), phrase courte en italique, chevron. Toucher ouvre la
    feuille d'explication : coup joué et meilleur coup montrés sur le plateau
    (pions animés, ADR 0011 « comparaison visuelle »), écart d'équité seulement