Accueil, tutoriel, aide : plan clos ; adresses ajoutées à l'ADR 0013
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Pierre MARTIN
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
8fd1ba3f4f
commit
71bff4def1
@@ -1,153 +0,0 @@
|
||||
# Accueil, installation, tutoriel des règles, aide (0e.5)
|
||||
|
||||
- **Date** : 2026-11-03
|
||||
- **Étape** : 0e.5 (feuille de route), qui couvre aussi le tutoriel de 1g
|
||||
- **Statut** : prévu (après la fusion de 0e.4)
|
||||
- **Exécutant** : sous-agent general-purpose, dans un worktree
|
||||
|
||||
## Objectif
|
||||
|
||||
Traiter les points 2 et 3 du message de Pierre du 2026-11-03 et sa demande d'installation en un toucher :
|
||||
- une page d'accueil ;
|
||||
- l'installation proposée par l'app ;
|
||||
- un tutoriel des règles très didactique, illustré par le plateau ;
|
||||
- une aide plus humaine.
|
||||
|
||||
## Références
|
||||
|
||||
- Règles : `docs/identite/charte/accueil-tutoriel-aide.md`. Le texte du tutoriel y figure en première version, à faire valider par Pierre.
|
||||
- Maquettes : https://claude.ai/artifact/CQw6vbDpi6XQqVWQa4sANe, rangée « Étape 0e.5 » et artboard « Accueil ».
|
||||
- ADR 0008 (source unique), ADR 0013 (positions par identifiants gnubg).
|
||||
|
||||
## Consignes
|
||||
|
||||
1. **Accueil**, selon la charte :
|
||||
- au premier lancement, et une seule fois, le choix entre « Je découvre » et « Je connais les règles » ;
|
||||
- ensuite : la partie en cours, la carte d'installation, la prochaine leçon et la progression résumée. La leçon et la progression restent en attente tant que 1g et 1h n'existent pas : n'afficher que ce qui existe.
|
||||
2. **Installation** :
|
||||
- sous Chrome, garder l'invite reçue avec `beforeinstallprompt` ;
|
||||
- sous Firefox et sur iPhone, une feuille en 3 étapes ;
|
||||
- la carte n'apparaît qu'à partir de la première partie terminée. « Plus tard » la masque, et elle ne revient qu'une fois, après 3 parties. Le menu garde une ligne tant que l'app n'est pas installée ;
|
||||
- plus rien en `display-mode: standalone` ni après l'événement `appinstalled`.
|
||||
3. **Tutoriel**, en 8 étapes :
|
||||
- le texte vit dans un fichier source unique sous `docs/` (par exemple `docs/tutoriel/`), copié dans le site par `make site` comme le glossaire, sous licence CC BY-SA 4.0 ;
|
||||
- positions données par leurs identifiants gnubg ;
|
||||
- sur les écrans « à vous », le moteur vérifie le coup joué en le comparant aux coups attendus de l'étape ;
|
||||
- le coup illustré se joue seul après 1 s, avec « Revoir » ;
|
||||
- un test vérifie que chaque position du tutoriel est valide pour le moteur et que chaque coup attendu est légal ;
|
||||
- ajouter la fiche du glossaire « camp ».
|
||||
4. **Aide**, en trois onglets :
|
||||
- « Jouer » : les scénarios deviennent des questions repliables. Le titre est la question et la description la réponse ; les étapes Gherkin sont cachées. Reformuler les titres des `.feature` sans casser les tests ;
|
||||
- « 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. **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.
|
||||
|
||||
Chaque écran (accueil, étapes du tutoriel, onglets et questions de l'aide) a son adresse et s'ouvre par un vrai lien, selon l'amendement de l'ADR 0013 ; le routeur vient de 0e.4.
|
||||
|
||||
`make lint`, `make test` et `make test-browser` doivent passer. Aucune nouvelle dépendance.
|
||||
|
||||
## Critères de réussite
|
||||
|
||||
- Un débutant suit le tutoriel jusqu'au bout sur le téléphone, et chaque écran « à vous » accepte le bon coup et refuse les autres.
|
||||
- Les trois commandes passent, et les captures sont livrées pour la recette.
|
||||
|
||||
## Résultat
|
||||
|
||||
Exécuté le 2026-11-09 sur la branche `accueil-tutoriel-aide`, construite sur
|
||||
`adresses-ecrans` (0e.4, en recette).
|
||||
|
||||
1. **Accueil** (`#/accueil`, `app/src/ui/home-view.ts`, `home-model.ts`).
|
||||
Lancée sans adresse d'écran (icône, adresse du site), l'application
|
||||
s'ouvre sur l'accueil ; `#/` reste la partie. Premier lancement (rien de
|
||||
fait : ni choix, ni partie terminée, ni étape du tutoriel) : logo,
|
||||
plateau de départ, « Bienvenue à la table », « Je découvre » (lien
|
||||
`#/tutoriel/1`) et « Je connais les règles » (lien `#/`), une seule fois.
|
||||
Ensuite : la partie en cours (miniature, comptes, « Reprendre la partie »
|
||||
en action principale, ou « Nouvelle partie » s'il n'y a rien à
|
||||
reprendre), l'invitation à installer, une carte « Les règles du jeu »
|
||||
(le tutoriel : seul contenu d'apprentissage qui existe), la progression
|
||||
(« N parties jouées · M gagnées », sans les leçons) et la phrase de
|
||||
l'Atelier du Huit. Le logo de la barre haute et le menu mènent à
|
||||
l'accueil.
|
||||
2. **Installation** (`install.ts`) : invite gardée de `beforeinstallprompt`,
|
||||
sinon marche à suivre en trois étapes (Firefox, iPhone) dans une feuille
|
||||
à son adresse, `#/installer`. Carte après la première partie terminée,
|
||||
« Plus tard » une fois, retour après trois parties de plus ; ligne du
|
||||
menu tant que l'application n'est pas installée ; plus rien en
|
||||
`display-mode: standalone` ni après `appinstalled` (retenu dans les
|
||||
réglages).
|
||||
3. **Tutoriel** : texte unique `docs/tutoriel/regles.md` (format :
|
||||
`docs/tutoriel/README.md`), copié par `make site`, CC BY-SA 4.0, texte de
|
||||
la charte. Huit étapes, écrans « à vous » aux étapes 3, 4, 6 et 8,
|
||||
adresses `#/tutoriel/<n>`, `#/tutoriel/<n>/a-vous`, `#/tutoriel/fin`.
|
||||
Positions par identifiants gnubg ; coup illustré joué seul après 1 s,
|
||||
pion par pion, avec « Revoir » ; sens du jeu en pointillés sur liseré
|
||||
ivoire (étape 2). Domaine : `app/src/domain/learning/tutorial.ts`
|
||||
(`MovePractice`, `illustratedMove`, `shouldTake`) ; le moteur dit les
|
||||
demi-coups permis, et un coup est juste s'il mène à la position d'un des
|
||||
coups attendus. Refus : le pion revient, une phrase dit pourquoi ; succès :
|
||||
coche, vibration « pion posé », « Continuer » principal. La barre de
|
||||
progression ne lie que les étapes déjà vues. `app/tests/tutorial.test.ts`
|
||||
joue chaque coup légal de chaque écran « à vous » sur le vrai moteur.
|
||||
Fiche du glossaire `camp.md` ajoutée.
|
||||
4. **Aide** : onglet « Jouer » en questions (titres des scénarios reformulés,
|
||||
descriptions ajoutées là où il n'y en avait pas, étapes cachées, lien
|
||||
« Voir sur le plateau » par l'étiquette `@position:`), carte du tutoriel en
|
||||
tête, « Les mots du jeu » en cartes triées avec nom anglais, renvois et
|
||||
recherche sans accents, « À propos » (licences, crédits, version publiée
|
||||
lue dans `version.json`). Le bouton « Aide » de la partie ouvre la
|
||||
question du moment (`help-context.ts`, titres vérifiés par un test).
|
||||
5. **Mise à jour** (`updates.ts`, `web/sw.js`) : le service worker installe
|
||||
la nouvelle version puis attend (plus de `skipWaiting()` à
|
||||
l'installation, sauf à la première où rien n'attend) ; bandeau
|
||||
« Nouvelle version disponible » en haut, jamais pendant un coup en cours ni
|
||||
sur « Reprendre l'ancienne » ; « Mettre à jour » envoie `skip-waiting`,
|
||||
rechargement au `controllerchange`, la partie reprend. Menu « Rechercher
|
||||
une mise à jour » (`registration.update()`), qui répond « Vous avez la
|
||||
dernière version. ».
|
||||
6. **Scénarios** : `decouvrir-l-application.feature`,
|
||||
`installer-l-application.feature`, `apprendre-les-regles.feature`, et
|
||||
« Comment mettre l'application à jour ? » dans
|
||||
`regler-l-application.feature`, exécutés par Cucumber.
|
||||
7. **`make test-browser`** : `tests/browser/accueil.mjs` (premier lancement,
|
||||
tutoriel complet avec un geste refusé puis juste sur chaque écran
|
||||
« à vous », installation avec `beforeinstallprompt` simulé dans Chromium,
|
||||
aide, mise à jour sur un second site dont le test publie une deuxième
|
||||
version) ; `play.mjs` adapté (accueil, tutoriel et installation ont leur
|
||||
adresse). Captures dans `build/browser-shots/accueil-tutoriel/`.
|
||||
|
||||
**Écarts et points à trancher**
|
||||
|
||||
- Les adresses `#/tutoriel/<n>/a-vous`, `#/tutoriel/fin` et `#/installer`
|
||||
s'ajoutent au tableau de l'ADR 0013 (amendement à consigner).
|
||||
- Étape 7 : avec la règle de Jacoby, active en partie libre, un gammon ne
|
||||
vaut 2 points qu'une fois le videau doublé (le moteur compte 1 point
|
||||
sinon). Le texte de la charte est gardé, avec une phrase ajoutée qui le
|
||||
dit ; à valider par Pierre.
|
||||
- Les boutons de l'écran « à vous » du videau s'appellent « Je prends » et
|
||||
« Je passe », pour ne pas se confondre avec « Passer » (le tutoriel).
|
||||
- « Toutes les leçons » et la prochaine leçon attendent 1g ; la carte
|
||||
« Les règles du jeu » tient leur place.
|
||||
- La partie commencée d'office au chargement compte dans « parties
|
||||
commencées » : le premier lancement reste affiché jusqu'à une partie
|
||||
commencée de plus.
|
||||
Reference in New Issue
Block a user