Accueil, tutoriel des règles, aide en questions, installation et mise à jour (0e.5) #44

2026-11-09T17:32:00Z

pierre commented

2026-11-09 17:32:00 +00:00

Pourquoi

Le 2026-11-03, Pierre a demandé :

une page d'accueil ;
un tutoriel des règles « TRÈS DIDACTIQUE », avec de belles visualisations du plateau ;
une aide plus « humaine » ;
l'installation en un toucher.

Le 2026-11-09, il a ajouté un moyen de forcer la mise à jour de l'app.

Jusqu'ici :

L'app s'ouvrait directement sur une partie, et un débutant n'avait aucune explication des règles.
L'aide affichait les fichiers Gherkin bruts, étapes comprises.
L'installation dépendait du menu du navigateur.
Le service worker appelait skipWaiting() dès l'installation et effaçait l'ancien cache. Une page déjà ouverte pouvait alors ne plus trouver ses fichiers, et le joueur ne pouvait pas demander de mise à jour.

Les règles des écrans viennent de la session design (docs/identite/charte/accueil-tutoriel-aide.md). Le plan docs/plans/2026-11-03-accueil-tutoriel-aide.md est supprimé dans cette MR.

Cette branche est construite au-dessus de la MR !43 (adresses des écrans), à fusionner avant elle.

Quoi

Accueil. Lancée sans adresse, l'app s'ouvre sur l'accueil (#/accueil).
- Au premier lancement, elle propose « Je découvre » ou « Je connais les règles ».
- Ensuite, l'accueil montre la partie en cours, l'invitation à installer, les règles et la progression.
Tutoriel. Huit étapes sur le vrai plateau. Les coups illustrés se jouent seuls. Quatre écrans « à vous » font jouer le geste, et GNU Backgammon vérifie le coup : sur un refus, le pion revient avec une explication, sans le mot « erreur ».
Aide. Elle est organisée en questions repliables, avec trois onglets :
- « Jouer » ;
- « Les mots du jeu », avec une recherche ;
- « À propos », qui donne la version publiée.
Le bouton Aide de la partie ouvre la question qui correspond au moment du jeu.
Installation. Sous Chrome, elle passe par l'invite du navigateur ; sous Firefox et sur iPhone, par une marche à suivre en trois étapes. La carte d'installation n'apparaît qu'après la première partie terminée.
Mise à jour. Une nouvelle version publiée attend l'accord du joueur : un bandeau « Nouvelle version disponible » propose « Mettre à jour », et la partie reprend après la mise à jour. Le menu propose aussi « Rechercher une mise à jour ».
Nouvelles adresses, ajoutées à l'ADR 0013 par un amendement :
- #/tutoriel/<n>, #/tutoriel/<n>/a-vous et #/tutoriel/fin ;
- #/installer.

Comment

Le travail a été délégué à un sous-agent.

Tutoriel.
- Le texte vit dans une source unique, docs/tutoriel/regles.md, sous CC BY-SA 4.0, copiée par make site (ADR 0008). Les positions y sont données par leurs identifiants gnubg.
- domain/learning/tutorial.ts fait jouer chaque écran « à vous » comme une partie d'un seul jet, jamais enregistrée. Le coup est juste s'il mène à la position de l'un des coups attendus. Pour le videau, la bonne réponse est celle du moteur (cubeDecision). Aucune règle n'est écrite dans le code.
- app/tests/tutorial.test.ts vérifie chaque position avec le vrai moteur, puis joue tous les coups légaux de chaque écran « à vous » : seuls les coups attendus doivent être acceptés.
Aide. Les scénarios sont lus avec leur étiquette @position:. Un test vérifie que les questions ouvertes depuis la partie existent bien dans les .feature.
Mise à jour. Le service worker ne prend la main qu'au message skip-waiting, puis la page recharge au controllerchange. Le test navigateur publie une seconde version du site et vérifie le bandeau, la mise à jour, la partie retrouvée et le nouveau numéro de version.
Fonctions pures. Elles sont testées sous Node : home-model.ts, tutorial-nav.ts, settings.ts et install.ts.

Vérification :

make lint : aucun problème ;
make test : 10/10, dont 32 scénarios Cucumber ;
make test-browser : Chromium et Firefox, avec un nouveau parcours accueil.mjs ;
60 captures pour la recette design.

Choix et compromis

#/ reste la partie, et l'accueil ne s'ouvre qu'au lancement : les liens existants ne changent pas.
Les écrans « à vous » sont jugés sur la position d'arrivée : un même coup saisi dans un autre ordre est accepté.
Dans l'écran du videau, les boutons s'appellent « Je prends » et « Je passe », pour ne pas être confondus avec le lien « Passer » du tutoriel.
Le test qui interdit les boîtes natives accepte event.prompt(), l'invite d'installation de Chrome. confirm, alert et prompt restent interdits.
Les leçons et la progression détaillée attendent les sous-étapes 1g et 1h : l'accueil n'affiche que ce qui existe.
La mise à jour et l'invite d'installation ne sont testées que dans Chromium : le service worker n'est pas simulable dans Firefox sous Playwright.

Risques et déploiement

Textes à valider par Pierre : le tutoriel (docs/tutoriel/regles.md), les questions de l'aide (docs/scenarios/*.feature), les textes de l'accueil et de l'installation (app/src/ui/home-texts.ts) et la fiche docs/glossaire/camp.md.
Étape 7 du tutoriel : en partie libre, la règle de Jacoby est active, donc un gammon vaut 1 point tant que le videau n'a pas été doublé. Une phrase l'ajoute au texte de la charte ; elle est à valider.
Bascule du service worker : cette version s'installe encore sans demander, parce que l'ancien service worker active lui-même la nouvelle version. Le bandeau n'apparaîtra qu'à la publication suivante.
Adresses de l'aide : les titres des scénarios ont changé, donc les adresses des questions aussi. Aucune n'avait circulé.
Retour arrière : annuler la fusion. Les nouveaux champs des réglages sont ignorés par l'ancienne version.

Comment vérifier

make lint && make test && make test-browser
ls build/browser-shots/accueil-tutoriel/

Sur le téléphone, après publication :

Ouvrir le site : l'écran de premier lancement s'affiche.
Toucher « Je découvre » et suivre les 8 étapes, en jouant un mauvais coup puis le bon sur chaque écran « à vous ».
Ouvrir #/aide, puis #/glossaire et chercher « sortir », puis #/a-propos pour voir la version.
Finir une partie : la carte « Installer » apparaît sur l'accueil.
À la publication suivante : le bandeau « Nouvelle version disponible » apparaît, puis « Mettre à jour » ramène à la partie.

Hors périmètre

Les leçons (1g) et la progression détaillée (1h).
Le conseil du maître (1d).
La taille des numéros des flèches du plateau du tutoriel en paysage, à vérifier en recette design.

Generated with Claude Code https://claude.com/claude-code

## Pourquoi Le 2026-11-03, Pierre a demandé : - une page d'accueil ; - un tutoriel des règles « TRÈS DIDACTIQUE », avec de belles visualisations du plateau ; - une aide plus « humaine » ; - l'installation en un toucher. Le 2026-11-09, il a ajouté un moyen de forcer la mise à jour de l'app. Jusqu'ici : - L'app s'ouvrait directement sur une partie, et un débutant n'avait aucune explication des règles. - L'aide affichait les fichiers Gherkin bruts, étapes comprises. - L'installation dépendait du menu du navigateur. - Le service worker appelait `skipWaiting()` dès l'installation et effaçait l'ancien cache. Une page déjà ouverte pouvait alors ne plus trouver ses fichiers, et le joueur ne pouvait pas demander de mise à jour. Les règles des écrans viennent de la session design (`docs/identite/charte/accueil-tutoriel-aide.md`). Le plan `docs/plans/2026-11-03-accueil-tutoriel-aide.md` est supprimé dans cette MR. Cette branche est construite au-dessus de la MR !43 (adresses des écrans), à fusionner avant elle. ## Quoi - **Accueil.** Lancée sans adresse, l'app s'ouvre sur l'accueil (`#/accueil`). - Au premier lancement, elle propose « Je découvre » ou « Je connais les règles ». - Ensuite, l'accueil montre la partie en cours, l'invitation à installer, les règles et la progression. - **Tutoriel.** Huit étapes sur le vrai plateau. Les coups illustrés se jouent seuls. Quatre écrans « à vous » font jouer le geste, et GNU Backgammon vérifie le coup : sur un refus, le pion revient avec une explication, sans le mot « erreur ». - **Aide.** Elle est organisée en questions repliables, avec trois onglets : - « Jouer » ; - « Les mots du jeu », avec une recherche ; - « À propos », qui donne la version publiée. Le bouton Aide de la partie ouvre la question qui correspond au moment du jeu. - **Installation.** Sous Chrome, elle passe par l'invite du navigateur ; sous Firefox et sur iPhone, par une marche à suivre en trois étapes. La carte d'installation n'apparaît qu'après la première partie terminée. - **Mise à jour.** Une nouvelle version publiée attend l'accord du joueur : un bandeau « Nouvelle version disponible » propose « Mettre à jour », et la partie reprend après la mise à jour. Le menu propose aussi « Rechercher une mise à jour ». - **Nouvelles adresses**, ajoutées à l'ADR 0013 par un amendement : - `#/tutoriel/<n>`, `#/tutoriel/<n>/a-vous` et `#/tutoriel/fin` ; - `#/installer`. ## Comment Le travail a été délégué à un sous-agent. - **Tutoriel.** - Le texte vit dans une source unique, `docs/tutoriel/regles.md`, sous CC BY-SA 4.0, copiée par `make site` (ADR 0008). Les positions y sont données par leurs identifiants gnubg. - `domain/learning/tutorial.ts` fait jouer chaque écran « à vous » comme une partie d'un seul jet, jamais enregistrée. Le coup est juste s'il mène à la position de l'un des coups attendus. Pour le videau, la bonne réponse est celle du moteur (`cubeDecision`). Aucune règle n'est écrite dans le code. - `app/tests/tutorial.test.ts` vérifie chaque position avec le vrai moteur, puis joue tous les coups légaux de chaque écran « à vous » : seuls les coups attendus doivent être acceptés. - **Aide.** Les scénarios sont lus avec leur étiquette `@position:`. Un test vérifie que les questions ouvertes depuis la partie existent bien dans les `.feature`. - **Mise à jour.** Le service worker ne prend la main qu'au message `skip-waiting`, puis la page recharge au `controllerchange`. Le test navigateur publie une seconde version du site et vérifie le bandeau, la mise à jour, la partie retrouvée et le nouveau numéro de version. - **Fonctions pures.** Elles sont testées sous Node : `home-model.ts`, `tutorial-nav.ts`, `settings.ts` et `install.ts`. Vérification : - `make lint` : aucun problème ; - `make test` : 10/10, dont 32 scénarios Cucumber ; - `make test-browser` : Chromium et Firefox, avec un nouveau parcours `accueil.mjs` ; - 60 captures pour la recette design. ## Choix et compromis - **`#/` reste la partie**, et l'accueil ne s'ouvre qu'au lancement : les liens existants ne changent pas. - **Les écrans « à vous » sont jugés sur la position d'arrivée** : un même coup saisi dans un autre ordre est accepté. - **Dans l'écran du videau**, les boutons s'appellent « Je prends » et « Je passe », pour ne pas être confondus avec le lien « Passer » du tutoriel. - **Le test qui interdit les boîtes natives accepte `event.prompt()`**, l'invite d'installation de Chrome. `confirm`, `alert` et `prompt` restent interdits. - **Les leçons et la progression détaillée** attendent les sous-étapes 1g et 1h : l'accueil n'affiche que ce qui existe. - **La mise à jour et l'invite d'installation ne sont testées que dans Chromium** : le service worker n'est pas simulable dans Firefox sous Playwright. ## Risques et déploiement - **Textes à valider par Pierre** : le tutoriel (`docs/tutoriel/regles.md`), les questions de l'aide (`docs/scenarios/*.feature`), les textes de l'accueil et de l'installation (`app/src/ui/home-texts.ts`) et la fiche `docs/glossaire/camp.md`. - **Étape 7 du tutoriel** : en partie libre, la règle de Jacoby est active, donc un gammon vaut 1 point tant que le videau n'a pas été doublé. Une phrase l'ajoute au texte de la charte ; elle est à valider. - **Bascule du service worker** : cette version s'installe encore sans demander, parce que l'ancien service worker active lui-même la nouvelle version. Le bandeau n'apparaîtra qu'à la publication suivante. - **Adresses de l'aide** : les titres des scénarios ont changé, donc les adresses des questions aussi. Aucune n'avait circulé. - **Retour arrière** : annuler la fusion. Les nouveaux champs des réglages sont ignorés par l'ancienne version. ## Comment vérifier ``` make lint && make test && make test-browser ls build/browser-shots/accueil-tutoriel/ ``` Sur le téléphone, après publication : 1. Ouvrir le site : l'écran de premier lancement s'affiche. 2. Toucher « Je découvre » et suivre les 8 étapes, en jouant un mauvais coup puis le bon sur chaque écran « à vous ». 3. Ouvrir `#/aide`, puis `#/glossaire` et chercher « sortir », puis `#/a-propos` pour voir la version. 4. Finir une partie : la carte « Installer » apparaît sur l'accueil. 5. À la publication suivante : le bandeau « Nouvelle version disponible » apparaît, puis « Mettre à jour » ramène à la partie. ## Hors périmètre - Les leçons (1g) et la progression détaillée (1h). - Le conseil du maître (1d). - La taille des numéros des flèches du plateau du tutoriel en paysage, à vérifier en recette design. Generated with Claude Code https://claude.com/claude-code

pierre added 14 commits 2026-11-09 17:32:01 +00:00

Domaine : lire et écrire le lien d'une position (ADR 0013) 43031d1ec6

Le moteur écrit et décode le Match ID ; readPosition valide un lien,
linkOf donne celui d'une partie, setupOf la partie à jouer depuis la
position. Scénario « Partager une position », fiche « Lien de position ».

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Une adresse pour chaque écran, de vrais liens pour y aller f4914b30ab

Routeur pur (fragment vers écran et inversement) et navigation sur
hashchange : aide et ses questions, glossaire et ses termes, à propos,
menu, mes parties et chaque partie, vue d'une position avec « Jouer à
partir d'ici » et « Retour à ma partie », « Copier le lien de la
position ».

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Navigation : un retour en cours retient l'adresse suivante ; test des adresses 97a098e98f

history.go est asynchrone : une adresse demandée pendant un retour attend
son arrivée. Le test dans le navigateur ouvre chaque adresse du tableau de
l'ADR 0013 dans un nouvel onglet, vérifie le retour, le rôle link des liens
et l'aller-retour d'un lien de position, et range ses captures dans
browser-shots/adresses/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Fin de partie : la vibration attend la fin de l'animation du dernier coup 9a5a0bb677

Le dessin lancé au début de l'animation annonçait la fin ; une prise de
l'ordinateur pendant ce dernier coup vibrait ensuite et la remplaçait (vu
dans Firefox par make test-browser).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Test navigateur : le coup joué a 10 s pour arriver dans IndexedDB 2f1d36413e

L'application enregistre sans attendre ; sur le disque dur de la machine
de développement, l'écriture de Firefox peut suivre de loin. En cas
d'échec, le message dit ce que montre l'écran.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Plan 0e.4 : résultat d26033b7bb

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Fusion de main dans adresses-ecrans f74b03fa0d

Adresses des écrans : plan clos d1db2b33c8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Merge remote-tracking branch 'origin/adresses-ecrans' into accueil-tutoriel-aide f1c589eff1

Tutoriel : texte source, lecture, vérification par le moteur, adresses 3f5b00133d

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Accueil, tutoriel, aide en questions, installation et mise à jour de l'application 441bca1bd7

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Tests navigateur : accueil, tutoriel, aide, installation, mise à jour ; plan : résultat 5fdca812d9

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Lint : formatage, ShellCheck sur le nettoyage du second site 8fd1ba3f4f

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Accueil, tutoriel, aide : plan clos ; adresses ajoutées à l'ADR 0013 71bff4def1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

pierre added 3 commits 2026-11-09 23:10:17 +00:00

Fusion de main (MR !43 ) dans accueil-tutoriel-aide d1e234bb11

Conflits résolus en gardant les deux apports : barre de l'aide collée
(scroll-margin sur la carte du terme) et position partagée en paysage.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Tutoriel : étape 7 réécrite, « Prendre », « Passer » et « Quitter » 7c10c688c3

Texte de l'étape 7 remplacé par la version de la recette design (gammon,
backgammon et règle de Jacoby en un paragraphe), légende du plateau
gardée. Le texte du tutoriel est validé par Pierre (9 novembre 2026).
Scénario : les réponses au double sont « Prendre » et « Passer », le lien
du haut est « Quitter ».

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Recette design : tutoriel en paysage, sens du jeu, bandeau de mise à jour 86c0ebfc36

- Sens du jeu (étape 2) : le tracé passe sous les pions et sous les
  numéros des flèches ; liseré ivoire de 8 px, points de 4 px à l'écran.
- Tutoriel en paysage : plateau à gauche sur toute la hauteur (géométrie
  du jeu en paysage, colonne gauche du cadre), colonne à droite avec la
  barre de progression, le titre, le texte, la consigne et les boutons ;
  seul le texte peut défiler. Tient en 915x412 et 844x320.
- Recette automatique étendue au tutoriel : numéros d'au moins 12 px,
  page sans défilement et boutons en vue en paysage, captures en 844x320.
- Boutons du videau « Prendre » et « Passer », lien « Quitter ».
- Bandeau « Nouvelle version prête. » en bas, au-dessus de la barre
  d'actions, seulement entre deux tours (betweenTurns, testé).
- Test des adresses : le lien Aide est lu au moment du toucher, la carte
  du terme ouvert est mesurée sous la barre de l'aide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

pierre referenced this issue from a commit

2026-11-09 23:14:14 +00:00

Fusion de la MR !44 : accueil, tutoriel des règles, aide en questions, installation et mise à jour (0e.5)

pierre manually merged commit dd18a0cc21 into main

2026-11-09 23:14:15 +00:00

pierre referenced this issue from a commit

2026-11-09 23:30:00 +00:00

Fusion d'origin/main (MR !44) ; 1c faite, plan clos

pierre referenced this pull request

2026-11-09 23:30:47 +00:00

Match, niveaux et réglages : écran Nouvelle partie, Crawford, Jacoby (1c) #49

Sign in to join this conversation.