Merge remote-tracking branch 'origin/main' into charte-ui

docs/adr/0011-lecons-conseil-et-bilan.md

@@ -0,0 +1,59 @@
+# 0011. Leçons numérotées, conseil du maître après le coup, bilan de fin de partie
+
+- **Statut** : accepté
+- **Date** : 2026-11-03
+- **Décideurs** : Pierre
+
+## Contexte
+
+Le cadrage (`docs/cadrage.md`) prévoit pour la V1 un coach en direct, un écran
+de fin de partie et des leçons par concept, sans en fixer la forme. Les
+maquettes des écrans (https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe),
+faites avec la charte graphique (ADR 0010), en ont proposé une. Pierre en a
+retenu trois éléments le 2026-11-03.
+
+Un point des maquettes contredisait le cadrage : le conseil apparaissait avant
+que le joueur ne joue, en donnant la réponse. Pierre a tranché pour un
+commentaire après le coup.
+
+## Décision
+
+- **Leçons numérotées** : un parcours de leçons dans un ordre fixe
+  (« Leçon 1 », « Leçon 2 »…). Chaque leçon affiche son état (à commencer,
+  « 3 exercices sur 5 », terminée) et sa progression. L'accueil propose de
+  continuer la leçon en cours.
+- **Conseil du maître** : c'est la forme du coach en direct du cadrage. Il
+  commente le coup **après** que le joueur l'a joué, jamais avant. Il donne
+  l'appréciation du moteur avec un mot et une icône (bon coup, imprécision,
+  erreur), puis une phrase du maître qui dit quel coup il aurait joué et
+  pourquoi, avec un lien pour en savoir plus. L'écart d'équité n'apparaît que
+  sur demande. Il reste désactivable, comme le prévoit le cadrage.
+- **Bilan de fin de partie** : le résultat, le décompte des coups par
+  appréciation (bons coups, imprécisions, erreurs), « le coup à revoir »
+  (la plus grosse erreur, avec sa position, le coup joué et le meilleur coup)
+  et le prompt prêt à copier pour une IA.
+
+Les maquettes de référence sont les écrans « Plateau de jeu », « Leçon et
+aide » et « Fin de partie » du canevas ci-dessus.
+
+## Alternatives écartées
+
+- **Conseil avant le coup, avec la réponse** : le joueur n'essaie plus par
+  lui-même, et on n'apprend pas en recopiant.
+- **Indice avant le coup, sans la réponse, en plus du commentaire après** :
+  écarté pour l'instant au profit d'un seul mécanisme simple. L'« indice » de
+  la liste des fonctions du cadrage reste à concevoir séparément.
+
+## Conséquences
+
+- Le commentaire après le coup demande une analyse du coup joué par le moteur
+  (classement des coups et écart avec le meilleur). Elle doit tenir dans le
+  budget de temps du téléphone, en arrière-plan, sans retarder le tour
+  suivant.
+- Les seuils entre « bon coup », « imprécision » et « erreur » sont à fixer,
+  en s'appuyant sur ceux de GNU Backgammon (doubtful, bad, very bad).
+- Les phrases du maître doivent rester exactes : elles s'appuient sur les
+  coups et les chiffres du moteur, jamais sur une explication inventée.
+- Les leçons sont des contenus sous CC BY-SA 4.0, à écrire et à faire relire
+  par un joueur fort (cadrage, risque « contenus longs à produire ») ; leur
+  progression est stockée localement.

docs/adr/0012-mode-immersif.md

@@ -0,0 +1,55 @@
+# 0012. Mode immersif : le plateau en paysage, sur demande
+
+- **Statut** : accepté
+- **Date** : 2026-11-03
+- **Décideurs** : Pierre
+
+## Contexte
+
+Sur l'écran de jeu en portrait, le plateau n'occupe qu'environ 35 % de l'écran
+d'un téléphone (pions de 24 px sur un écran de 390 px de large). Pierre le
+trouve peu immersif et a demandé un mode où le plateau prend le maximum de
+l'écran.
+
+Deux pistes ont été maquettées
+(https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe, rangée « Mode immersif ») :
+le téléphone en paysage, plateau sur toute la hauteur ; ou le portrait avec le
+plateau tourné d'un quart de tour. Toutes deux donnent environ 57 % de l'écran
+au plateau et des pions de 30 px : le petit côté de l'écran limite la taille
+des pions dans les deux cas.
+
+## Décision
+
+- Un **mode immersif en paysage** : le plateau occupe toute la hauteur, dans
+  son orientation habituelle. À gauche : le menu, les comptes de points et la
+  consigne. À droite : l'aide et les actions. Le fond est en noyer jusqu'aux
+  bords de l'écran.
+- On y entre **par un geste explicite** : un bouton « Plein écran » sur l'écran
+  de jeu en portrait. On en sort par le menu ou par le retour du téléphone.
+- Le bouton force la vue paysage même si le téléphone est tenu droit ou si sa
+  rotation automatique est verrouillée : passage en plein écran
+  (`requestFullscreen`), puis verrouillage de l'orientation
+  (`screen.orientation.lock("landscape")`).
+- Si le verrouillage est refusé (navigateur ou système qui ne le permet pas,
+  iPhone), l'app affiche la vue paysage tournée d'un quart de tour dans l'écran
+  portrait. Le résultat est le même en main.
+- L'écran de jeu en portrait reste la vue par défaut, pour jouer d'une main.
+
+## Alternatives écartées
+
+- **Plateau tourné en portrait** : il change la lecture du plateau (numéros de
+  côté, camps à gauche et à droite) et risque de dérouter les débutants habitués
+  à une vraie table.
+- **Bascule automatique quand on tourne le téléphone** : elle ne marche pas si
+  la rotation est verrouillée, et elle surprend en cours de partie. Elle reste
+  possible en plus du bouton, plus tard.
+
+## Conséquences
+
+- Le rendu du plateau doit s'adapter à deux mises en page (portrait et paysage)
+  sans changer le domaine ni le moteur : seule la vue change (ADR 0007).
+- `screen.orientation.lock` n'est accepté qu'en plein écran, et pas partout :
+  la solution de repli par rotation CSS est obligatoire, et elle doit être
+  testée (`make test-browser`).
+- Le plein écran masque la barre d'état du téléphone, ce qui libère encore un
+  peu de place.

docs/adr/README.md

@@ -17,3 +17,5 @@ l'ancien passe au statut « remplacé par NNNN ». Voir l'ADR 0001.
 | [0008](0008-glossaire-et-scenarios-source-unique.md) | Glossaire et scénarios : une source unique pour le code, l'aide et les tests | accepté |
 | [0009](0009-socle-pwa-typescript.md) | Socle : PWA en TypeScript, moteur en WebAssembly | accepté |
 | [0010](0010-identite-visuelle.md) | Identité visuelle : symbole, logotype, palette | accepté |
+| [0011](0011-lecons-conseil-et-bilan.md) | Leçons numérotées, conseil du maître après le coup, bilan de fin de partie | accepté |
+| [0012](0012-mode-immersif.md) | Mode immersif : le plateau en paysage, sur demande | accepté |

docs/feuille-de-route.md

@@ -30,7 +30,7 @@ par coup de l'IA en niveau standard, tous les tests au vert.
 
 | Étape | Contenu | État |
 | --- | --- | --- |
-| 1. V1 Jouer et comprendre | Plateau soigné, niveaux, coach, analyse, branches, tutoriel, prompts, sauvegarde | ⏳ |
+| 1. V1 Jouer et comprendre | Charte graphique appliquée à la PWA (ADR 0010, `docs/identite/charte/`), plateau soigné, niveaux, conseil du maître après le coup, bilan de fin de partie, premières leçons numérotées (ADR 0011), mode immersif en paysage (ADR 0012), analyse, branches, tutoriel, prompts, sauvegarde | ⏳ |
 | 2. V1.5 Apprendre | Parcours 2, exercices, progression | ⏳ |
 | 3. V2 Perfectionnement et IA | Parcours 3 et 4, rollouts, révision espacée | ⏳ |