diff --git a/docs/adr/0013-position-dans-l-adresse.md b/docs/adr/0013-position-dans-l-adresse.md index 0ba224a..1fb8151 100644 --- a/docs/adr/0013-position-dans-l-adresse.md +++ b/docs/adr/0013-position-dans-l-adresse.md @@ -85,3 +85,16 @@ unique pour tous les écrans, avant sa première mise en œuvre. - Une adresse inconnue mène à la partie en cours avec un message clair. - L'adresse de l'écran courant est la source de vérité de la navigation : l'application l'écoute (`hashchange`) et dessine l'écran correspondant. + +### 2026-11-09 — Adresses du tutoriel et de l'installation + +Ajoutées avec l'accueil et le tutoriel (étape 0e.5), dans le même schéma : + +| Écran | Adresse | +| --- | --- | +| Écran « à vous » d'une étape du tutoriel | `#/tutoriel//a-vous` | +| Fin du tutoriel | `#/tutoriel/fin` | +| Marche à suivre pour installer l'application | `#/installer` | + +Lancée sans adresse, l'application ouvre l'accueil (`#/accueil`) ; `#/` reste +la partie en cours, pour que les liens existants ne changent pas. diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index 182d163..945cb51 100644 --- a/docs/feuille-de-route.md +++ b/docs/feuille-de-route.md @@ -23,7 +23,6 @@ Demandes de Pierre du 2026-11-03, traitées avant d'ouvrir l'étape 1. | Sous-étape | Contenu | État | Plan | | --- | --- | --- | --- | -| 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 diff --git a/docs/plans/2026-11-03-accueil-tutoriel-aide.md b/docs/plans/2026-11-03-accueil-tutoriel-aide.md deleted file mode 100644 index 2936c62..0000000 --- a/docs/plans/2026-11-03-accueil-tutoriel-aide.md +++ /dev/null @@ -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/`, `#/tutoriel//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//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.