Fin de l'étape 0, vue paysage dès la rotation #21

Manually merged
pierre merged 1 commits from cloture-etape-0 into main 2026-11-03 06:02:28 +00:00
7 changed files with 64 additions and 260 deletions
+1 -1
View File
@@ -1,7 +1,7 @@
# CLAUDE.md — Règles du projet
Ce fichier est lu par Claude Code au début de chaque session. Il fixe le cadre du projet.
Le cadrage complet est dans `docs/cadrage.md`, l'étape en cours dans `docs/etape-0.md`.
Le cadrage complet est dans `docs/cadrage.md`, le travail en cours dans `docs/feuille-de-route.md`.
**En début de session**, lire `docs/organisation.md`, `docs/feuille-de-route.md`, la fin
de `docs/journal.md`, l'index des ADR (`docs/adr/README.md`) et les plans en cours dans `docs/plans/`, puis reprendre là où en
+24
View File
@@ -53,3 +53,27 @@ des pions dans les deux cas.
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.
## Amendements
### 2026-11-03 — Vue paysage dès la rotation, plateau = écran
Décidé par Pierre après son premier essai sur le téléphone, où la vue paysage
à deux colonnes (plateau limité à 70 % de la largeur, texte à droite) lui a
paru « vraiment pas optimale ».
- Dès que le téléphone est en paysage, même sans plein écran, l'app applique
la mise en page « plateau = écran » sur la hauteur réelle (`100dvh`, barre
d'adresse comprise). La mise en page à deux colonnes disparaît.
- Dans cette vue, les contrôles sont dans le plateau : comptes de points sur la
barre, videau au milieu de la barre, dés et consigne dans la bande centrale,
pictogrammes (menu, annuler, plein écran) dans la colonne des sorties
(maquette « Immersif : plein écran, contrôles dans le plateau » du canevas
ci-dessus). La géométrie du plateau suit les proportions de l'écran ; les
numéros des flèches font au moins 12 px.
- Le bouton « Plein écran » garde son rôle : plein écran, verrouillage en
paysage, repli par rotation CSS.
La bascule automatique écartée plus haut était celle qui forçait
l'orientation ; ici, seule la mise en page suit l'orientation choisie par le
joueur.
-73
View File
@@ -1,73 +0,0 @@
# Étape 0 — Prototype technique
**But** : prouver que la chaîne technique fonctionne avant d'investir dans le design, et trancher entre deux socles : PWA (moteur en WebAssembly) ou Android natif.
**Règle** : chaque sous-étape se termine par une démonstration que le développeur peut lancer lui-même avec une commande `make`.
---
## 0a. Le moteur en ligne de commande
**Objectif** : interroger le moteur GNU Backgammon sur une position, depuis le PC.
À faire :
1. Récupérer les sources du moteur (choisir entre gnubg, gnubg-nn ou le moteur extrait par CBG ; justifier le choix dans un ADR, `docs/adr/`).
2. Définir une **interface C minimale** du moteur (`engine/include/engine.h`, identifiants en anglais : ADR 0007), indépendante de toute interface graphique :
- initialiser le moteur (charger réseaux, base de fin de partie, table d'équité de match) ;
- lister les coups légaux pour une position et des dés ;
- donner le meilleur coup et le classement des coups avec leur équité, pour un niveau d'évaluation donné ;
- donner la décision de videau (pas de double, double/prend, double/passe, avec équités) ;
- évaluer une position (probabilités de gain, gammon, backgammon).
Les positions entrent et sortent au format **GNU Position ID + Match ID**.
3. Écrire `engine-cli`, un petit programme qui expose ces fonctions en ligne de commande, avec une sortie JSON.
4. Générer un jeu de **positions de référence** (au moins 30 : ouvertures, contact, course, sortie, décisions de videau) avec le GNU Backgammon de bureau dans Docker, et stocker les résultats attendus dans `tests/reference/`.
5. `make test` compare `engine-cli` aux références (même meilleur coup, équités à une tolérance près, à fixer).
**Démo** : `make engine && ./build/engine-cli bestmove <position_id> <match_id> 31` affiche le meilleur coup en JSON ; `make test` passe.
---
## 0b. Le test WebAssembly (décisif)
**Objectif** : savoir si le moteur tourne assez vite et léger dans le navigateur du téléphone.
À faire :
1. Compiler le même moteur et la même interface C en WebAssembly avec Emscripten (dans Docker).
2. Charger le moteur dans un **Web Worker** (jamais sur le fil d'affichage).
3. Page HTML minimale : un champ Position ID, des dés, un bouton « meilleur coup », l'affichage du résultat et du temps de calcul.
4. Rejouer les positions de référence dans le navigateur : les résultats doivent concorder avec 0a.
5. `make deploy-web` sert la page sur le réseau local pour l'ouvrir depuis le Fairphone 4.
6. `make bench` (ou une page de mesure) produit un petit rapport : temps par coup selon le niveau d'évaluation, taille téléchargée, mémoire utilisée.
**Critères de réussite (à ajuster après mesure)** :
| Mesure sur le Fairphone 4 | Seuil |
| --- | --- |
| Meilleur coup, niveau rapide (0-ply GNU) | moins de 0,3 s |
| Meilleur coup, niveau fort (2-ply GNU) | moins de 3 s |
| Décision de videau, niveau fort | moins de 3 s |
| Taille totale à télécharger (wasm + données, compressé) | moins de 40 Mo |
| Résultats identiques aux références de 0a | 100 % |
**Démo** : la page ouverte sur le Fairphone donne le meilleur coup d'une position de référence, avec le temps de calcul affiché.
---
## 0c. Android natif (seulement si 0b échoue)
**Objectif** : la même démonstration en application Android.
À faire :
1. Compiler le moteur pour arm64 avec le NDK (dans Docker), en s'appuyant sur la configuration de CBG.
2. Application Android minimale, construite en ligne de commande (Gradle sans Android Studio, `-j2`, démon Gradle limité en mémoire).
3. Même écran de test et mêmes mesures qu'en 0b.
4. `make deploy` installe l'APK sur le Fairphone via adb.
---
## 0d. Plateau minimal et décision
1. Sur le socle retenu, un **plateau minimal** : une partie complète jouable contre le moteur, coups et videau décidés par le moteur, dés tirés par l'app.
2. Rédiger un ADR (`docs/adr/`) : socle retenu (PWA ou Android natif), mesures obtenues, raisons, risques restants.
**Critère de fin de l'étape 0** : une partie complète jouée sur le Fairphone 4, moins de 2 s par coup de l'IA en niveau standard, tous les tests au vert.
+13 -14
View File
@@ -3,33 +3,32 @@
Le travail restant, dans l'ordre. Une ligne réalisée est retirée : ce qui a été
fait se lit dans les merge requests et le journal, ce qui a été décidé dans les
ADR (`docs/adr/`). Les versions et leur contenu sont définis dans
`docs/cadrage.md` ; le détail de l'étape en cours est dans `docs/etape-0.md`.
`docs/cadrage.md`.
Légende : 🔄 en cours · ⏳ à venir · ⏸ conditionnel
## Étape 0 — Prototype technique
## Étape 0 — Prototype technique : terminée
Acquis : socle du dépôt, organisation (ADR 0001, 0003, 0006), source du moteur
(ADR 0005 : gnubg officiel, commit 14b6798), gnubg de référence et 32 positions
de référence (0a.2), moteur embarqué et `engine-cli` (0a.3), comparaison
automatique aux références, tolérance 0,002 (0a.4), moteur en WebAssembly avec
page de test, page de mesure et guide de test (0b), mesures sur le Fairphone 4 et
socle PWA en TypeScript (ADR 0009 ; 0c Android natif abandonnée), domaine
« partie » en journal d'événements avec scénario exécuté sur le vrai moteur et
garde-fous d'architecture (0d.1), déploiement sur https://ustagammon.sans.pub.
Close le 2026-11-03 : partie complète jouée par Pierre sur le Fairphone 4, coups
de l'ordinateur rapides, tous les tests au vert. Acquis : moteur gnubg officiel
(ADR 0005) comparé à 32 positions de référence, moteur en WebAssembly, socle
PWA en TypeScript (ADR 0009 ; Android natif abandonné), domaine « partie » en
journal d'événements, plateau jouable hors ligne avec la charte graphique,
publié sur https://ustagammon.sans.pub. Le détail est dans le journal et les
merge requests.
## Retours du premier test sur téléphone (avant l'étape 1)
Demandes de Pierre du 2026-11-03, traitées avant d'ouvrir l'étape 1.
| Sous-étape | Contenu | État | Plan |
| --- | --- | --- | --- |
| 0d.2 | Plateau minimal jouable (PWA hors ligne), publié ; reste la vérification avec Pierre sur le Fairphone 4 (`docs/guide-test-etape-0.md`, section « Étape 0d ») | 🔄 | |
| 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.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 | ⏳ | |
**Critère de fin** : une partie complète jouée sur le Fairphone 4, moins de 2 s
par coup de l'IA en niveau standard, tous les tests au vert.
## Étapes suivantes
| Étape | Contenu | État |
-171
View File
@@ -1,171 +0,0 @@
# Guide de test : Ustagammon sur le Fairphone 4 (étape 0)
Document temporaire de l'étape 0 : il sera supprimé avec `docs/etape-0.md`.
Deux tests sur le téléphone :
- **Étape 0d : jouer une partie** (section suivante), sur le site publié ;
- **Étape 0b : mesurer le moteur** (fait le 2026-11-02), sur une page
servie par le PC.
## Étape 0d : jouer une partie sur le téléphone
Le but : installer l'application sur le Fairphone 4, jouer une partie
complète contre l'ordinateur, vérifier qu'elle marche sans réseau, et
rapporter ce que vous avez constaté. Comptez une demi-heure.
### Ouvrir et installer l'application
1. Sur le Fairphone, ouvrez Chrome et allez sur https://ustagammon.sans.pub.
2. Attendez que le plateau s'affiche et que le message « Chargement du
moteur… » laisse place à une consigne (par exemple « À vous : lancez les
dés. » ou « L'ordinateur réfléchit… »). La première fois, le moteur se
télécharge (environ 7 Mo) : quelques secondes en Wi-Fi.
3. Installez l'application : menu de Chrome (les trois points), puis
« Installer l'application » ou « Ajouter à l'écran d'accueil ». Une icône
(deux pions sur du bois) apparaît sur l'écran d'accueil.
4. Fermez Chrome et ouvrez Ustagammon depuis cette icône : l'application
s'ouvre en plein écran, sans barre d'adresse.
### Jouer une partie complète
Suivez le scénario « Jouer une partie contre l'ordinateur »
(`docs/scenarios/jouer-une-partie.feature`), qui est aussi l'aide de
l'application : bouton « Aide », en haut.
1. Une partie commence d'elle-même au premier lancement, par le jet
d'ouverture (un dé chacun) : le message dit qui commence. « Nouvelle
partie », en haut, en recommence une.
2. Quand c'est à vous : touchez « Lancer les dés » (ou « Doubler », pour
proposer de doubler avant de lancer).
3. Pour jouer : touchez un pion entouré de vert, puis l'une des cases
d'arrivée en surbrillance ; recommencez pour chaque dé. Pour sortir un
pion, touchez le bac à droite, en bas. « Annuler » remet les pions du coup
en cours à leur place.
4. Le coup est envoyé dès qu'il est complet ; l'ordinateur joue ensuite, et
le message dit son coup et son temps de calcul, par exemple
« L'ordinateur a joué 6-4 : 24/18 13/9 (0,3 s) ». Les petits points
orange marquent ses cases de départ et d'arrivée (dans sa numérotation :
sa case 24 est votre case 1).
5. Si l'ordinateur vous propose de doubler : « Prendre » ou « Passer ».
Essayez au moins une fois de doubler vous-même.
6. En fin de partie, le message donne le gagnant, la sorte de victoire
(simple, gammon ou backgammon) et les points.
En cours de partie, fermez l'application (balayez-la dans la liste des
applications ouvertes), puis rouvrez-la : la partie doit reprendre là où vous
en étiez.
### Vérifier le hors ligne
1. Après avoir ouvert l'application au moins une fois (attendez une
vingtaine de secondes après le premier chargement, le temps que tout soit
mis de côté), fermez-la.
2. Passez le téléphone en mode avion.
3. Rouvrez Ustagammon depuis son icône : le plateau, l'ordinateur et l'aide
doivent fonctionner comme avant.
4. Repassez en mode normal.
### Ce qu'il faut rapporter
Dans la conversation avec Claude Code :
- les **temps des coups de l'ordinateur** : ceux affichés dans les messages
(le plus long que vous avez vu), et votre ressenti (attente gênante ou
non) ;
- si la partie est allée **jusqu'au bout**, et son résultat ;
- si la **reprise** après fermeture et le **mode avion** ont marché ;
- tout ce qui gêne : plateau trop petit, case difficile à toucher, texte
incompréhensible, bouton qui ne répond pas, couleurs peu lisibles (thème
clair ou sombre du téléphone) ;
- une **capture d'écran** (bouton marche + volume bas) de tout problème.
Si vous le pouvez, refaites l'essai dans Firefox sur le téléphone (sans
l'installer) et dites si les temps de l'ordinateur sont nettement plus longs.
## Étape 0b : mesurer le moteur
Le but : ouvrir sur le téléphone une page web où le moteur de backgammon
calcule, puis lancer une mesure et coller son rapport dans la conversation.
Comptez un quart d'heure.
### 1. Préparer le PC
1. Ouvrez un terminal dans le dossier du projet (`~/Code/ustagammon`).
2. Si ce n'est pas déjà fait, tapez `make setup` puis Entrée. Cela prépare les
outils. La première fois, c'est long ; ensuite, c'est immédiat.
3. Le PC et le téléphone doivent être sur **le même Wi-Fi** (la même box).
### 2. Lancer la page
1. Tapez `make deploy` puis Entrée.
2. La première fois, le moteur se compile : quelques minutes.
3. Le terminal affiche deux adresses, par exemple :
```
Application : http://192.168.1.21:8080/
Test du moteur : http://192.168.1.21:8080/moteur/
Page de mesure : http://192.168.1.21:8080/moteur/bench.html
```
Vos chiffres peuvent être différents : notez ceux de votre écran.
4. Laissez ce terminal ouvert pendant tout le test. Pour arrêter la page à la
fin : Ctrl+C dans le terminal.
### 3. Essayer un meilleur coup
1. Sur le Fairphone, ouvrez le navigateur (Chrome ou Firefox).
2. Tapez l'adresse du **test du moteur** dans la barre d'adresse, exactement
comme affichée (avec `http://` et `:8080`). Les pages de test sont aussi
publiées : https://ustagammon.sans.pub/moteur/ et
https://ustagammon.sans.pub/moteur/bench.html.
3. Attendez le message « Moteur prêt, chargé en … ms ».
4. Dans « Exemple », choisissez une position, par exemple « middlegame-1 ».
5. Dans « Niveau », choisissez « fort (2 plis) ».
6. Touchez « Meilleur coup ».
7. La page affiche le coup conseillé et le **temps de calcul**. Notez ce temps
si vous voulez, il sera aussi dans le rapport.
### 4. Lancer la mesure
1. En bas de la page, touchez « Page de mesure » (ou tapez l'adresse de la
page de mesure).
2. Touchez « Lancer la mesure ».
3. Attendez « Mesure terminée » : de une à quelques minutes. Pendant ce temps,
gardez l'écran allumé et la page ouverte, sans changer d'application.
4. Un tableau résume les résultats : « OK » si le seuil est respecté,
« dépassé » sinon.
### 5. Envoyer le rapport
1. Touchez « Copier les résultats ».
2. Si la page dit « Rapport copié », c'est bon.
3. Sinon, le texte du rapport est sélectionné : faites un appui long dessus,
puis « Copier ».
4. Collez le rapport dans la conversation avec Claude Code (sur le téléphone,
ou envoyez-le vous sur le PC).
Si vous en avez le temps, refaites la mesure une deuxième fois (rechargez la
page de mesure) et collez aussi ce second rapport : cela montre si les temps
sont stables. Si les deux navigateurs sont installés, faites la mesure dans
Chrome **et** dans Firefox : sur le PC, Firefox s'est montré nettement plus
lent, et le rapport indique le navigateur utilisé.
### Si la page ne s'ouvre pas
- **Vérifiez l'adresse** : `http://` (et non `https://`), les chiffres exacts,
et `:8080` à la fin.
- **Vérifiez le Wi-Fi** : le téléphone doit être sur le même réseau que le PC,
pas sur la 4G ni sur un Wi-Fi invité.
- **Vérifiez que la page tourne** : sur le PC, ouvrez
`http://localhost:8080/` dans un navigateur. Si elle ne s'ouvre pas non
plus, relancez `make deploy` et lisez le message d'erreur.
- **Le pare-feu du PC** peut bloquer le téléphone. S'il est actif
(`sudo ufw status` affiche « Status: active »), autorisez le port le temps
du test : `sudo ufw allow 8080/tcp`, puis à la fin `sudo ufw delete allow
8080/tcp`.
- **« Le moteur n'a pas pu se charger »** : notez le message exact et
collez-le dans la conversation. Essayez aussi l'autre navigateur (Chrome ou
Firefox), à jour.
- **Le port 8080 est déjà pris** : un autre programme l'utilise. Lancez
`make deploy WEB_PORT=8081` et utilisez `:8081` dans l'adresse.
+25
View File
@@ -110,3 +110,28 @@ Une entrée datée par session : ce qui a été fait, décidé, et la suite.
- Les maquettes proposent des éléments de produit qui ne sont pas encore
décidés (leçons, « Conseil du maître », bilan de fin de partie) : à valider
par Pierre avant toute mise en œuvre.
## 2026-11-03 (matin) : fin de l'étape 0, retours du test sur téléphone
**Fait**
- Pierre a joué une partie complète sur le Fairphone 4 : « très rapide de la
part de l'ordinateur ». Avec les tests au vert, le critère de fin de l'étape 0
est atteint. Le guide de test et `docs/etape-0.md`, temporaires, sont
supprimés ; leurs décisions sont dans les ADR 0005 et 0009.
- Playwright validé par Pierre (amendement de l'ADR 0004, MR !20).
- Douze retours de Pierre après l'essai, plus l'installation en un toucher et
les retours haptiques, rangés en sous-étapes 0e dans la feuille de route
(MR !20). Lancés : la saisie du coup (0e.1) et une revue UX par un designer
UI (0e.2).
- Coordination avec la session « identité » : elle propose et maquette le
design (mode immersif, compte de points, accueil, tutoriel), Pierre tranche,
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).
- 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.
+1 -1
View File
@@ -7,7 +7,7 @@
// Sur les positions de référence (tests/reference/positions.json) : temps du
// meilleur coup à 0 et 2 plis pour les positions avec dés, temps de la
// décision de videau à 2 plis pour les autres. Le rapport compare aux seuils
// de l'étape 0b (docs/etape-0.md).
// de l'étape 0b (ADR 0009).
// Seuils de l'étape 0b. Un temps respecte son seuil si son maximum, sur
// toutes les positions, est en dessous (la médiane est donnée en plus).