2026-11-03 06:13:34 +00:00
6 changed files with 183 additions and 42 deletions
@@ -0,0 +1,55 @@
+# Étape 1 — V1 « Jouer et comprendre »
+
+Document temporaire : il décrit l'étape en cours et sera supprimé à sa clôture,
+après report de ce qui est durable dans les ADR et le journal.
+
+**Critère de fin** (cadrage) : un débutant apprend et joue seul ; un joueur de
+club comprend ses erreurs. Livré avec un plan de test (`docs/guide-test-etape-1.md`)
+que Pierre déroule sur le Fairphone 4.
+
+**Préalable** : les sous-étapes 0e (retours du premier test) de la feuille de
+route, dont la revue UX validée par Pierre.
+
+## Périmètre
+
+Repris du cadrage (modules, écrans clés, IA générative en V1) et des ADR 0010,
+0011 et 0012. Ce qui n'y figure pas est hors de l'étape 1.
+
+| Sous-étape | Contenu | Dépend de |
+| --- | --- | --- |
+| 1a. Moteur pour l'analyse | 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 | 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 |
+| 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 |
+| 1h. Progression | Historique des parties et courbe du taux d'erreur | 1b, 1e |
+| 1i. Plateau soigné | Dessin du plateau aligné sur la charte (`docs/identite/charte/board.js`), animations des pions, glisser-déposer en plus du toucher, double toucher pour le seul coup évident | 0e.3 |
+| 1j. Plan de test | `docs/guide-test-etape-1.md` : parcours du débutant et du joueur de club sur le téléphone, avec ce qu'il faut rapporter | toutes |
+
+## Orientation donnée par Pierre
+
+- **Un coach bienveillant, mis en avant mais discret** (2026-11-03) : le
+  conseil du maître et les conseils sont une signature de l'app, présents à
+  chaque partie, sans jamais interrompre le jeu ni culpabiliser le joueur. Le
+  ton des phrases du maître est encourageant ; l'espace qu'il occupe est
+  réservé dans la mise en page (revue UX 0e.2), pas en fenêtre surgissante.
+
+## Questions pour Pierre (ne bloquent pas le démarrage)
+
+- **Indice** : le cadrage le liste dans le module Jeu, l'ADR 0011 l'a laissé
+  « à concevoir séparément ». Il n'est pas dans l'étape 1 sans décision.
+- **Questionnaire de premier lancement** (choix du parcours) : le parcours 1
+  seul existe en V1 ; proposé : un simple choix « Je découvre » / « Je connais
+  les règles » qui oriente vers le tutoriel ou la partie.
+- **Seuils des appréciations** : proposés d'après ceux de GNU Backgammon
+  (douteux 0,04, mauvais 0,08, très mauvais 0,16 d'équité), à calibrer.
+- **Relecture des leçons** par un joueur fort de l'Atelier du Huit.
+
+## Ordre de réalisation
+
+1a et 1b d'abord (fondations, sans conflit avec l'interface), en parallèle des
+sous-étapes 0e. Puis 1c, 1d, 1e, 1f dans cet ordre ; 1g après la validation des
+maquettes d'accueil et de tutoriel par Pierre ; 1h et 1i ; 1j en dernier. Chaque
+sous-étape a son plan dans `docs/plans/` et sa merge request.
@@ -24,8 +24,7 @@ Demandes de Pierre du 2026-11-03, traitées avant d'ouvrir l'étape 1.
 | Sous-étape | Contenu | État | Plan |
 | --- | --- | --- | --- |
 | 0e.1 | Saisie du coup : pion à destination unique joué en un toucher, coup à valider et annulable demi-coup par demi-coup, dés joués marqués, dés des deux côtés touchables, videau confirmé ; pages de test du moteur retirées | 🔄 | `plans/2026-11-03-saisie-du-coup.md` |
-| 0e.2 | Revue UX par un designer UI : compte de points, fluidité (bouton « Nouvelle partie », interruptions), paysage ; propositions à valider par Pierre | 🔄 | `plans/2026-11-03-revue-ux.md` |
-| 0e.3 | Paysage sur téléphone : plateau sur presque tout l'écran, contrôles en pictogrammes (ADR 0012 à amender), selon la revue validée | ⏳ | |
+| 0e.3 | Révision UX arbitrée (session « identité », sur délégation de Pierre) : portrait stable, bandeaux de compte de points, menu en feuille et nouvelle partie annulable, vibrations, écran allumé, paysage « plateau = écran » dès la rotation (ADR 0012 amendé) | ⏳ | `plans/2026-11-03-revision-ux.md` |
 | 0e.4 | Position dans l'adresse : chaque position du plateau a un lien direct (nouvel ADR pour le format) | ⏳ | |
 | 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 | ⏳ | |

@@ -33,7 +32,7 @@ Demandes de Pierre du 2026-11-03, traitées avant d'ouvrir l'étape 1.

 | Étape | Contenu | État |
 | --- | --- | --- |
-| 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 | ⏳ |
+| 1. V1 Jouer et comprendre | Détail et ordre dans `docs/etape-1.md` : moteur pour l'analyse, parties enregistrées et branches, match et réglages, conseil du maître, fin de partie et analyse, prompts, accueil, tutoriel et leçons, progression, plateau soigné, plan de test | 🔄 |
 | 2. V1.5 Apprendre | Parcours 2, exercices, progression | ⏳ |
 | 3. V2 Perfectionnement et IA | Parcours 3 et 4, rollouts, révision espacée | ⏳ |

@@ -128,10 +128,11 @@ Une entrée datée par session : ce qui a été fait, décidé, et la suite.
  la session technique implémente. Numéros des flèches à 12 px minimum.
 - Décision de Pierre : la vue paysage « plateau = écran » s'applique dès la
  rotation du téléphone, sans plein écran (amendement de l'ADR 0012).
+- Mode avion vérifié par Pierre sur le téléphone : l'application fonctionne
+  hors ligne.
+- Étape 1 découpée dans `docs/etape-1.md` (sous-étapes 1a à 1j).
 - Nouvel objectif fixé par Pierre : traiter les retours 0e (les siens et ceux
  du designer), puis réaliser l'étape 1, livrée avec un plan de test.

 **Reste à faire**
- Le test en mode avion sur le téléphone n'a pas été rapporté ; le hors ligne
-  est vérifié dans Chromium par `make test-browser`.
 - Firefox sur le téléphone reste à mesurer.
@@ -0,0 +1,60 @@
+# Moteur pour l'analyse et les niveaux (1a)
+
+- **Date** : 2026-11-03
+- **Étape** : 1a (`docs/etape-1.md`)
+- **Statut** : en cours
+- **Exécutant** : sous-agent general-purpose, dans un worktree
+
+## Objectif
+
+Donner au domaine tout ce dont l'étape 1 a besoin du moteur : niveaux de jeu de
+l'ordinateur, analyse d'un coup joué et d'une décision de videau, chance d'un
+jet. Tout vient de GNU Backgammon, comparé à gnubg de bureau.
+
+## Consignes
+
+ADR 0005, 0007 et la méthode de comparaison de `tests/reference/` (README).
+Ne pas modifier `engine/gnubg/` (copie fidèle). Pas de nouvelle dépendance.
+
+1. **Niveaux de jeu** : les niveaux de GNU Backgammon (débutant, amateur,
+   intermédiaire, avancé, expert, champion du monde…), avec leurs plis, filtres
+   et bruit, repris des réglages prédéfinis de gnubg (pas inventés). Le bruit
+   doit être déterministe (option « deterministic » de gnubg) pour que les
+   tests soient reproductibles. API C (`engine.h`), `engine-cli`, adaptateur
+   WebAssembly et interface `Engine` du domaine (ajout seulement : ne pas
+   toucher au reste de `app/src/domain/game/`, qu'un autre agent modifie).
+2. **Analyse d'un coup joué** : pour une position, un jet et un coup joué,
+   l'équité du coup joué, celle du meilleur coup, l'écart, et le rang du coup
+   joué, au niveau d'analyse demandé (comme l'analyse de partie de gnubg).
+3. **Analyse d'une décision de videau** : équités sans double, double/prend,
+   double/passe, et l'écart de la décision prise (double, pas de double,
+   prendre, passer), comme gnubg.
+4. **Chance d'un jet** : la chance (luck) d'un jet au sens de gnubg, et son
+   classement (très chanceux… très malchanceux) avec les seuils de gnubg.
+5. **Seuils d'appréciation** : exposer les seuils de gnubg (douteux, mauvais,
+   très mauvais) comme constantes documentées ; l'interface les traduira.
+6. **Références** : ajouter des positions de référence évaluées par gnubg de
+   bureau (Docker existant, `make reference`) pour l'analyse d'un coup, d'une
+   décision de videau et la chance, comparées par `make test` (natif et
+   WebAssembly) avec la tolérance existante. Les niveaux avec bruit : vérifier
+   au moins que le coup choisi est reproductible et identique à celui de gnubg
+   de bureau sur quelques positions.
+7. Glossaire : fiches pour les nouveaux termes (niveau, chance, appréciation,
+   équité si absente…), reliées au code.
+8. Mesurer sous Node (`make bench` ou équivalent) le temps d'une analyse de
+   coup au niveau prévu pour le conseil du maître (2 plis), pour vérifier
+   qu'elle tient en arrière-plan sur le téléphone (repère : ADR 0009).
+
+Machine ancienne : `-j2`, ne recompiler le moteur que si nécessaire.
+`make lint` et `make test` doivent passer. Commits fréquents ; `git add` avec
+chemins explicites ; ne pas pousser, pas de MR.
+
+## Critères de réussite
+
+- `engine-cli` répond aux nouvelles commandes en JSON.
+- Les nouvelles références concordent avec gnubg de bureau, natif et WebAssembly.
+- `make lint` et `make test` passent.
+
+## Résultat
+
+À remplir à la clôture.
@@ -0,0 +1,63 @@
+# Révision UX : portrait stable, compte de points, menu, paysage « plateau = écran »
+
+- **Date** : 2026-11-03
+- **Étape** : 0e.3 (feuille de route)
+- **Statut** : prévu (après la fusion de 0e.1, qui touche les mêmes fichiers)
+- **Exécutant** : sous-agent general-purpose, dans un worktree
+
+## Objectif
+
+Appliquer la revue UX (0e.2) telle qu'arbitrée par la session « identité » sur
+délégation de Pierre le 2026-11-03, et l'amendement de l'ADR 0012.
+
+## Références
+
+- Maquettes : https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe, rangées
+  « Révision UX » en bas du canevas.
+- Règles : section « Interaction » du design system, copiée dans
+  `docs/identite/charte/interaction.md` (durées, courbes, motifs de vibration,
+  touches) et composant Icons (10 pictogrammes).
+- Rapport du designer UI : conservé dans la description de la MR qui clôt ce
+  plan.
+
+## Décisions à appliquer
+
+1. **Portrait stable** (maquette « Portrait révisé ») :
+   - une barre haute avec le symbole et trois pictogrammes, libellés de 13 px dessous : Aide, Plein écran, Menu ;
+   - le bandeau de l'ordinateur, puis le plateau, puis le bandeau du joueur ;
+   - une ligne réservée de 44 px : le dernier coup de l'ordinateur avec ↻, ou la ligne du maître ;
+   - la consigne ;
+   - une barre d'actions collée en bas, l'action secondaire à gauche et la principale à droite (« Jouer ce coup »). Toucher les dés valide aussi ;
+   - la durée de calcul affichée disparaît.
+2. **Compte de points** :
+   - en portrait, des bandeaux. Les chiffres sont en 20 px gras, alignés. Le bandeau de celui qui a la main est en accent-soft (« Vous · à vous de jouer »). L'écart s'écrit « mène de 8 », en muted, du côté de celui qui mène. Toucher le chiffre ouvre une bulle avec le texte de la fiche du glossaire (source unique, ADR 0008) ;
+   - en paysage, des pastilles aux bouts de la barre.
+3. **Menu en feuille** qui monte du bas :
+   - il contient Nouvelle partie, Plein écran, Aide et glossaire, Thème, et les interrupteurs Vibrations et « Écran allumé pendant la partie » ;
+   - « Nouvelle partie » agit sans confirmation. Un bandeau « Nouvelle partie commencée. Reprendre l'ancienne » reste 10 s avec une barre de temps, et l'ancienne partie se restaure depuis son journal ;
+   - plus de `window.confirm`.
+4. **Pas de passage automatique du tour** quand aucun coup n'est possible : les dés sont barrés avec le message, et le joueur passe en touchant les dés (ou Espace). Ajouter `overscroll-behavior: none` et `user-select: none`. L'écran reste allumé pendant une partie (Wake Lock), activé par défaut, avec un interrupteur.
+5. **Paysage, « le plateau est l'écran »** (ADR 0012 amendé) :
+   - la vue s'applique dès la rotation, sur `100dvh` ;
+   - la géométrie suit l'écran, par une fonction pure testée unitairement, d'après les formules du composant Board des maquettes ;
+   - une colonne de commandes à gauche dans le cadre : menu en haut, videau au milieu, ↶ en bas, remplacé par ↻ quand le coup de l'ordinateur est montré ;
+   - les sorties restent libres ;
+   - numéros des flèches à 12 px au moins ;
+   - la fin de partie s'affiche dans un panneau centré sur un voile ;
+   - le plein écran s'ouvre sur un geste (pictogramme ou menu), avec `requestFullscreen` puis `screen.orientation.lock` et un repli par rotation CSS. Ce n'est pas le réglage par défaut de l'app installée.
+6. **Vibrations** (`navigator.vibrate`, si disponible) aux quatre moments, avec les motifs d'`interaction.md` : pion posé, pion frappé, double proposé par l'ordinateur, fin de partie. Elles sont activées par défaut, rien au lancer des dés, et elles doublent toujours un signal visible.
+7. **Pictogrammes** du composant Icons, en SVG dans le site (CSP : pas de style en ligne).
+8. **Consigne** : forme longue pendant les trois premières parties, puis forme courte.
+9. **Mouvement** :
+   - durées de 90, 160 et 240 ms, avec la courbe cubic-bezier(0.2, 0, 0, 1) ;
+   - l'ordinateur joue pion par pion : 160 ms par pion, 120 ms de pause ;
+   - `prefers-reduced-motion` est respecté.
+10. **Clavier** (priorité basse) : prévoir dans l'architecture une table d'actions commune au toucher et au clavier. Les touches d'`interaction.md` peuvent venir dans une MR ultérieure.
+
+## Consignes
+
+ADR 0007 : ni le domaine ni le moteur ne changent pour la mise en page. ADR 0008 : scénarios Gherkin pour les comportements visibles nouveaux (nouvelle partie annulable, menu). Aucune nouvelle dépendance. `tests/browser/play.mjs` étendu aux deux orientations, avec des captures Playwright en 412×915, 915×412 et 844×320, en thème clair et sombre, rangées dans un dossier indiqué par la session principale pour la revue design. `make lint`, `make test` et `make test-browser` passent.
+
+## Résultat
+
+À remplir à la clôture.
@@ -1,37 +0,0 @@
-# Revue UX : compte de points, fluidité, paysage
-
- **Date** : 2026-11-03
- **Étape** : 0e (retours du premier test de Pierre sur le téléphone)
- **Statut** : en cours
- **Exécutant** : sous-agent general-purpose, rôle de designer UI, en lecture
-  seule sur le code
-
-## Objectif
-
-Proposer à Pierre, avec maquettes, une meilleure présentation du compte de
-points et une revue de toute l'expérience de jeu (point 10 de son message du
-2026-11-03), en couvrant la fluidité (ligne 0d.2+ de la feuille de route) et le
-paysage sur téléphone (point 5).
-
-## Consignes
-
- Partir de la charte (`docs/identite/`, ADR 0010), des ADR 0011 et 0012, et de
-  l'application publiée (https://ustagammon.sans.pub, ou `make site` puis les
-  captures de `make test-browser`).
- Ne pas modifier le dépôt. Livrer un rapport en Markdown (chemin indiqué par
-  la session principale) et, si utile, une page de maquettes.
- Pour chaque proposition : le problème observé, la solution, sa maquette, son
-  coût technique estimé, et ce qui relève d'un choix de Pierre.
- Sujets imposés : compte de points ; bouton « Nouvelle partie » et tout ce qui
-  interrompt la partie ; paysage sur téléphone, plateau sur presque tout
-  l'écran, contrôles en pictogrammes.
- Les changements de saisie du coup en cours (plan
-  `2026-11-03-saisie-du-coup.md`) sont acquis : ne pas les reproposer.
-
-## Critères de réussite
-
-Un rapport priorisé que Pierre peut valider point par point.
-
-## Résultat
-
-À remplir à la clôture.