Compare commits

...
Author SHA1 Message Date
pierre ed6d0a7140 Merge pull request 'Charte des leçons : écarts de la recette 1g' (#62) from charte-lecons-quitter into main 2026-11-12 12:40:48 +00:00
Pierre MARTINandClaude Opus 5.5 217c40a245 Charte des leçons : « Quitter », leçon terminée, actions en bas, « Revoir » sur la ligne du titre
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 13:34:18 +01:00
Pierre MARTINandClaude Opus 5.5 cfb2e485c3 Fusion de la MR !60 : niveau d'évaluation du prompt, tests instables
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:33:00 +01:00
Pierre MARTINandClaude Opus 5.5 ac0e924e4c Test navigateur : fermer le bilan rouvert avant l'aide ; plan des corrections clos
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:14:13 +01:00
Pierre MARTIN ceed97e359 Fusion de main dans corrections-plis-firefox 2026-11-12 09:09:54 +01:00
Pierre MARTINandClaude Opus 5.5 109655537f Fusion de la MR !58 : retours des premiers joueurs, pions blancs et noirs, numéros sur le cadre, flèches du tutoriel, jans
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:05:49 +01:00
Pierre MARTINandClaude Opus 5.5 a238da77ec Contour des pions blancs plus sombre en thème clair ; recette des pions du joueur
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:05:45 +01:00
Pierre MARTINandClaude Opus 5.5 9f0f20896b Fusion de main (contour des pions blancs, règle de recette des pions du joueur) dans retours-joueurs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 03:42:20 +01:00
pierre 32f5270215 Fusion de la MR !59 : contour des pions blancs 2026-11-12 02:41:51 +00:00
Pierre MARTINandClaude Opus 5.5 3fff880db2 Charte : contour des pions blancs plus sombre en thème clair (3:1 sur le chêne)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 03:41:49 +01:00
Pierre MARTINandClaude Opus 5.5 282a3d688b Test navigateur : zones du plateau relevées d'un coup, sans boîte nulle
touchTarget mesurait chaque zone par boundingBox ; une zone remplacée
entre-temps par un nouveau dessin du plateau n'avait plus de boîte (null,
vu sous Firefox). Les zones sont relevées dans la page en une lecture, et
le test attend qu'elles soient toutes là.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 03:38:35 +01:00
Pierre MARTINandClaude Opus 5.5 57eeb19630 Plan des retours des premiers joueurs clos : résultat dans la description de la MR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 03:34:40 +01:00
Pierre MARTINandClaude Opus 5.5 5a13c40bbb Recette des retours : capture après le bandeau, capture si le bouton reste caché
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:54:27 +01:00
Pierre MARTINandClaude Opus 5.5 8c2043aca5 Recette : contraste du contour des pions, retours des joueurs dans le navigateur
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:50:10 +01:00
Pierre MARTINandClaude Opus 5.5 966822084a Tutoriel : deux flèches circulaires ; les jans remplacent le camp
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:50:10 +01:00
Pierre MARTINandClaude Opus 5.5 09a2ddf566 Numéros des flèches sur le cadre en portrait aussi
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:50:10 +01:00
Pierre MARTINandClaude Opus 5.5 cfdbc1cedc Pions blancs et noirs, avec contour : valeurs de tokens.json dans app.css
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:50:10 +01:00
Pierre MARTINandClaude Opus 5.5 cb42052c80 Test navigateur : attendre l'enregistrement de la nouvelle partie
Sous Firefox, sur disque lent, l'enregistrement de la nouvelle partie
attend dans la file derrière l'analyse de la partie finie ; le test lisait
IndexedDB trop tôt. Il attend désormais que la partie en cours change.
Test unitaire : rien n'est perdu avec un stockage lent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:47:38 +01:00
Pierre MARTINandClaude Opus 5.5 99294900a0 Prompt d'un coup : le classement de l'analyse, au niveau calculé
Le classement du conseil vient de l'analyse du coup joué (conseils en
version 2) : mêmes équités que la feuille du maître et l'analyse. Le
titre dit le niveau du meilleur coup ; une ligne plus basse le dit aussi.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:47:38 +01:00
Pierre MARTINandClaude Opus 5.5 1d21ac15d2 Moteur : classement de l'analyse d'un coup, comme gnubg de bureau
engine_analyse_move rend les dix premiers coups de la liste de l'analyse,
chacun au niveau où gnubg l'a évalué, et refait d'abord l'analyse de la
chance comme AnalyzeMove : son cache change les coups restés à 0 pli.
Les références d'analyse gagnent le niveau de chaque coup du classement,
comparé par compare.py.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:47:38 +01:00
Pierre MARTINandClaude Opus 5.5 c42316d9d8 Plan des corrections : plis du prompt d'un coup, test Firefox instable
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 02:31:25 +01:00
Pierre MARTINandClaude Opus 5.5 0e17334f45 Plan : retours des premiers joueurs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 23:12:22 +01:00
Pierre MARTINandClaude Opus 5.5 1f69635c49 Fusion de la MR !57 : nouvelle partie directe après un bilan, bouton Commencer, fiche Notation des coups
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 23:02:48 +01:00
Pierre MARTINandClaude Opus 5.5 fb161789bf Liens de notation : pointillé discret, zone d'appui agrandie
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:41:42 +01:00
Pierre MARTINandClaude Opus 5.5 e20f215030 Fusion de main (1f, prompts à copier) dans nouvelle-partie-directe
Conflits résolus en gardant les deux apports : la feuille du prompt et la
correction de reviewFinishedGame dans app.ts ; prompts et nouvelle-partie
dans tests/browser.sh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:41:42 +01:00
Pierre MARTINandClaude Opus 5.5 abff843519 Plan de la nouvelle partie directe clos : résultat dans la description de la MR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:39:47 +01:00
Pierre MARTINandClaude Opus 5.5 05bd06c946 Fusion de la MR !56 : demander à une IA, prompts à copier (1f)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:28:40 +01:00
Pierre MARTINandClaude Opus 5.5 4050517904 Glossaire : fiche « Notation des coups », touchable depuis la partie
La fiche explique 13/7, 24/22*, 6/off, bar/22 et 8/4(2), dans la notation
de gnubg. Le type MoveNotation la relie au code. Le coup de la ligne
« L'ordinateur a joué » et celui de la feuille du maître mènent à la fiche.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:15:09 +01:00
Pierre MARTINandClaude Opus 5.5 05d2479bd3 Écran « Nouvelle partie » : « Commencer la partie » ou « Commencer le match »
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:15:09 +01:00
Pierre MARTINandClaude Opus 5.5 5da3baecde Nouvelle partie : plus de retour au bilan de l'ancienne partie
Le passage différé au bilan (reviewFinishedGame) ne vérifiait pas que la
partie finie était encore à l'écran : « Commencer » redessinait d'abord
l'ancienne partie finie (adresse #/), puis lançait la nouvelle, et la
microtâche ouvrait le bilan de l'ancienne par-dessus. Le bilan ne s'ouvre
plus que pour la partie finie encore affichée, et « Commencer » lance la
partie avant de changer d'adresse.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:15:09 +01:00
pierre 65ee563794 Fusion de la MR !55 : pions blancs et noirs 2026-11-11 21:14:56 +00:00
Pierre MARTINandClaude Opus 5.5 145c19ac77 Identité : pions blancs et noirs avec contour (ADR 0010 amendé, choix de Pierre)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:14:54 +01:00
Pierre MARTINandClaude Opus 5.5 0bb41524bf Test navigateur : nouvelle partie après une partie finie et son bilan
Reproduit le défaut signalé : après une partie finie, l'application
rouverte, « Commencer » de l'écran « Nouvelle partie » ramenait au bilan
de l'ancienne partie. Vérifie l'accueil, le menu et « Changer les réglages ».

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:14:46 +01:00
pierre 6a1ee6f65a Fusion de la MR !54 : retours des premiers joueurs 2026-11-11 21:00:44 +00:00
Pierre MARTINandClaude Opus 5.5 22e415bb81 Charte : retours des premiers joueurs (pions sombres lisibles, numéros sur le cadre, jans, flèches circulaires)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:00:42 +01:00
Pierre MARTIN 850d860658 Merge remote-tracking branch 'origin/main' into prompts 2026-11-11 21:54:32 +01:00
Pierre MARTINandClaude Opus 5.5 d5f08fe393 Demander à une IA : une seule feuille à la fois, la copie confirmée sur le bouton
Recette de 1f (F1, F2). Depuis la feuille du maître ou le bilan, la page
du prompt prend la place de leur contenu, à la même hauteur, avec
« ‹ Explication » ou « ‹ Bilan » pour revenir ; depuis l'analyse et le
glossaire, elle monte dans sa propre feuille. La croix et « Fermer »
ferment la feuille. Plus de bandeau « Prompt copié » : le bouton passe à
« ✓ Copié » (verdict-good) 2 s. Test navigateur : une poignée, une croix,
un titre, même hauteur, retour du téléphone, couleur du bouton. Charte et
amendement de l'ADR 0013 mis à jour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 21:54:32 +01:00
Pierre MARTINandClaude Opus 5.5 62ecff245f Plan : nouvelle partie directe, libellé « Commencer », notation des coups
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 21:54:18 +01:00
Pierre MARTINandClaude Opus 5.5 21baddcea3 Fusion de la MR !53 : corrections, saisie de la sortie, largeur du tutoriel, notation du coup de l'ordinateur
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 21:53:20 +01:00
Pierre MARTINandClaude Opus 5.5 7a6c0ac2ac Aide : texte de « Sortir ses pions dans l'ordre de son choix » choisi par Pierre
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 21:53:14 +01:00
Pierre MARTINandClaude Opus 5.5 f2df1b2e7f Prompts : le niveau du joueur seulement à partir de 20 décisions, son taux d'erreur dans le seul bilan
Recette de 1f (F3). En dessous de 20 décisions analysées, le prompt dit
« Je débute au backgammon. ». Test du seuil ; outil prompt-sample pour
relire des prompts remplis par le moteur. Plan de 1f clos.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 21:52:23 +01:00
Pierre MARTINandClaude Opus 5.5 f509f8746e Test navigateur des prompts : captures sans bandeau résiduel, repli par sélection vérifié
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 21:04:08 +01:00
Pierre MARTINandClaude Opus 5.5 2a1fe1b04c « Demander à une IA » : bouton, feuille du prompt à son adresse, copie
Le bouton, secondaire, dans la feuille du maître, sur le bilan, dans
l'analyse et sur la fiche ouverte du glossaire. Il ouvre la feuille du
prompt (…/ia, amendement de l'ADR 0013), où le texte se relit avant la
copie : navigator.clipboard, repli par sélection du texte, bandeau
« Prompt copié » (2 s). Gabarits copiés par make site (amendement de
l'ADR 0008), scénario « Demander à une IA », 1f marquée faite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 20:56:56 +01:00
Pierre MARTINandClaude Opus 5.5 4f0611c24c Prompts : gabarits dans docs/prompts/ et remplissage par le domaine
Cinq gabarits sous CC BY-SA 4.0 (coup, videau, bilan, concept,
exercices), remplis par des fonctions pures de domain/prompts/ avec la
position lue par le moteur (identifiants, lien public, diagramme) et ses
chiffres, écrits comme à l'écran (domain/analysis/numbers.ts, partagé avec
la feuille du maître, le bilan et l'analyse). Testés sur de vraies
analyses : aucun repère vide ni inconnu, mêmes chiffres que l'écran.
Fiche du glossaire « Prompt ».

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 20:40:07 +01:00
Pierre MARTINandClaude Opus 5.5 90f835869a Plan des corrections clos : résultat dans la description de la MR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 20:24:22 +01:00
Pierre MARTINandClaude Opus 5.5 ce36d738fb Saisie : plus de demi-coup demandé une fois tous les dés joués
Après un double complet, la saisie restée ouverte demandait au moteur un
cinquième demi-coup, que la ligne de commande refuse (erreur dans la page,
relevée par make test-browser). Test : un moteur qui refuse plus de
demi-coups que de dés.

Coup de l'ordinateur : la recette du navigateur vérifie la ligne
« L'ordinateur a joué … » au premier coup montré.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 20:05:14 +01:00
Pierre MARTINandClaude Opus 5.5 fbf317909a Scénario de sortie : mise en forme Biome
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 19:44:36 +01:00
Pierre MARTINandClaude Opus 5.5 b2263c7e3d Tutoriel : même largeur à chaque étape ; règle ajoutée à la recette
Les pages sont des éléments de la colonne flexible #screen ; leurs marges
automatiques annulaient l'étirement, et une page au contenu court se
réduisait à la largeur de ce contenu : l'étape 6 « à vous » (consigne
courte, pas d'explication) avait un plateau de 300 px au lieu de 396 en
412 × 915. Les pages prennent toute la largeur, bornée par max-width.
La recette mesure le plateau et le texte à chaque écran du tutoriel, dans
les trois tailles, et refuse un plateau de largeur différente ou une page
plus large que l'écran (mesures dans tutoriel-largeurs.txt).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 19:42:41 +01:00
Pierre MARTINandClaude Opus 5.5 4e74bab3ac Écran de jeu : le coup de l'ordinateur dans la notation du moteur
« L'ordinateur a joué 6-4 : 6/off » au lieu de « 6/2 2/off » : la
notation vient du coup légal de gnubg qui mène à la même position
(Game.moveNotation), comme dans l'analyse et le bilan. Testé : sur une
partie analysée, chaque coup s'écrit pareil des deux côtés.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 19:37:46 +01:00
Pierre MARTINandClaude Opus 5.5 ab8dc512ba Sortie : un coup déjà complet peut encore se prolonger (6/off puis 1/off avec 6-1)
La partie fermait la saisie dès que les demi-coups formaient un coup
légal. En sortie, 6/off seul mène à la même position que 6/5/off : le
1/off qui suivait était refusé. La saisie reste ouverte tant que le
moteur accepte un demi-coup de plus ; le tutoriel suit la même règle.
Tests : tous les ordres de saisie des fins de partie d'un à quatre pions,
sur les 21 jets, scénario Gherkin et tests du moteur pour les deux ordres.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 19:36:15 +01:00
Pierre MARTINandClaude Opus 5.5 e9bb9ae88d Plan des corrections : sortie, largeur du tutoriel, notation de l'ordinateur
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 16:12:29 +01:00
Pierre MARTINandClaude Opus 5.5 f3f977bf66 Fusion de la MR !52 : bilan de fin de partie et écran d'analyse (1e)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 16:03:43 +01:00
Pierre MARTINandClaude Opus 5.5 9f72b6212f Bilan : ne se redessine que si ce qu'il montre change ; le test attend son mini-plateau
Les analyses de l'ordinateur et les chances de gagner, rangées en
arrière-plan pour l'écran d'analyse, redessinaient tout le bilan, et son
mini-plateau disparaissait le temps d'être redessiné.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 16:03:01 +01:00
Pierre MARTINandClaude Opus 5.5 f2417097f9 Bilan : l'état prêt s'efface quand il se ferme ; le test du match attend le bilan visible
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 15:07:54 +01:00
Pierre MARTINandClaude Opus 5.5 663ef35b51 Recette 1e : titre du bilan sur l'issue, notation du moteur partout, boutons de 48 px en paysage, filtre en accent-soft, longue partie ; tests navigateur adaptés au bilan
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 14:37:44 +01:00
Pierre MARTINandClaude Opus 5.5 ced004edb0 1e faite : scénario ajusté (l'ordinateur double, vous passez), plan clos
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 10:41:35 +01:00
Pierre MARTINandClaude Opus 5.5 4d6f8cfc2e ADR 0007 et 0013 amendés : analyse de partie dans le journal, adresses du bilan et de l'analyse
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 10:30:17 +01:00
Pierre MARTINandClaude Opus 5.5 2c5ae08f46 Bilan et analyse : scénario, fiches du glossaire, test dans le navigateur
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 10:30:17 +01:00
Pierre MARTINandClaude Opus 5.5 006fd62704 Bilan de fin de partie et écran d'analyse : courbe des chances, visualiseur, liste filtrable, rejouer d'ici
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 10:30:17 +01:00
Pierre MARTINandClaude Opus 5.5 a657d7d7a9 Analyse de partie : tours, chance, taux d'erreur à la manière de gnubg, format durable
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 09:56:48 +01:00
Pierre MARTINandClaude Opus 5.5 3e7b161933 Fusion de la MR !51 : conseil du maître, une ligne après chaque coup, l'explication sur demande (1d)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 09:32:34 +01:00
pierre ff3871d86f Fusion de la MR !50 : charte 1d, rang du coup 2026-11-10 04:39:36 +00:00
Pierre MARTINandClaude Opus 5.5 02467d32e0 Charte 1d : rang du coup seulement pour un coup proche ou une imprécision ; pastille en paysage
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 05:39:34 +01:00
128 changed files with 10596 additions and 604 deletions
+4 -3
View File
@@ -127,8 +127,9 @@ SITE_ICONS := icone.svg icone-192.png icone-512.png icone-maskable-192.png icone
# docs/identite/logo/ (une seule source, ADR 0010) ;
# - l'application compilée (build/web/src/) sous app/ ;
# - le moteur sous wasm/ ;
# - les copies du glossaire, des scénarios, du tutoriel et des phrases du
# maître sous docs/, lues par l'aide, le tutoriel et le conseil du maître
# - les copies du glossaire, des scénarios, du tutoriel, des phrases du
# maître et des prompts pour une IA sous docs/, lues par l'aide, le
# tutoriel, le conseil du maître et « Demander à une IA »
# (ADR 0008 : jamais commitées
# ailleurs) ;
# - version.json (commit publié) ;
@@ -142,7 +143,7 @@ site: engine-wasm web ## Assemble le site publié dans build/site/
cp -r $(BUILD_DIR)/web/src $(BUILD_DIR)/site/app
cp $(BUILD_DIR)/wasm/engine.mjs $(BUILD_DIR)/wasm/engine.wasm $(BUILD_DIR)/wasm/engine.data \
$(BUILD_DIR)/wasm/positions.json $(BUILD_DIR)/site/wasm/
cp -r docs/glossaire docs/scenarios docs/tutoriel docs/maitre $(BUILD_DIR)/site/docs/
cp -r docs/glossaire docs/scenarios docs/tutoriel docs/maitre docs/prompts $(BUILD_DIR)/site/docs/
printf '{"commit": "%s", "dirty": %s}\n' "$$(git rev-parse HEAD)" \
"$$(git diff --quiet HEAD && echo false || echo true)" > $(BUILD_DIR)/site/version.json
scripts/service-worker.sh $(BUILD_DIR)/site
+37 -14
View File
@@ -14,6 +14,7 @@ import { ADVICE_VERSION, type Advice, type AdvisedMove, type MoveFacts } from ".
import type { BoardSide, CubeAction, Engine, EvaluatedMove, Ply } from "../game/engine.js";
import { currentLine, type GameEvent, type GameJournal } from "../game/events.js";
import { engineCube, STANDARD_PLY } from "../game/game.js";
import { otherSide, type Side } from "../game/side.js";
import { replay } from "../game/state.js";
/** Niveau de l'analyse : 2 plis, comme l'analyse de partie de gnubg par
@@ -30,35 +31,55 @@ export const RANKING_SIZE = 5;
* avant), ses doubles et ses réponses aux doubles de l'ordinateur.
*/
export function playerDecisions(events: readonly GameEvent[]): GameEvent[] {
return decisionsOf(events, "player");
}
/** Les décisions de side parmi des événements, comme playerDecisions. */
export function decisionsOf(events: readonly GameEvent[], side: Side): GameEvent[] {
return events.filter((event) => {
switch (event.type) {
case "MovePlayed":
return event.side === "player" && event.halfMoves.length > 0;
return event.side === side && event.halfMoves.length > 0;
case "DiceRolled":
case "CubeOffered":
case "CubeTaken":
case "CubeDropped":
return event.side === "player";
return event.side === side;
default:
return false;
}
});
}
/** Ce qu'on demande à l'analyse d'une décision. */
export interface DecisionOptions {
/** Niveau de l'analyse ; ANALYSIS_PLY par défaut. */
readonly ply?: Ply;
/** Le camp qui décide ; le joueur par défaut. Le conseil est alors vu
* de ce camp (sa position, ses coups). */
readonly side?: Side;
/** Garder le classement des coups (une seconde analyse) ; oui par
* défaut. L'analyse des coups de l'ordinateur s'en passe. */
readonly ranking?: boolean;
}
/**
* Le conseil du moteur sur la décision du joueur eventId, au niveau ply ;
* null s'il n'y a rien à analyser (pas une décision du joueur, aucun coup
* possible, videau inaccessible ou position de départ pour gnubg).
* Le conseil du moteur sur la décision eventId du joueur (ou du camp
* options.side) ; null s'il n'y a rien à analyser (pas une décision de ce
* camp, aucun coup possible, videau inaccessible ou position de départ pour
* gnubg).
*/
export async function analyseDecision(
engine: Engine,
journal: GameJournal,
eventId: string,
ply: Ply = ANALYSIS_PLY,
options: DecisionOptions = {},
): Promise<Advice | null> {
const ply = options.ply ?? ANALYSIS_PLY;
const side = options.side ?? "player";
const line = currentLine({ ...journal, head: eventId });
const event = line.at(-1);
if (event === undefined || playerDecisions([event]).length === 0) {
if (event === undefined || decisionsOf([event], side).length === 0) {
return null;
}
const earlier = line.slice(0, -1);
@@ -67,10 +88,10 @@ export async function analyseDecision(
if (before.roll === null) {
return null;
}
const cube = engineCube(before, "player");
// Le coup joué est enregistré vu de l'ordinateur : le moteur donne la
// même position vue du joueur.
const after = await engine.board(event.position, engineCube(before, "computer"));
const cube = engineCube(before, side);
// Le coup joué est enregistré vu de l'adversaire : le moteur donne
// la même position vue de celui qui l'a joué.
const after = await engine.board(event.position, engineCube(before, otherSide(side)));
const analysis = await engine.analyseMove(
before.position,
cube,
@@ -81,7 +102,9 @@ export async function analyseDecision(
if (analysis === null) {
return null;
}
const ranking = await engine.rankMoves(before.position, cube, before.roll, ply);
// Le classement est celui de l'analyse même : mêmes coups, mêmes
// niveaux et mêmes équités que le coup joué et le meilleur coup.
const ranking = options.ranking === false ? [] : analysis.ranking;
const start = await engine.board(before.position, cube);
const facts = async (move: EvaluatedMove) =>
factsOf(start.onRoll, start.opponent, await engine.board(move.position, cube));
@@ -105,7 +128,7 @@ export async function analyseDecision(
};
}
let action: CubeAction;
let decider: "player" | "computer" = "player";
let decider: Side = side;
if (event.type === "DiceRolled") {
if (before.phase !== "rolling") {
return null;
@@ -115,7 +138,7 @@ export async function analyseDecision(
action = "double";
} else {
action = event.type === "CubeTaken" ? "take" : "pass";
decider = "computer";
decider = otherSide(side);
}
const analysis = await engine.analyseCube(
before.position,
+579
View File
@@ -0,0 +1,579 @@
// L'analyse d'une partie (étape 1e) : ce qui manque à analyser, le calcul
// de chaque analyse par le moteur, et les chiffres du bilan à la manière de
// GNU Backgammon (taux d'erreur, chance, résultat corrigé de la chance).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// Tout ce qui juge le jeu vient du moteur : l'analyse de chaque décision
// (équité perdue, appréciation), la chance de chaque jet, l'évaluation des
// positions. Ce module ne fait que les ranger et les additionner, comme le
// fait gnubg dans ses statistiques de partie. Sources, dans gnubg 1.08.003
// (commit 14b67984, ADR 0005), fichiers analysis.c et formatgs.c :
// - updateStatcontext (analysis.c, l. 304-596) : les erreurs de chaque
// décision et leur nombre ;
// - getMWCFromError (analysis.c, l. 1432-1472) : le taux d'erreur ;
// - GetRating et arThrsRating (analysis.c, l. 83-101) : le classement ;
// - formatgs.c, l. 348-374 et getLuckRating (analysis.c, l. 1757) : la
// chance par coup et son appréciation ;
// - arLuckAdj (analysis.c, l. 304-330 et 405-414) : le résultat corrigé de
// la chance.
// Les tâches d'analyse sont indépendantes : l'application les lance une à
// une sur le second moteur, en arrière-plan, et peut s'arrêter entre deux.
import {
type Advice,
type CubeAdvice,
type MoveAdvice,
type Verdict,
verdictOf,
} from "../game/advice.js";
import type { Engine, LuckRating } from "../game/engine.js";
import { LUCK_THRESHOLDS } from "../game/engine.js";
import {
currentLine,
type GameEnded,
type GameEvent,
type GameJournal,
type MovePlayed,
withAdvice,
withReview,
} from "../game/events.js";
import { engineCube } from "../game/game.js";
import { COMPUTER_LEVELS, type ComputerLevel } from "../game/level.js";
import { emptyReview, type GameReview } from "../game/review.js";
import type { Roll } from "../game/roll.js";
import type { Side } from "../game/side.js";
import { applyEvent, replay } from "../game/state.js";
import { ANALYSIS_PLY, analyseDecision, decisionsOf } from "./analyse.js";
// ------------------------------------------------------------ Les tours
/**
* Un tour de la partie : ce qu'un camp a fait quand il avait la main
* (doubler ou non, lancer, jouer), avec la réponse de l'adversaire à son
* double. Les tours sont numérotés à partir de 1 ; c'est le « coup » de
* l'écran d'analyse (#/parties/<id>/analyse/<n>).
*/
export interface Turn {
readonly number: number;
/** Le camp qui avait la main. */
readonly side: Side;
/** Le jet joué (null : le tour s'est fini sur un double passé). */
readonly roll: Roll | null;
/** Le coup joué (null : double passé). */
readonly move: MovePlayed | null;
/** Les événements du tour, dans l'ordre (sans la fin de partie). */
readonly events: readonly GameEvent[];
/** La fin de partie, si elle suit ce tour. */
readonly end: GameEnded | null;
}
/** Les tours d'une ligne de jeu (événements du début à la fin). */
export function turnsOf(line: readonly GameEvent[]): Turn[] {
const turns: Turn[] = [];
let bucket: GameEvent[] = [];
let state = replay([]);
for (const event of line) {
const before = state;
state = applyEvent(state, event);
if (event.type === "GameStarted") {
continue;
}
if (event.type === "GameEnded") {
const last = turns.at(-1);
if (bucket.length === 0 && last !== undefined) {
turns[turns.length - 1] = { ...last, end: event };
} else if (bucket.length > 0) {
const offer = bucket.find((e) => e.type === "CubeOffered");
const side = offer?.type === "CubeOffered" ? offer.side : (before.turn ?? "player");
turns.push(makeTurn(turns.length + 1, side, bucket, null, event));
}
bucket = [];
continue;
}
bucket.push(event);
if (event.type === "MovePlayed") {
turns.push(makeTurn(turns.length + 1, event.side, bucket, event, null));
bucket = [];
}
}
return turns;
}
function makeTurn(
number: number,
side: Side,
events: readonly GameEvent[],
move: MovePlayed | null,
end: GameEnded | null,
): Turn {
const rolled = move === null ? undefined : events.findLast((e) => e.type === "DiceRolled");
return {
number,
side,
roll: rolled?.type === "DiceRolled" ? rolled.roll : null,
move,
events,
end,
};
}
/** Les tours de la ligne courante d'un journal. */
export function gameTurns(journal: GameJournal): Turn[] {
return turnsOf(currentLine(journal));
}
// --------------------------------------------- Ce qui reste à analyser
/** Une analyse à demander au moteur. */
export type AnalysisTask =
/** Une décision (coup ou videau) d'un camp. */
| { readonly kind: "decision"; readonly side: Side; readonly eventId: string }
/** La chance d'un jet. */
| { readonly kind: "luck"; readonly eventId: string }
/** Les chances de gagner du joueur après un coup. */
| { readonly kind: "chance"; readonly eventId: string };
/** L'analyse de partie du journal, au niveau d'analyse ; vide s'il n'y en
* a pas encore (ou à un autre niveau). */
export function reviewOf(journal: GameJournal): GameReview {
const review = journal.review;
return review !== undefined && review.ply === ANALYSIS_PLY ? review : emptyReview(ANALYSIS_PLY);
}
/**
* Ce qui reste à analyser sur la ligne courante, dans l'ordre où le bilan
* en a besoin : les décisions du joueur (celles d'avant l'étape 1d, ou
* dont l'analyse est arrivée trop tard), la chance de chaque jet, puis,
* pour l'écran d'analyse, les décisions de l'ordinateur et les chances de
* gagner après chaque coup.
*/
export function missingAnalyses(journal: GameJournal): AnalysisTask[] {
const line = currentLine(journal);
const review = reviewOf(journal);
const skipped = new Set(review.unanalysed);
const advice = journal.advice ?? {};
const tasks: AnalysisTask[] = [];
for (const event of decisionsOf(line, "player")) {
if (advice[event.id] === undefined && !skipped.has(event.id)) {
tasks.push({ kind: "decision", side: "player", eventId: event.id });
}
}
for (const event of luckyRolls(line)) {
if (review.luck[event.id] === undefined) {
tasks.push({ kind: "luck", eventId: event.id });
}
}
for (const event of decisionsOf(line, "computer")) {
if (review.computer[event.id] === undefined && !skipped.has(event.id)) {
tasks.push({ kind: "decision", side: "computer", eventId: event.id });
}
}
for (const event of line) {
if (event.type === "MovePlayed" && review.winChances[event.id] === undefined) {
tasks.push({ kind: "chance", eventId: event.id });
}
}
return tasks;
}
/** Ce qu'il faut au bilan : toutes les décisions du joueur et la chance
* de tous les jets. */
export function readyForSummary(journal: GameJournal): boolean {
return missingAnalyses(journal).every(
(task) => task.kind === "chance" || (task.kind === "decision" && task.side === "computer"),
);
}
/** Les jets qui ont une chance : tous ceux d'un camp, et le jet
* d'ouverture qui désigne le premier joueur (pas une égalité, qui se
* relance). */
function luckyRolls(line: readonly GameEvent[]): GameEvent[] {
const rolls: GameEvent[] = [];
let state = replay([]);
for (const event of line) {
const before = state;
state = applyEvent(state, event);
if (event.type !== "DiceRolled") {
continue;
}
if (event.side !== null || (before.phase === "opening" && state.phase === "moving")) {
rolls.push(event);
}
}
return rolls;
}
/**
* Fait une analyse avec le moteur et la range dans le journal, qui est
* renvoyé (le journal reçu ne change pas). Une décision que le moteur
* n'analyse pas est notée comme telle, pour ne plus la demander.
*/
export async function runAnalysis(
engine: Engine,
journal: GameJournal,
task: AnalysisTask,
): Promise<GameJournal> {
const review = reviewOf(journal);
switch (task.kind) {
case "decision": {
const advice = await analyseDecision(engine, journal, task.eventId, {
side: task.side,
ranking: task.side === "player",
});
if (advice === null) {
return withReview(journal, {
...review,
unanalysed: [...review.unanalysed, task.eventId],
});
}
return task.side === "player"
? withAdvice(journal, advice)
: withReview(journal, {
...review,
computer: { ...review.computer, [task.eventId]: advice },
});
}
case "luck": {
const line = currentLine({ ...journal, head: task.eventId });
const event = line.at(-1);
if (event?.type !== "DiceRolled") {
throw new Error(`pas un jet : ${task.eventId}`);
}
const before = replay(line.slice(0, -1));
// Le camp qui joue le jet ; au jet d'ouverture, celui qu'il
// désigne. La position de départ est la même pour les deux.
const roller = event.side ?? replay(line).turn ?? "player";
const luck = await engine.luck(before.position, engineCube(before, roller), event.roll);
return withReview(journal, { ...review, luck: { ...review.luck, [event.id]: luck } });
}
case "chance": {
const chance = await chanceAfter(engine, journal, task.eventId);
return withReview(journal, {
...review,
winChances: { ...review.winChances, [task.eventId]: chance },
});
}
}
}
/** Les chances de gagner du joueur après le coup moveId : le résultat si
* la partie finit là, sinon l'évaluation du moteur, vue de celui qui a
* alors la main. */
async function chanceAfter(engine: Engine, journal: GameJournal, moveId: string): Promise<number> {
const line = currentLine(journal);
const index = line.findIndex((e) => e.id === moveId);
const upTo = index >= 0 ? line.slice(0, index + 1) : currentLine({ ...journal, head: moveId });
const next = index >= 0 ? line[index + 1] : undefined;
if (next?.type === "GameEnded") {
return next.winner === "player" ? 1 : 0;
}
const after = replay(upTo);
const onRoll = after.turn ?? "player";
const evaluation = await engine.evaluate(
after.position,
engineCube(after, onRoll),
ANALYSIS_PLY,
);
return onRoll === "player" ? evaluation.win : 1 - evaluation.win;
}
// ------------------------------------------------ Les chiffres du bilan
/**
* Classement de gnubg selon le taux d'erreur par décision (GetRating et
* arThrsRating, analysis.c l. 83-101) : en dessous de 0,005, « Super
* Grandmaster » ; puis 0,008 « Grandmaster », 0,013 « Master », 0,020
* « Advanced », 0,032 « Intermediate », au-delà « Beginner ». Les six
* classements portent les noms des six niveaux de l'ordinateur, dans le
* même ordre (correspondance dans docs/glossaire/taux-d-erreur.md).
*/
export const RATING_THRESHOLDS: readonly number[] = [0.032, 0.02, 0.013, 0.008, 0.005];
/**
* Le taux d'erreur d'un camp, à la manière de gnubg (getMWCFromError,
* analysis.c) : l'équité perdue sur toutes ses décisions, divisée par le
* nombre de coups non forcés et de décisions de videau « serrées ».
*
* Glossaire : docs/glossaire/taux-d-erreur.md
*/
export interface ErrorRate {
/** Équité perdue au total, pour un videau de 1 (positive ou nulle). */
readonly total: number;
/** Nombre de décisions comptées. */
readonly decisions: number;
/** Équité perdue par décision (0 sans décision). */
readonly perDecision: number;
/** Le niveau correspondant, du nom des niveaux de l'ordinateur. */
readonly level: ComputerLevel;
}
/** La chance d'un camp sur la partie, à la manière de gnubg (formatgs.c,
* « Luck total », « Luck rate », « Luck rating »). */
export interface LuckSummary {
/** Somme de la chance de ses jets, pour un videau de 1. */
readonly total: number;
/** Nombre de ses tours avec un jet (anTotalMoves de gnubg). */
readonly rolls: number;
/** Chance par tour (0 sans tour). */
readonly perRoll: number;
/** getLuckRating : la chance par tour, multipliée par 10, comparée aux
* seuils d'un jet (LUCK_THRESHOLDS). */
readonly rating: LuckRating;
/** La chance comptée en points : chaque jet multiplié par la valeur
* du videau à ce moment (arLuck[…][1] de gnubg en partie libre). */
readonly points: number;
}
/** Ce que le bilan dit d'un camp. */
export interface SideSummary {
readonly errorRate: ErrorRate;
readonly luck: LuckSummary;
}
/** Une décision du joueur et son conseil, dans son tour. */
export interface ReviewedDecision {
readonly turn: number;
readonly advice: Advice;
}
/** Le bilan d'une partie (ligne courante). */
export interface GameSummary {
readonly player: SideSummary;
readonly computer: SideSummary;
/** Les décisions du joueur comptées, par appréciation : ses coups, ses
* doubles et ses réponses aux doubles, et ses jets sans doubler
* seulement quand doubler était mieux. */
readonly counts: Readonly<Record<Verdict, number>>;
/** La plus grosse erreur du joueur (null : aucune imprécision ni
* erreur). */
readonly toReview: ReviewedDecision | null;
/** Le résultat de la partie en points pour le joueur (0 si elle n'est
* pas finie), et ce résultat corrigé de la chance des deux camps
* (arLuckAdj de gnubg) : ce qu'il serait sans les dés. */
readonly result: number;
readonly luckAdjustedResult: number;
}
/** Le niveau de gnubg pour un taux d'erreur par décision. */
export function levelOfErrorRate(perDecision: number): ComputerLevel {
let index = 0;
while (index < RATING_THRESHOLDS.length && perDecision < (RATING_THRESHOLDS[index] ?? 0)) {
index++;
}
return COMPUTER_LEVELS[index] ?? "beginner";
}
/** getLuckRating de gnubg : Luck(chance par tour × 10). */
export function luckRatingOf(perRoll: number): LuckRating {
const r = perRoll * 10;
if (r > LUCK_THRESHOLDS.veryLucky) {
return "veryLucky";
}
if (r > LUCK_THRESHOLDS.lucky) {
return "lucky";
}
if (r < -LUCK_THRESHOLDS.veryLucky) {
return "veryUnlucky";
}
if (r < -LUCK_THRESHOLDS.lucky) {
return "unlucky";
}
return "none";
}
/**
* Une décision de videau « serrée » pour gnubg (isCloseCubedecision,
* eval.c l. 5107) : doubler coûte moins de 0,16 par rapport à l'optimum.
* Un jet sans doubler n'est compté dans le taux d'erreur que dans ce cas ;
* un double, une prise ou un refus le sont toujours.
*/
function closeCube(advice: CubeAdvice): boolean {
const e = advice.equities;
return e.optimal - Math.min(e.doubleTake, 1) < 0.16;
}
/** L'erreur d'une décision (équité perdue, positive) et si elle compte
* dans le nombre de décisions (updateStatcontext). */
function errorOf(advice: Advice): { error: number; counted: boolean } {
const error = -Math.min(0, advice.equityLoss);
if (advice.kind === "move") {
// Un coup forcé ne compte pas (anUnforcedMoves).
return { error: advice.moveCount > 1 ? error : 0, counted: advice.moveCount > 1 };
}
return { error, counted: advice.action !== "noDouble" || closeCube(advice) };
}
function errorRateOf(advices: readonly Advice[]): ErrorRate {
let total = 0;
let decisions = 0;
for (const advice of advices) {
const { error, counted } = errorOf(advice);
total += error;
decisions += counted ? 1 : 0;
}
const perDecision = decisions > 0 ? total / decisions : 0;
return { total, decisions, perDecision, level: levelOfErrorRate(perDecision) };
}
/** Le bilan de la ligne courante, avec les analyses déjà faites (les
* manquantes ne comptent pas : voir readyForSummary). */
export function summarizeAnalysis(journal: GameJournal): GameSummary {
const line = currentLine(journal);
const review = reviewOf(journal);
const advice = journal.advice ?? {};
const turns = turnsOf(line);
const turnOf = new Map<string, number>();
for (const turn of turns) {
for (const event of turn.events) {
turnOf.set(event.id, turn.number);
}
}
const decided = (side: Side): Advice[] =>
decisionsOf(line, side)
.map((e) => (side === "player" ? advice[e.id] : review.computer[e.id]))
.filter((a): a is Advice => a !== undefined);
const mine = decided("player");
// La chance de chaque camp, et la valeur du videau à chaque jet.
const luck: Record<Side, { total: number; points: number; rolls: number }> = {
player: { total: 0, points: 0, rolls: 0 },
computer: { total: 0, points: 0, rolls: 0 },
};
let state = replay([]);
for (const event of line) {
const before = state;
state = applyEvent(state, event);
if (event.type === "MovePlayed") {
luck[event.side].rolls++;
}
const value = event.type === "DiceRolled" ? review.luck[event.id] : undefined;
if (value !== undefined && event.type === "DiceRolled") {
const roller = event.side ?? state.turn ?? "player";
luck[roller].total += value.value;
luck[roller].points += value.value * before.cube.value;
}
}
const luckSummary = (side: Side): LuckSummary => {
const { total, points, rolls } = luck[side];
const perRoll = rolls > 0 ? total / rolls : 0;
return { total, rolls, perRoll, rating: luckRatingOf(perRoll), points };
};
const counts: Record<Verdict, number> = { good: 0, doubtful: 0, bad: 0, veryBad: 0 };
let toReview: ReviewedDecision | null = null;
for (const a of mine) {
const verdict = verdictOf(a.skill);
// Un jet sans doubler n'est une décision visible que s'il était
// une faute.
if (!(a.kind === "cube" && a.action === "noDouble" && verdict === "good")) {
counts[verdict]++;
}
if (
verdict !== "good" &&
(toReview === null || a.equityLoss < toReview.advice.equityLoss)
) {
toReview = { turn: turnOf.get(a.eventId) ?? 0, advice: a };
}
}
const ended = line.findLast((e) => e.type === "GameEnded");
const result =
ended?.type === "GameEnded" ? (ended.winner === "player" ? 1 : -1) * ended.points : 0;
const player = luckSummary("player");
const computer = luckSummary("computer");
return {
player: { errorRate: errorRateOf(mine), luck: player },
computer: { errorRate: errorRateOf(decided("computer")), luck: computer },
counts,
toReview,
result,
luckAdjustedResult: result - player.points + computer.points,
};
}
// ------------------------------------------------ Coup par coup
/** Un point de la courbe des chances de gagner : un tour. */
export interface ChancePoint {
readonly turn: number;
readonly side: Side;
/** Chances de gagner du joueur après le tour, de 0 à 1 (null : pas
* encore analysé). */
readonly chance: number | null;
/** L'appréciation de la décision du joueur la plus coûteuse du tour
* (null : aucune décision du joueur analysée). */
readonly verdict: Verdict | null;
}
/**
* La courbe des chances de gagner du joueur, tour après tour : la position
* après chaque coup évaluée par le moteur, et le résultat après le dernier.
*
* Glossaire : docs/glossaire/courbe-des-chances.md
*/
export type WinChanceCurve = readonly ChancePoint[];
/** La décision du joueur à revoir dans un tour : la plus coûteuse, le coup
* à égalité (null : aucune décision du joueur analysée dans ce tour). */
export function mainAdvice(journal: GameJournal, turn: Turn): Advice | null {
const advice = journal.advice ?? {};
let main: Advice | null = null;
for (const event of decisionsOf(turn.events, "player")) {
const a = advice[event.id];
if (a === undefined) {
continue;
}
if (
main === null ||
a.equityLoss < main.equityLoss ||
(a.equityLoss === main.equityLoss && a.kind === "move")
) {
main = a;
}
}
return main;
}
/** Le conseil sur le coup de l'ordinateur d'un tour (null sinon). */
export function computerMoveAdvice(journal: GameJournal, turn: Turn): MoveAdvice | null {
if (turn.side !== "computer" || turn.move === null) {
return null;
}
const advice = reviewOf(journal).computer[turn.move.id];
return advice?.kind === "move" ? advice : null;
}
export function chanceCurve(journal: GameJournal): WinChanceCurve {
const review = reviewOf(journal);
return gameTurns(journal).map((turn) => {
const main = mainAdvice(journal, turn);
let chance: number | null = null;
if (turn.move !== null) {
chance = review.winChances[turn.move.id] ?? null;
}
if (turn.end !== null && (turn.move === null || chance === null)) {
chance = turn.end.winner === "player" ? 1 : 0;
}
return {
turn: turn.number,
side: turn.side,
chance,
verdict: main === null ? null : verdictOf(main.skill),
};
});
}
/**
* « Rejouer d'ici » sur un tour : l'événement où revenir pour rejouer la
* décision à revoir du joueur (juste avant elle : même jet pour un coup,
* même moment pour un videau). null pour un tour sans décision du joueur.
*/
export function replayPoint(journal: GameJournal, turn: Turn): string | null {
const main = mainAdvice(journal, turn);
const decisions = decisionsOf(turn.events, "player");
const event = main === null ? decisions.at(-1) : decisions.find((e) => e.id === main.eventId);
return event?.parent ?? null;
}
+77
View File
@@ -0,0 +1,77 @@
// Les chiffres du moteur tels qu'on les écrit : à l'écran (feuille du
// maître, bilan, analyse) et dans les prompts pour une IA (étape 1f). Une
// seule écriture, pour que le prompt donne exactement les chiffres que
// l'application affiche.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import type { AdvisedMove, MoveAdvice } from "../game/advice.js";
import type { Ply } from "../game/engine.js";
/** Un nombre à la française, signé, à trois décimales : « −0,123 ». */
export function formatEquity(value: number): string {
const text = Math.abs(value).toFixed(3).replace(".", ",");
return value < -0.0005 ? `−${text}` : value > 0.0005 ? `+${text}` : text;
}
/** Des chances de 0 à 1, en pourcentage arrondi, avec une espace
* insécable : « 41 % ». */
export function formatPercent(chance: number): string {
return `${Math.round(chance * 100)} %`;
}
/** Une ligne du classement des coups montré par « Voir les chiffres du
* moteur ». */
export interface RankingRow {
readonly move: AdvisedMove;
/** Rang dans le classement du moteur, à partir de 1. */
readonly rank: number;
/** Écart d'équité avec le premier coup du classement : 0 ou négatif. */
readonly loss: number;
/** C'est le coup joué. */
readonly played: boolean;
}
/**
* Le classement d'un conseil tel que l'affiche la feuille du maître : les
* coups du classement de l'analyse, chacun avec son écart par rapport au
* premier ; puis le coup joué, s'il n'y figure pas. Le coup joué a toujours
* l'écart de l'analyse (equityLoss), celui que dit le maître.
*/
export function rankingRows(advice: MoveAdvice): RankingRow[] {
const first = advice.ranking[0]?.equity ?? advice.best.equity;
const rows = advice.ranking.map((move, i) => {
const played = move.notation === advice.played.notation;
return {
move,
rank: i + 1,
loss: played ? advice.equityLoss : move.equity - first,
played,
};
});
if (!rows.some((row) => row.played)) {
rows.push({
move: advice.played,
rank: advice.rank,
loss: advice.equityLoss,
played: true,
});
}
return rows;
}
/**
* Le niveau du classement d'un conseil : celui auquel le moteur a évalué le
* meilleur coup. C'est le niveau demandé (advice.ply), sauf quand gnubg
* s'arrête avant, parce qu'un seul coup a passé ses filtres : tout le
* classement reste alors au niveau inférieur.
*/
export function rankingPly(advice: MoveAdvice): Ply {
return advice.best.ply;
}
/** « 1 pli », « 2 plis » : gnubg compte les plis à partir de 0. */
export function pliesText(ply: Ply): string {
return `${ply} ${ply > 1 ? "plis" : "pli"}`;
}
+46 -1
View File
@@ -15,7 +15,8 @@ import {
type Verdict,
verdictOf,
} from "../game/advice.js";
import type { CubeAction } from "../game/engine.js";
import type { CubeAction, LuckRating } from "../game/engine.js";
import type { GameSummary } from "./game-analysis.js";
/** Les gabarits, par clé de section (« coup.meilleur »…). */
export type MasterPhrases = ReadonlyMap<string, readonly string[]>;
@@ -93,8 +94,52 @@ export const PHRASE_KEYS: readonly string[] = [
"contexte.videau.double",
"contexte.videau.pas-de-double",
"contexte.videau.reponse",
"bilan.jeu.gagne",
"bilan.jeu.perdu",
"bilan.des",
"bilan.des.tres-pour",
"bilan.des.pour",
"bilan.des.neutres",
"bilan.des.contre",
"bilan.des.tres-contre",
"bilan.aucun-coup",
];
const DICE_KEYS: Readonly<Record<LuckRating, string>> = {
veryLucky: "bilan.des.tres-pour",
lucky: "bilan.des.pour",
none: "bilan.des.neutres",
unlucky: "bilan.des.contre",
veryUnlucky: "bilan.des.tres-contre",
};
/** La chance de vos dés sur la partie, en mots : « un peu contre vous »… */
export function diceWords(phrases: MasterPhrases, rating: LuckRating): string {
return pick(phrases, DICE_KEYS[rating], "0");
}
/**
* La lecture du bilan d'une partie finie : ce qui a fait la différence,
* selon le résultat corrigé de la chance (gnubg) ; et vos dés, en mots.
* Partie gagnée : votre jeu, si le résultat corrigé de la chance reste
* positif, sinon les dés ; partie perdue : le jeu de l'ordinateur, si le
* résultat corrigé reste négatif, sinon les dés.
*/
export function summaryReading(phrases: MasterPhrases, summary: GameSummary): string {
const dice = diceWords(phrases, summary.player.luck.rating);
const won = summary.result > 0;
const playDecided = won ? summary.luckAdjustedResult > 0 : summary.luckAdjustedResult < 0;
if (!playDecided) {
return pick(phrases, "bilan.des", "0");
}
return fillIn(pick(phrases, won ? "bilan.jeu.gagne" : "bilan.jeu.perdu", "0"), { dice });
}
/** « Aucun coup à revoir… » : la carte du coup à revoir sans erreur. */
export function nothingToReview(phrases: MasterPhrases): string {
return pick(phrases, "bilan.aucun-coup", "0");
}
/** Ce que le maître dit d'un conseil du moteur. */
export function masterWords(phrases: MasterPhrases, advice: Advice): MasterWords {
return advice.kind === "move" ? moveWords(phrases, advice) : cubeWords(phrases, advice);
+8 -6
View File
@@ -10,13 +10,15 @@
// stockage, dans le journal (events.ts, champ advice). Le format est
// durable (ADR 0007) : chaque conseil porte sa version (ADVICE_VERSION).
import type { CubeAction, CubeEquities, Ply, Skill } from "./engine.js";
import type { CubeAction, CubeEquities, MoveNotation, Ply, Skill } from "./engine.js";
import type { HalfMove, PositionId } from "./position.js";
import type { Roll } from "./roll.js";
/** Version du format d'un conseil enregistré. Un conseil d'une autre
* version est ignoré à la reprise (il peut être recalculé). */
export const ADVICE_VERSION = 1;
* version est ignoré à la reprise (il peut être recalculé). Version 2 : le
* classement des coups vient de l'analyse du coup joué, et non plus d'un
* second classement comme la commande « hint » de gnubg. */
export const ADVICE_VERSION = 2;
/**
* Le conseil du maître sur une décision du joueur : un coup ou une décision
@@ -29,7 +31,7 @@ export type Advice = MoveAdvice | CubeAdvice;
/** Un coup, tel que le conseil le retient. */
export interface AdvisedMove {
/** Notation de gnubg, par exemple « 8/5 6/5 ». */
readonly notation: string;
readonly notation: MoveNotation;
readonly halfMoves: readonly HalfMove[];
/** Équité (avec videau) du point de vue du joueur, et le niveau auquel
* le moteur l'a évaluée. */
@@ -66,8 +68,8 @@ export interface MoveAdvice {
readonly best: AdvisedMove;
readonly playedFacts: MoveFacts;
readonly bestFacts: MoveFacts;
/** Les meilleurs coups du classement du moteur, du meilleur au moins
* bon (cinq au plus). */
/** Les meilleurs coups du classement de l'analyse, du meilleur au
* moins bon (cinq au plus), chacun au niveau où le moteur l'a évalué. */
readonly ranking: readonly AdvisedMove[];
/** Équité du coup joué moins celle du meilleur : 0 ou négative. */
readonly equityLoss: number;
+31 -12
View File
@@ -80,17 +80,6 @@ export interface Engine {
ply: Ply,
): Promise<MoveAnalysis | null>;
/** Les coups légaux d'un jet classés du meilleur au moins bon, au
* niveau ply, comme la commande « hint » de gnubg (les coups écartés
* par ses filtres gardent l'évaluation d'un niveau inférieur, voir leur
* ply). */
rankMoves(
position: PositionId,
cube: EngineCube,
roll: Roll,
ply: Ply,
): Promise<EvaluatedMove[]>;
/** L'analyse d'une décision de videau, position vue du joueur au trait
* (celui qui double ou non ; take et pass sont la réponse de son
* adversaire). */
@@ -104,6 +93,11 @@ export interface Engine {
/** La chance d'un jet pour le joueur au trait. */
luck(position: PositionId, cube: EngineCube, roll: Roll): Promise<Luck>;
/** L'évaluation d'une position, joueur au trait avant de lancer les
* dés, au niveau ply : ses chances de gain (sans videau) et son équité
* avec videau. */
evaluate(position: PositionId, cube: EngineCube, ply: Ply): Promise<Evaluation>;
/** Le Match ID, joueur 0 au trait, avec ce videau et ce match vus de lui
* (partie libre sans match), sans dés. */
encodeMatch(cube: EngineCube): Promise<MatchId>;
@@ -189,6 +183,16 @@ export interface Luck {
readonly rating: LuckRating;
}
/** Une position évaluée par le moteur, du point de vue du joueur au
* trait. */
export interface Evaluation {
/** Chances de gagner la partie, de 0 à 1, sans tenir compte du videau
* (première probabilité de gnubg). */
readonly win: number;
/** Équité avec videau, normalisée pour un videau de 1. */
readonly equity: number;
}
/** Un coup avec son équité (avec videau), du point de vue de celui qui le joue. */
export interface EvaluatedMove extends Move {
readonly equity: number;
@@ -207,6 +211,12 @@ export interface MoveAnalysis {
/** Équité du coup joué moins celle du meilleur : 0 ou négative. */
readonly equityLoss: number;
readonly skill: Skill;
/** Le classement de l'analyse, du meilleur au moins bon (dix coups au
* plus) : la liste de l'analyse de partie de gnubg, chaque coup au
* niveau où gnubg l'a évalué (ply). Les coups écartés par ses filtres
* gardent l'évaluation d'un niveau inférieur ; le meilleur coup et le
* coup joué y ont les évaluations de best et played. */
readonly ranking: readonly EvaluatedMove[];
}
/** Décision de videau : doubler ou non (joueur au trait), prendre ou passer
@@ -266,6 +276,15 @@ export interface EngineMatchAfter {
readonly crawford: boolean;
}
/**
* Un coup écrit dans la notation de gnubg : « 8/5 6/5 », « 24/22* »,
* « 6/off », « bar/22 », « 8/4(2) ». Le moteur l'écrit ; l'application ne
* fait que l'afficher.
*
* Glossaire : docs/glossaire/notation-des-coups.md
*/
export type MoveNotation = string;
/**
* Un coup légal complet.
*
@@ -273,7 +292,7 @@ export interface EngineMatchAfter {
*/
export interface Move {
/** Notation de gnubg, par exemple « 8/5 6/5 ». */
readonly notation: string;
readonly notation: MoveNotation;
/** Ses demi-coups, dans un ordre jouable. */
readonly halfMoves: readonly HalfMove[];
/** La position après le coup, vue du joueur qui vient de jouer. */
+75 -2
View File
@@ -17,6 +17,7 @@ import type { Cube } from "./cube.js";
import type { Level, ResultKind } from "./engine.js";
import type { Match, MatchAfterGame } from "./match.js";
import type { HalfMove, PositionId } from "./position.js";
import { type GameReview, REVIEW_VERSION } from "./review.js";
import type { Roll } from "./roll.js";
import type { Side } from "./side.js";
@@ -40,7 +41,7 @@ const VERSION_1_LEVEL: Level = "2ply";
* version inconnue est laissé tel quel (Game.resume le refuse).
*/
export function migrateJournal(saved: GameJournal): GameJournal {
const journal = keepKnownAdvice(saved);
const journal = keepKnownReview(keepKnownAdvice(saved));
if (journal.events.every((event) => event.version === EVENT_VERSION)) {
return journal;
}
@@ -87,6 +88,56 @@ function keepKnownAdvice(journal: GameJournal): GameJournal {
return { ...journal, advice: Object.fromEntries(kept) };
}
/**
* L'analyse de partie d'un journal enregistré (étape 1e) : oubliée si elle
* est d'une autre version (REVIEW_VERSION) ou mal formée ; sinon, seules
* restent ses entrées rattachées à un événement du journal. Ce n'est
* qu'une analyse du moteur, qui peut être refaite. Un journal sans analyse
* (enregistré avant l'étape 1e) reste tel quel.
*/
function keepKnownReview(journal: GameJournal): GameJournal {
const review = journal.review;
if (review === undefined) {
return journal;
}
const tables = [review.luck, review.winChances, review.computer];
const wellFormed =
typeof review === "object" &&
review !== null &&
review.version === REVIEW_VERSION &&
typeof review.ply === "number" &&
tables.every((table) => typeof table === "object" && table !== null) &&
Array.isArray(review.unanalysed);
if (!wellFormed) {
const { review: _, ...rest } = journal;
return rest;
}
const ids = new Set(journal.events.map((event) => event.id));
const known = <T>(table: Readonly<Record<string, T>>) =>
Object.fromEntries(Object.entries(table).filter(([id]) => ids.has(id)));
const computer = Object.fromEntries(
Object.entries(review.computer).filter(
([id, a]) =>
ids.has(id) &&
typeof a === "object" &&
a !== null &&
a.version === ADVICE_VERSION &&
a.eventId === id,
),
);
const kept: GameReview = {
...review,
luck: known(review.luck),
winChances: known(review.winChances),
computer,
unanalysed: review.unanalysed.filter((id) => ids.has(id)),
};
// Le nombre d'entrées de chaque table : rien d'oublié, rien ne change.
const sizes = (r: GameReview) =>
[r.luck, r.winChances, r.computer, r.unanalysed].map((t) => Object.keys(t).length).join();
return sizes(kept) === sizes(review) ? journal : { ...journal, review: kept };
}
interface EventBase {
/** Identifiant, unique dans la partie. */
readonly id: string;
@@ -182,11 +233,14 @@ type WithoutBase<E> = E extends unknown ? Omit<E, keyof EventBase> : never;
* courant (head) : la partie en est là. advice (étape 1d, facultatif) : le
* conseil du maître sur les décisions du joueur, par identifiant de
* l'événement de la décision. Ce n'est pas un événement : il arrive après
* coup, quand l'analyse du moteur est prête, et ne change pas la partie. */
* coup, quand l'analyse du moteur est prête, et ne change pas la partie.
* review (étape 1e, facultatif) : le reste de l'analyse de la partie (chance
* des jets, chances de gagner, décisions de l'ordinateur), pour le bilan. */
export interface GameJournal {
readonly events: readonly GameEvent[];
readonly head: string | null;
readonly advice?: Readonly<Record<string, Advice>>;
readonly review?: GameReview;
}
export const EMPTY_JOURNAL: GameJournal = { events: [], head: null };
@@ -211,6 +265,25 @@ export function withAdvice(journal: GameJournal, advice: Advice): GameJournal {
return { ...journal, advice: { ...journal.advice, [advice.eventId]: advice } };
}
/** Remplace l'analyse de partie du journal (elle ne change pas la
* partie). */
export function withReview(journal: GameJournal, review: GameReview): GameJournal {
return { ...journal, review };
}
/** Le journal avec les analyses d'une copie de lui-même, faite en
* arrière-plan : ses conseils s'ajoutent, son analyse de partie remplace
* celle du journal. Les événements ne changent pas. */
export function withAnalysesOf(journal: GameJournal, analysed: GameJournal): GameJournal {
const ids = new Set(journal.events.map((event) => event.id));
const advice = Object.entries(analysed.advice ?? {}).filter(([id]) => ids.has(id));
return {
...journal,
advice: { ...Object.fromEntries(advice), ...journal.advice },
...(analysed.review === undefined ? {} : { review: analysed.review }),
};
}
/** Les événements du début jusqu'à l'événement courant, dans l'ordre. */
export function currentLine(journal: GameJournal): GameEvent[] {
const byId = new Map(journal.events.map((event) => [event.id, event]));
+68 -10
View File
@@ -12,7 +12,15 @@
import type { Advice } from "./advice.js";
import { type Branch, branches, switchToBranch } from "./branches.js";
import { CENTERED_CUBE, type Cube } from "./cube.js";
import type { BoardSide, Engine, EngineCube, Level, Ply, ResultKind } from "./engine.js";
import type {
BoardSide,
Engine,
EngineCube,
Level,
MoveNotation,
Ply,
ResultKind,
} from "./engine.js";
import {
appendEvent,
currentLine,
@@ -24,9 +32,17 @@ import {
migrateJournal,
type NewGameEvent,
withAdvice,
withAnalysesOf,
} from "./events.js";
import { firstGameOf, type Match, nextGameOf } from "./match.js";
import { BAR, type HalfMove, OFF, type PositionId, START_POSITION } from "./position.js";
import {
BAR,
formatHalfMoves,
type HalfMove,
OFF,
type PositionId,
START_POSITION,
} from "./position.js";
import { type DiceSource, type Roll, randomDice, rollDice } from "./roll.js";
import { otherSide, type Side } from "./side.js";
import { type GameState, replay } from "./state.js";
@@ -185,8 +201,11 @@ export class Game {
}
/** Les demi-coups saisis forment un coup complet (le moteur le dit) : il
* n'attend plus que d'être validé (confirmMove) ou défait
* (undoLastHalfMove). */
* peut être validé (confirmMove) ou défait (undoLastHalfMove). La saisie
* n'est pas close pour autant : en sortie, un coup complet peut encore
* se prolonger en un autre coup légal (avec 6-1 et des pions sur 6 et 1,
* 6/off seul mène à la même position que 6/5/off, et 1/off reste
* possible) ; nextHalfMoves dit lesquels, selon le moteur. */
get moveComplete(): boolean {
return this.#pending.at(-1)?.complete === true;
}
@@ -272,6 +291,29 @@ export class Game {
return { side, halfMoves, boards, hits };
}
/**
* Le coup joué à l'événement eventId (un MovePlayed), dans la notation
* du moteur : celle du coup légal de gnubg qui mène à la même position
* (« 6/off » et non « 6/5 5/off »), comme dans l'analyse et le bilan.
* À défaut (aucun coup légal ne correspond), les demi-coups ; chaîne
* vide si l'événement n'est pas un coup ou si aucun pion n'a bougé.
*/
async moveNotation(eventId: string): Promise<MoveNotation> {
const line = currentLine({ ...this.#journal, head: eventId });
const event = line.at(-1);
if (event?.type !== "MovePlayed" || event.halfMoves.length === 0) {
return "";
}
const before = replay(line.slice(0, -1));
const roll = rollToPlay(before);
const [check, legal] = await Promise.all([
this.#engine.checkHalfMoves(before.position, roll, event.halfMoves),
this.#engine.legalMoves(before.position, roll),
]);
const move = legal.find((m) => m.position === check.position);
return move?.notation ?? formatHalfMoves(event.halfMoves);
}
/** Les conseils du maître déjà rattachés aux décisions du joueur, par
* identifiant d'événement. */
get advice(): Readonly<Record<string, Advice>> {
@@ -284,16 +326,25 @@ export class Game {
this.#journal = withAdvice(this.#journal, advice);
}
/** Range dans le journal les analyses faites en arrière-plan sur une
* copie de celui-ci (étape 1e : conseils, analyse de partie). */
recordAnalyses(analysed: GameJournal): void {
this.#journal = withAnalysesOf(this.#journal, analysed);
}
/**
* Les demi-coups que le joueur peut saisir maintenant, à la suite de ceux
* déjà saisis (liste vide hors de son tour de jeu). Chaque candidat
* déplace un de ses pions de la valeur d'un dé (vers la sortie si le dé
* dépasse la case 1) ; seuls restent ceux que le moteur déclare menant à
* un coup légal. Aucune règle n'est jugée ici.
* un coup légal. Aucune règle n'est jugée ici : même après un coup
* complet, c'est le moteur qui dit si un dé reste à jouer. Seule
* exception : une fois tous les dés utilisés (diceLeft), rien n'est
* demandé, le moteur n'acceptant pas plus de demi-coups que de dés.
*/
async nextHalfMoves(): Promise<HalfMove[]> {
const state = this.state;
if (state.turn !== "player" || state.phase !== "moving" || this.moveComplete) {
if (state.turn !== "player" || state.phase !== "moving" || !this.#diceLeft(state)) {
return [];
}
const roll = rollToPlay(state);
@@ -363,13 +414,13 @@ export class Game {
/**
* Le joueur déplace un pion (un dé). Renvoie false si ce demi-coup ne
* mène à aucun coup légal (ou si le coup est déjà complet) : il est
* refusé et rien ne change. Le coup n'est pas joué pour autant : une fois
* complet (moveComplete), il attend d'être validé (confirmMove).
* mène à aucun coup légal : il est refusé et rien ne change. Le coup
* n'est pas joué pour autant : une fois complet (moveComplete), il attend
* d'être validé (confirmMove), ou prolongé si le moteur le permet.
*/
async playHalfMove(halfMove: HalfMove): Promise<boolean> {
const state = this.#expect("player", "moving");
if (this.moveComplete) {
if (!this.#diceLeft(state)) {
return false;
}
const check = await this.#engine.checkHalfMoves(state.position, rollToPlay(state), [
@@ -386,6 +437,13 @@ export class Game {
return true;
}
/** Il reste un dé à jouer : moins de demi-coups saisis que de dés
* (quatre pour un double). */
#diceLeft(state: GameState): boolean {
const roll = rollToPlay(state);
return this.#pending.length < (roll[0] === roll[1] ? 4 : 2);
}
/** Défait le dernier demi-coup saisi du coup en cours (rien s'il n'y en a
* pas) : il n'a jamais été dans le journal. */
undoLastHalfMove(): void {
+55
View File
@@ -0,0 +1,55 @@
// L'analyse de la partie par le moteur, rangée dans le journal à côté du
// conseil du maître (étape 1e) : la chance de chaque jet, les chances de
// gagner après chaque coup, et les décisions de l'ordinateur.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// Ce fichier ne contient que des données : tout ce qu'elles disent vient du
// moteur. Le calcul est dans domain/analysis/game-analysis.ts. Comme le
// conseil (advice.ts), ce n'est pas un événement : l'analyse arrive après
// coup et ne change pas la partie. Le format est durable (ADR 0007) : il
// porte sa version (REVIEW_VERSION), et une analyse d'une autre version
// est oubliée à la reprise (elle peut être refaite).
import type { Advice } from "./advice.js";
import type { Luck, Ply } from "./engine.js";
/** Version du format de l'analyse de partie enregistrée. */
export const REVIEW_VERSION = 1;
/**
* L'analyse de la partie, en plus des conseils du maître : de quoi
* calculer le bilan (taux d'erreur, chance) et tracer la courbe des chances
* de gagner. Chaque table est indexée par l'identifiant d'un événement du
* journal ; une table incomplète est complétée en arrière-plan.
*/
export interface GameReview {
readonly version: number;
/** Niveau des analyses et des évaluations, en plis. */
readonly ply: Ply;
/** Pour chaque jet (DiceRolled, ouverture comprise), sa chance pour le
* camp qui le joue, selon le moteur. */
readonly luck: Readonly<Record<string, Luck>>;
/** Pour chaque coup (MovePlayed), les chances de gagner du joueur dans
* la position d'après, de 0 à 1, selon le moteur. */
readonly winChances: Readonly<Record<string, number>>;
/** Les décisions de l'ordinateur, analysées comme celles du joueur (le
* conseil d'un coup de l'ordinateur est vu de lui). */
readonly computer: Readonly<Record<string, Advice>>;
/** Les décisions (des deux camps) que le moteur n'analyse pas : videau
* inaccessible, position de départ. Elles ne sont plus demandées. */
readonly unanalysed: readonly string[];
}
/** Une analyse vide, au niveau ply. */
export function emptyReview(ply: Ply): GameReview {
return {
version: REVIEW_VERSION,
ply,
luck: {},
winChances: {},
computer: {},
unanalysed: [],
};
}
+7 -3
View File
@@ -209,10 +209,14 @@ export class MovePractice {
if (!(await this.#game.playHalfMove(halfMove))) {
return "wrong";
}
if (this.#game.moveComplete) {
const position = this.#game.displayedPosition;
return this.#expected.some((m) => m.position === position) ? "right" : "wrong";
if (
this.#game.moveComplete &&
this.#expected.some((m) => m.position === this.#game.displayedPosition)
) {
return "right";
}
// Un coup complet peut encore se prolonger (en sortie) : il n'est
// refusé que s'il ne peut plus mener à un coup attendu.
return canStillLeadTo(this.#game.pendingHalfMoves, this.#expected) ? "continue" : "wrong";
}
+195
View File
@@ -0,0 +1,195 @@
// La position que décrit un prompt, étape 1f : ses identifiants de GNU
// Backgammon, son plateau décodé par le moteur, le videau et le match ; et
// son diagramme texte.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// Rien n'est décodé ici : le moteur lit la position (board) et écrit le
// Match ID (encodeMatch). Le diagramme ne fait que recopier le plateau
// qu'il a décodé.
import type { Cube } from "../game/cube.js";
import type { Engine, Evaluation, MatchId } from "../game/engine.js";
import { currentLine, type GameJournal } from "../game/events.js";
import { engineCube, type SideBoards } from "../game/game.js";
import type { Match } from "../game/match.js";
import type { PositionId } from "../game/position.js";
import type { Roll } from "../game/roll.js";
import type { Side } from "../game/side.js";
import { type GameState, replay } from "../game/state.js";
/** L'adresse publique de l'application (ADR 0013 : les liens de position
* s'ouvrent sur elle). */
export const PUBLIC_SITE = "https://ustagammon.sans.pub/";
/** Une position telle que la décrit un prompt. */
export interface PromptPosition {
/** Position ID de gnubg, vue du camp au trait. */
readonly positionId: PositionId;
/** Match ID écrit par le moteur, du point de vue du camp au trait, sans
* dés. */
readonly matchId: MatchId;
readonly onRoll: Side;
/** Le plateau décodé par le moteur, chaque camp dans sa numérotation. */
readonly sides: SideBoards;
readonly cube: Cube;
/** null en partie libre. */
readonly match: Match | null;
/** Le jet à jouer, s'il est déjà tiré. */
readonly roll: Roll | null;
}
/** La position d'avant l'événement eventId du journal (la décision qu'on
* commente), lue par le moteur. */
export async function positionBefore(
engine: Engine,
journal: GameJournal,
eventId: string,
): Promise<PromptPosition> {
const line = currentLine({ ...journal, head: eventId });
return positionOf(engine, replay(line.slice(0, -1)));
}
/** La position actuelle d'une partie, ou la position de départ sans
* partie, lue par le moteur. */
export async function positionNow(
engine: Engine,
journal: GameJournal | null,
): Promise<PromptPosition> {
return positionOf(engine, replay(journal === null ? [] : currentLine(journal)));
}
async function positionOf(engine: Engine, state: GameState): Promise<PromptPosition> {
// Pendant le jet d'ouverture, la position de départ, vue du joueur.
const onRoll = state.turn ?? "player";
const cube = engineCube(state, onRoll);
const [board, matchId] = await Promise.all([
engine.board(state.position, cube),
engine.encodeMatch(cube),
]);
const sides =
onRoll === "player"
? { player: board.onRoll, computer: board.opponent }
: { player: board.opponent, computer: board.onRoll };
return {
positionId: state.position,
matchId,
onRoll,
sides,
cube: state.cube,
match: state.match,
roll: state.phase === "moving" ? state.roll : null,
};
}
/** L'évaluation par le moteur d'une position, pour le camp au trait avant
* de lancer les dés. */
export function evaluatePosition(
engine: Engine,
position: PromptPosition,
ply: number,
): Promise<Evaluation> {
const cube = engineCube({ cube: position.cube, match: position.match }, position.onRoll);
return engine.evaluate(position.positionId, cube, ply);
}
/** L'adresse publique de la position (#/position/<Position ID>/<Match ID>,
* ADR 0013, identifiants encodés avec encodeURIComponent). */
export function positionAddress(position: PromptPosition): string {
const id = encodeURIComponent(position.positionId);
return `${PUBLIC_SITE}#/position/${id}/${encodeURIComponent(position.matchId)}`;
}
/** Nombre de lignes de pions dessinées par moitié du plateau ; au-delà, la
* dernière ligne porte le nombre de pions. */
const ROWS = 5;
/**
* Le diagramme texte d'une position, vu du joueur : ses pions X, ceux de
* l'ordinateur O, dans la numérotation du joueur (sa case 1 est la plus
* proche de sa sortie, en bas à droite). Sous le dessin, la liste des pions
* case par case, la barre, les pions sortis et les comptes de points, tels
* que le moteur les donne.
*/
export function boardDiagram(sides: SideBoards): string {
// La case p du joueur est la case 25 - p de l'ordinateur.
const at = (point: number): { mark: string; count: number } => {
const mine = sides.player.points[point - 1] ?? 0;
const theirs = sides.computer.points[24 - point] ?? 0;
if (mine > 0) {
return { mark: "X", count: mine };
}
return theirs > 0 ? { mark: "O", count: theirs } : { mark: ".", count: 0 };
};
const cell = (text: string) => text.padStart(3, " ");
const half = (points: readonly number[]) =>
`${points.slice(0, 6).map(String).map(cell).join("")} |${points.slice(6).map(String).map(cell).join("")}`;
const row = (points: readonly number[], level: number) => {
const cells = points.map((p) => {
const { mark, count } = at(p);
if (count < level) {
return level === 1 ? cell(".") : cell("");
}
return cell(level === ROWS && count > ROWS ? String(count) : mark);
});
return `${cells.slice(0, 6).join("")} |${cells.slice(6).join("")}`.trimEnd();
};
const top = [13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24];
const bottom = [12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1];
const lines = [half(top)];
for (let level = 1; level <= ROWS; level++) {
lines.push(row(top, level));
}
lines.push("");
for (let level = ROWS; level >= 1; level--) {
lines.push(row(bottom, level));
}
lines.push(half(bottom));
const list = (mark: "X" | "O") => {
const parts: string[] = [];
for (let point = 24; point >= 1; point--) {
const here = at(point);
if (here.mark === mark) {
parts.push(`${point} (${here.count})`);
}
}
return parts.length === 0 ? "aucun" : parts.join(", ");
};
return [
"```",
...lines,
"```",
"X : mes pions ; O : ceux de l'ordinateur. Les cases sont numérotées de mon point de vue : je joue de la case 24 vers la case 1, mon jan intérieur est en bas à droite (cases 1 à 6).",
`Mes pions (X), case (nombre) : ${list("X")}.`,
`Pions de l'ordinateur (O), dans ma numérotation : ${list("O")}.`,
`Sur la barre : moi ${sides.player.bar}, l'ordinateur ${sides.computer.bar}. Sortis : moi ${sides.player.off}, l'ordinateur ${sides.computer.off}.`,
`Compte de points : moi ${sides.player.pipCount}, l'ordinateur ${sides.computer.pipCount}.`,
].join("\n");
}
/** Le camp, à la première personne du joueur : « moi », « l'ordinateur ». */
export function sideName(side: Side): string {
return side === "player" ? "moi" : "l'ordinateur";
}
/** Le score : « partie libre » ou celui du match. */
export function scoreText(position: Pick<PromptPosition, "match">): string {
const match = position.match;
if (match === null) {
return "partie libre, sans match (règle Jacoby)";
}
const crawford = match.crawford ? ", partie Crawford" : "";
return `match en ${match.length} points, moi ${match.score.player}, l'ordinateur ${match.score.computer}${crawford}`;
}
/** Le videau : sa valeur et qui le possède. */
export function cubeText(position: Pick<PromptPosition, "cube" | "match">): string {
if (position.match?.crawford === true) {
return "aucun (partie Crawford : personne ne peut doubler)";
}
const { value, owner } = position.cube;
const where = owner === null ? "au centre" : owner === "player" ? "à moi" : "à l'ordinateur";
return `${value}, ${where}`;
}
+489
View File
@@ -0,0 +1,489 @@
// Les prompts pour une IA (étape 1f ; cadrage, « IA générative en V1 ») :
// chaque gabarit de docs/prompts/ rempli avec la position, décodée par le
// moteur, et les chiffres du moteur, écrits comme l'application les
// affiche. Le moteur décide, l'IA explique : le prompt lui demande de ne
// pas contredire ces chiffres.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// Les fonctions qui remplissent (decisionPrompt, summaryPrompt,
// conceptPrompt, exercisesPrompt) sont pures : elles reçoivent les
// analyses du moteur et la position déjà lue. Les fonctions asynchrones
// (summaryPosition, conceptExample, exercisesPosition) ne font que demander
// au moteur la position à décrire.
import {
type ErrorRate,
gameTurns,
levelOfErrorRate,
type ReviewedDecision,
summarizeAnalysis,
} from "../analysis/game-analysis.js";
import {
formatEquity,
formatPercent,
pliesText,
rankingPly,
rankingRows,
} from "../analysis/numbers.js";
import { diceWords, type MasterPhrases, masterWords } from "../analysis/phrases.js";
import {
type Advice,
type CubeAdvice,
type MoveAdvice,
masterCubeAction,
verdictOf,
} from "../game/advice.js";
import type { CubeAction, Engine, Evaluation, Ply } from "../game/engine.js";
import { currentLine, type GameJournal } from "../game/events.js";
import { type ComputerLevel, computerLevelOf } from "../game/level.js";
import { replay } from "../game/state.js";
import {
boardDiagram,
cubeText,
evaluatePosition,
type PromptPosition,
positionAddress,
positionBefore,
positionNow,
scoreText,
sideName,
} from "./position.js";
import { fillPrompt, type Prompt, type PromptTemplates } from "./templates.js";
/** La langue des réponses demandées à l'IA. */
export const PROMPT_LANGUAGE = "français";
/** Les noms des niveaux, les mêmes que l'écran « Nouvelle partie » et le
* bilan (vérifié par app/tests/prompts.test.ts). */
export const LEVEL_NAMES: Readonly<Record<ComputerLevel, string>> = {
beginner: "Débutant",
amateur: "Amateur",
intermediate: "Intermédiaire",
advanced: "Avancé",
expert: "Expert",
champion: "Champion",
};
/** Les décisions de videau, comme le bilan les nomme. */
export const CUBE_ACTION_WORDS: Readonly<Record<CubeAction, string>> = {
double: "doubler",
noDouble: "lancer sans doubler",
take: "prendre",
pass: "passer",
};
/** Les lignes des équités de videau, comme « Voir les chiffres du
* moteur ». */
export const CUBE_ROW_WORDS = {
noDouble: "Pas de double",
doubleTake: "Double, prend",
doublePass: "Double, passe",
} as const;
/** Les erreurs citées au plus dans un prompt : bilan, exercices. */
const MAX_ERRORS = 8;
const plural = (n: number, one: string, many: string) => `${n} ${n > 1 ? many : one}`;
/** « analyse à 2 plis ». */
export function plyText(ply: Ply): string {
return `analyse à ${pliesText(ply)}`;
}
/** Nombre de décisions analysées à partir duquel le niveau du joueur se
* dit dans un prompt : en dessous, l'erreur par décision dit peu de chose. */
export const LEVEL_MIN_DECISIONS = 20;
/** Ce que le joueur dit de lui-même dans un prompt : son niveau, d'après
* son erreur par décision mesurée par GNU Backgammon, s'il est mesuré sur
* au moins LEVEL_MIN_DECISIONS décisions ; sinon, qu'il débute (pas encore
* d'historique des parties : étape 1h). Jamais le taux lui-même, qui n'est
* que dans le bilan. */
export function playerSentence(rate: Pick<ErrorRate, "decisions" | "level"> | null): string {
if (rate === null || rate.decisions < LEVEL_MIN_DECISIONS) {
return "Je débute au backgammon.";
}
return `Je suis un joueur de niveau ${LEVEL_NAMES[rate.level]}.`;
}
/** playerSentence, sur les décisions d'une partie. */
function playerOf(journal: GameJournal | null): string {
return playerSentence(journal === null ? null : summarizeAnalysis(journal).player.errorRate);
}
/** Les repères de la position, communs à tous les gabarits. */
function positionValues(position: PromptPosition): Record<string, string> {
return {
position_id: position.positionId,
match_id: position.matchId,
au_trait: sideName(position.onRoll),
lien: positionAddress(position),
diagramme: boardDiagram(position.sides),
score: scoreText(position),
videau: cubeText(position),
langue: PROMPT_LANGUAGE,
};
}
// ------------------------------------------------------ Une décision
/** Ce que demande le prompt d'une décision du joueur. */
export interface DecisionPromptData {
/** La partie : le niveau du joueur se lit sur ses décisions. */
readonly journal: GameJournal;
/** Le conseil du moteur sur la décision. */
readonly advice: Advice;
/** La position d'avant la décision (positionBefore). */
readonly position: PromptPosition;
}
/** Le prompt « Pourquoi ce coup est meilleur » ou « Expliquer cette
* décision de videau ». */
export function decisionPrompt(
templates: PromptTemplates,
phrases: MasterPhrases,
data: DecisionPromptData,
): Prompt {
const common = {
...positionValues(data.position),
joueur: playerOf(data.journal),
niveau_eval: plyText(data.advice.ply),
appreciation: masterWords(phrases, data.advice).word,
};
// Le niveau d'un classement de coups : celui de son meilleur coup, que
// le moteur a pu évaluer moins profondément que demandé.
return data.advice.kind === "move"
? fillPrompt(templates.move, {
...common,
niveau_eval: plyText(rankingPly(data.advice)),
...moveValues(data.advice),
})
: fillPrompt(templates.cube, { ...common, ...cubeValues(data.advice) });
}
function moveValues(advice: MoveAdvice): Record<string, string> {
const count = plural(advice.moveCount, "coup possible", "coups possibles");
const rank =
advice.moveCount <= 1
? "le seul coup possible"
: advice.rank === 1
? `le meilleur des ${count}`
: `le ${advice.rank}e choix sur ${count}`;
// Les trois meilleurs coups, et le vôtre s'il n'en est pas : les lignes
// de « Voir les chiffres du moteur », avec les mêmes chiffres.
const rows = rankingRows(advice).filter((row) => row.rank <= 3 || row.played);
const ranking = rows.map((row) => {
// Un coup écarté par les filtres du moteur garde l'évaluation d'un
// niveau inférieur à celui du classement : la ligne le dit.
const ply =
row.move.ply === rankingPly(advice) ? "" : `, évalué à ${pliesText(row.move.ply)}`;
const mine = row.played ? " (mon coup)" : "";
return `${row.rank}. ${row.move.notation}${mine} : équité ${formatEquity(row.move.equity)}, écart ${formatEquity(row.loss)}${ply}`;
});
return {
des: `${advice.roll[0]}-${advice.roll[1]}`,
coup_joue: advice.played.notation,
rang: rank,
classement: ranking.join("\n"),
};
}
function cubeValues(advice: CubeAdvice): Record<string, string> {
const answering = advice.action === "take" || advice.action === "pass";
// Les lignes de votre décision : doubler mène à l'une des deux lignes
// « Double », selon la réponse de l'ordinateur (comme la feuille).
const mine = {
noDouble: ["noDouble"],
double: ["doubleTake", "doublePass"],
take: ["doubleTake"],
pass: ["doublePass"],
}[advice.action];
const rows = (["noDouble", "doubleTake", "doublePass"] as const).map((key) => {
const note = mine.length === 1 && mine.includes(key) ? " (ma décision)" : "";
return `- ${CUBE_ROW_WORDS[key]}${note} : ${formatEquity(advice.equities[key])}`;
});
return {
decision: answering
? "prendre ou passer le double de l'ordinateur"
: "doubler ou lancer les dés sans doubler",
choix: CUBE_ACTION_WORDS[advice.action],
choix_moteur: CUBE_ACTION_WORDS[masterCubeAction(advice)],
qui_double: answering ? "l'ordinateur" : "moi",
equites: rows.join("\n"),
ecart: formatEquity(advice.equityLoss),
};
}
// ------------------------------------------------------------ Le bilan
/** Une imprécision ou une erreur du joueur, dans son tour. */
interface Mistake {
readonly turn: number;
readonly advice: Advice;
/** Le jet du tour, « 6-1 » (vide pour un tour sans jet). */
readonly roll: string;
}
/** Les imprécisions et erreurs du joueur sur la ligne courante, dans
* l'ordre de la partie. */
function mistakesOf(journal: GameJournal): Mistake[] {
const advice = journal.advice ?? {};
const mistakes: Mistake[] = [];
for (const turn of gameTurns(journal)) {
for (const event of turn.events) {
const a = advice[event.id];
if (a !== undefined && verdictOf(a.skill) !== "good") {
const roll = turn.roll === null ? "" : `${turn.roll[0]}-${turn.roll[1]}`;
mistakes.push({ turn: turn.number, advice: a, roll });
}
}
}
return mistakes;
}
/** Une ligne de la liste des erreurs : ce qui a été joué, ce que le moteur
* préférait, l'écart et le mot du maître. */
function mistakeLine(phrases: MasterPhrases, mistake: Mistake, where: string): string {
const a = mistake.advice;
const word = masterWords(phrases, a).word;
const cost = `écart ${formatEquity(a.equityLoss)} (${word})`;
if (a.kind === "move") {
return `- ${where}, ${mistake.roll} : j'ai joué ${a.played.notation}, GNU Backgammon préférait ${a.best.notation} ; ${cost}.`;
}
return `- ${where} : j'ai choisi de ${CUBE_ACTION_WORDS[a.action]}, GNU Backgammon aurait choisi de ${CUBE_ACTION_WORDS[masterCubeAction(a)]} ; ${cost}.`;
}
/** Le niveau de l'ordinateur d'une partie, par son nom. */
function computerLevelName(journal: GameJournal): string {
const level = replay(currentLine(journal)).level;
const name = computerLevelOf(level);
return name === null ? `GNU Backgammon, réglage ${level}` : LEVEL_NAMES[name];
}
/** Le résultat d'une partie finie, et le match après elle. */
function resultText(journal: GameJournal): string {
const line = currentLine(journal);
const state = replay(line);
const result = state.result;
if (result === null) {
return "partie pas encore finie";
}
const who = result.winner === "player" ? "j'ai gagné" : "l'ordinateur a gagné";
const kind = {
single: "une partie simple",
gammon: "un gammon",
backgammon: "un backgammon",
}[result.kind];
const dropped = line.some((e) => e.type === "CubeDropped")
? result.winner === "player"
? ", l'ordinateur ayant refusé mon double"
: ", après mon refus de son double"
: "";
const cube = state.cube.value > 1 ? `, videau à ${state.cube.value}` : "";
const text = `${who} ${kind}, ${plural(result.points, "point", "points")}${cube}${dropped}`;
const after = state.matchAfter;
if (state.match === null || after === null) {
return text;
}
const over = after.over ? ", match terminé" : "";
return `${text} ; match en ${state.match.length} points, score après la partie : moi ${after.score.player}, l'ordinateur ${after.score.computer}${over}`;
}
/** La position que montre le prompt du bilan : celle d'avant le coup à
* revoir, ou la position finale si le joueur n'a fait aucune erreur. */
export async function summaryPosition(
engine: Engine,
journal: GameJournal,
): Promise<PromptPosition> {
const toReview = summarizeAnalysis(journal).toReview;
return toReview === null
? positionNow(engine, journal)
: positionBefore(engine, journal, toReview.advice.eventId);
}
/** Ce que demande le prompt du bilan. */
export interface SummaryPromptData {
/** La partie finie, analysée (readyForSummary). */
readonly journal: GameJournal;
/** summaryPosition. */
readonly position: PromptPosition;
}
/** Le prompt « Bilan de ma partie ». */
export function summaryPrompt(
templates: PromptTemplates,
phrases: MasterPhrases,
data: SummaryPromptData,
): Prompt {
const summary = summarizeAnalysis(data.journal);
const { player, computer, counts } = summary;
const errors = counts.bad + counts.veryBad;
const veryBad =
counts.veryBad > 0
? ` (dont ${plural(counts.veryBad, "grosse erreur", "grosses erreurs")})`
: "";
const mistakes = mistakesOf(data.journal);
const listed = [...mistakes]
.sort((a, b) => a.advice.equityLoss - b.advice.equityLoss)
.slice(0, MAX_ERRORS)
.sort((a, b) => a.turn - b.turn)
.map((m) => mistakeLine(phrases, m, `Coup ${m.turn}`));
if (mistakes.length > listed.length) {
listed.push(`- et ${mistakes.length - listed.length} de moins coûteuses.`);
}
const toReview = summary.toReview;
return fillPrompt(templates.summary, {
...positionValues(data.position),
joueur: playerOf(data.journal),
niveau_eval: plyText(summaryPly(data.journal, toReview)),
ordinateur: computerLevelName(data.journal),
resultat: resultText(data.journal),
decomptes: `${plural(counts.good, "bon coup", "bons coups")}, ${plural(counts.doubtful, "imprécision", "imprécisions")}, ${plural(errors, "erreur", "erreurs")}${veryBad}`,
taux: formatEquity(-player.errorRate.perDecision),
decisions: plural(player.errorRate.decisions, "décision", "décisions"),
niveau_jeu: LEVEL_NAMES[player.errorRate.level],
taux_ordinateur: `${formatEquity(-computer.errorRate.perDecision)} sur ${plural(computer.errorRate.decisions, "décision", "décisions")}, soit le niveau ${LEVEL_NAMES[computer.errorRate.level]}`,
chance: formatEquity(player.luck.perRoll),
chance_mots: diceWords(phrases, player.luck.rating),
chance_ordinateur: formatEquity(computer.luck.perRoll),
erreurs:
listed.length === 0 ? "- aucune : j'ai joué comme GNU Backgammon." : listed.join("\n"),
position_titre:
toReview === null
? "Je n'ai fait ni imprécision ni erreur. Voici la position finale"
: `Le coup à revoir, ma plus grosse erreur (coup ${toReview.turn}) : la position avant ma décision`,
});
}
/** Le niveau des analyses du bilan : celui du coup à revoir, ou de
* l'analyse de partie (2 plis). */
function summaryPly(journal: GameJournal, toReview: ReviewedDecision | null): Ply {
return toReview?.advice.ply ?? journal.review?.ply ?? 2;
}
// ------------------------------------------------------- Un concept
/** La position d'exemple d'un concept : la partie en cours, ou la
* position de départ s'il n'y en a pas (ou si elle est finie), avec
* l'évaluation du moteur. */
export interface ConceptExample {
readonly position: PromptPosition;
readonly evaluation: Evaluation;
readonly ply: Ply;
readonly fromGame: boolean;
}
/** Lit la position d'exemple d'un concept et l'évalue, au niveau ply. */
export async function conceptExample(
engine: Engine,
journal: GameJournal | null,
ply: Ply,
): Promise<ConceptExample> {
const playing =
journal !== null && !["opening", "over"].includes(replay(currentLine(journal)).phase);
const position = await positionNow(engine, playing ? journal : null);
const evaluation = await evaluatePosition(engine, position, ply);
return { position, evaluation, ply, fromGame: playing };
}
/** Ce que demande le prompt d'un concept. */
export interface ConceptPromptData {
/** Le terme, son nom anglais (peut être vide) et sa phrase « En bref ». */
readonly term: string;
readonly english: string;
readonly brief: string;
/** La partie en cours, pour le niveau du joueur (null : aucune). */
readonly journal: GameJournal | null;
readonly example: ConceptExample;
}
/** Le prompt « Expliquer ce concept ». */
export function conceptPrompt(templates: PromptTemplates, data: ConceptPromptData): Prompt {
const { example } = data;
const english =
data.english !== "" && data.english.toLowerCase() !== data.term.toLowerCase()
? ` (en anglais : ${data.english})`
: "";
return fillPrompt(templates.concept, {
...positionValues(example.position),
joueur: playerOf(data.journal),
niveau_eval: plyText(example.ply),
concept: `« ${data.term} »${english}`,
definition: data.brief,
position_titre: example.fromGame
? "une position de ma partie en cours"
: "la position de départ",
evaluation: `chances de gagner ${formatPercent(example.evaluation.win)}, équité ${formatEquity(example.evaluation.equity)}`,
});
}
// ------------------------------------------------------ Des exercices
/** Une erreur dans une des parties. */
interface GameMistake extends Mistake {
/** Rang de la partie, à partir de 1 (la plus ancienne). */
readonly game: number;
readonly journal: GameJournal;
}
/** Les imprécisions et erreurs de plusieurs parties, de la plus coûteuse à
* la moins coûteuse. */
function costliest(journals: readonly GameJournal[]): GameMistake[] {
return journals
.flatMap((journal, i) => mistakesOf(journal).map((m) => ({ ...m, game: i + 1, journal })))
.sort((a, b) => a.advice.equityLoss - b.advice.equityLoss);
}
/** La position de la plus coûteuse des erreurs de ces parties (null s'il
* n'y en a aucune : pas d'exercice à proposer). */
export async function exercisesPosition(
engine: Engine,
journals: readonly GameJournal[],
): Promise<PromptPosition | null> {
const worst = costliest(journals)[0];
return worst === undefined ? null : positionBefore(engine, worst.journal, worst.advice.eventId);
}
/** Ce que demande le prompt des exercices. */
export interface ExercisesPromptData {
/** Les parties analysées, de la plus ancienne à la plus récente. */
readonly journals: readonly GameJournal[];
/** exercisesPosition (non null). */
readonly position: PromptPosition;
}
/** Le prompt « Créer des exercices » (progression, étape 1h). Erreur si
* les parties n'ont aucune imprécision ni erreur. */
export function exercisesPrompt(
templates: PromptTemplates,
phrases: MasterPhrases,
data: ExercisesPromptData,
): Prompt {
const mistakes = costliest(data.journals);
const worst = mistakes[0];
if (worst === undefined) {
throw new Error("exercices : aucune erreur dans ces parties");
}
// Le niveau, sur toutes les décisions de ces parties.
let total = 0;
let decisions = 0;
for (const journal of data.journals) {
const rate = summarizeAnalysis(journal).player.errorRate;
total += rate.total;
decisions += rate.decisions;
}
const level = levelOfErrorRate(decisions > 0 ? total / decisions : 0);
const listed = mistakes
.slice(0, MAX_ERRORS)
.map((m) => mistakeLine(phrases, m, `Partie ${m.game}, coup ${m.turn}`));
return fillPrompt(templates.exercises, {
...positionValues(data.position),
joueur: playerSentence({ decisions, level }),
niveau_eval: plyText(worst.advice.ply),
parties: String(data.journals.length),
erreurs: listed.join("\n"),
position_titre: `La plus coûteuse (partie ${worst.game}, coup ${worst.turn}) : la position avant ma décision`,
});
}
+73
View File
@@ -0,0 +1,73 @@
// Les gabarits des prompts pour une IA (étape 1f) : lecture de leur source
// (docs/prompts/, ADR 0008 : une seule source) et remplissage des repères.
// Fonctions pures, testées sous Node sur de vraies analyses du moteur
// (app/tests/prompts.test.ts).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
/**
* Un prompt : le texte que l'application prépare pour une IA, rempli avec
* la position et les chiffres du moteur, et que le joueur copie.
*
* Glossaire : docs/glossaire/prompt.md
*/
export type Prompt = string;
/** Les cinq gabarits du cadrage (« IA générative en V1 »). */
export type PromptKind = "move" | "cube" | "summary" | "concept" | "exercises";
export const PROMPT_KINDS: readonly PromptKind[] = [
"move",
"cube",
"summary",
"concept",
"exercises",
];
/** Le fichier de chaque gabarit, dans docs/prompts/. */
export const PROMPT_FILES: Readonly<Record<PromptKind, string>> = {
move: "coup.md",
cube: "videau.md",
summary: "bilan.md",
concept: "concept.md",
exercises: "exercices.md",
};
/** Les gabarits lus, par sorte. */
export type PromptTemplates = Readonly<Record<PromptKind, string>>;
/** Le gabarit d'un fichier de docs/prompts/ : le bloc de texte qui suit le
* titre « ## Gabarit ». Erreur s'il manque. */
export function parsePromptTemplate(markdown: string): string {
const lines = markdown.split("\n");
const heading = lines.findIndex((line) => line.trim() === "## Gabarit");
const start = lines.findIndex((line, i) => i > heading && line.trim() === "```text");
const end = lines.findIndex((line, i) => i > start && line.trim() === "```");
if (heading < 0 || start < 0 || end < 0) {
throw new Error("gabarit de prompt : bloc « ## Gabarit » absent");
}
return lines.slice(start + 1, end).join("\n");
}
/** Les repères d'un gabarit, dans l'ordre, sans doublon. */
export function placeholders(template: string): string[] {
return [...new Set([...template.matchAll(/\{([a-z_]+)\}/g)].map((m) => m[1] as string))];
}
/**
* Remplit les repères {nom} d'un gabarit. Erreur sur un repère inconnu ou
* une valeur vide : un prompt n'a jamais de trou.
*/
export function fillPrompt(template: string, values: Readonly<Record<string, string>>): Prompt {
return template.replace(/\{([a-z_]+)\}/g, (_, name: string) => {
const value = values[name];
if (value === undefined) {
throw new Error(`gabarit de prompt : repère {${name}} inconnu`);
}
if (value.trim() === "") {
throw new Error(`gabarit de prompt : repère {${name}} vide`);
}
return value;
});
}
+12 -8
View File
@@ -19,6 +19,7 @@ import type {
EngineCube,
EngineMatch,
EvaluatedMove,
Evaluation,
HalfMovesCheck,
Level,
Luck,
@@ -181,6 +182,7 @@ export function createWasmEngine(run: RunCommand): Engine {
best: CliEvaluatedMove | null;
equity_loss: number;
skill: CliSkill;
ranking: CliEvaluatedMove[];
};
if (answer.rank === null || answer.played === null || answer.best === null) {
return null;
@@ -192,17 +194,10 @@ export function createWasmEngine(run: RunCommand): Engine {
best: toEvaluatedMove(answer.best),
equityLoss: answer.equity_loss,
skill: toSkill(answer.skill),
ranking: answer.ranking.map(toEvaluatedMove),
};
},
async rankMoves(position: PositionId, cube: EngineCube, roll: Roll, ply: Ply) {
const args = ["--ply", String(ply), "moves", position, await matchId(cube)];
const answer = (await run([...args, diceText(roll)])) as {
moves: CliEvaluatedMove[];
};
return answer.moves.map(toEvaluatedMove);
},
async analyseCube(
position: PositionId,
cube: EngineCube,
@@ -260,6 +255,15 @@ export function createWasmEngine(run: RunCommand): Engine {
return { value: answer.luck, rating };
},
async evaluate(position: PositionId, cube: EngineCube, ply: Ply): Promise<Evaluation> {
const args = ["--ply", String(ply), "eval", position, await matchId(cube)];
const answer = (await run(args)) as {
probabilities: { win: number };
cubeful_equity: number;
};
return { win: answer.probabilities.win, equity: answer.cubeful_equity };
},
encodeMatch: matchId,
async decodeMatch(id: MatchId): Promise<MatchDescription> {
+31 -1
View File
@@ -5,9 +5,11 @@
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import { analyseDecision } from "./domain/analysis/analyse.js";
import { ANALYSIS_PLY, analyseDecision } from "./domain/analysis/analyse.js";
import { runAnalysis } from "./domain/analysis/game-analysis.js";
import { Game } from "./domain/game/game.js";
import { linkOf, readPosition } from "./domain/game/position-link.js";
import { levelOf } from "./domain/game/saved-game.js";
import { exportSgf } from "./domain/game/sgf.js";
import {
illustratedMove,
@@ -15,6 +17,8 @@ import {
shouldTake,
tutorialBoard,
} from "./domain/learning/tutorial.js";
import { positionBefore } from "./domain/prompts/position.js";
import { conceptExample, summaryPosition } from "./domain/prompts/prompts.js";
import { createWasmEngine } from "./engine/wasm-engine.js";
import { type EngineWorker, startEngineWorker } from "./engine/worker-run.js";
import { createGameSession } from "./storage/game-session.js";
@@ -103,6 +107,22 @@ startApp({
journal: async (id) => (await storage().library.load(id))?.journal ?? null,
shownId: () => storage().session.shownId,
open: (id, branchHead) => storage().session.open(id, branchHead),
view: async (id) => {
const saved = await storage().library.load(id);
if (saved === null) {
return null;
}
try {
return Game.resume(engine, saved.journal);
} catch {
return null;
}
},
saveAnalyses: (id, journal) => {
storage()
.library.saveAnalyses(id, journal, { level: levelOf(journal) })
.catch(() => {});
},
remove: (id) => storage().library.remove(id),
exportSgf: async (id) => {
const game = await storage().library.load(id);
@@ -143,6 +163,16 @@ startApp({
// Cela évite aussi de télécharger deux fois ces données à la première
// visite.
analyse: (journal, eventId) => analyseDecision(analysisEngine, journal, eventId),
// Le bilan et l'analyse de partie (étape 1e) : les analyses qui
// manquent, une à une, sur le même moteur à part.
analyseGame: (journal, task) => runAnalysis(analysisEngine, journal, task),
// Les prompts pour une IA (étape 1f) : la position à décrire, lue par
// le moteur, et l'évaluation de la position d'exemple d'un concept.
prompts: {
before: (journal, eventId) => positionBefore(engine, journal, eventId),
summary: (journal) => summaryPosition(engine, journal),
concept: (journal) => conceptExample(engine, journal, ANALYSIS_PLY),
},
startUpdates: (onAvailable) =>
startUpdates(new URL("../sw.js", import.meta.url), worker.ready, onAvailable),
});
+13
View File
@@ -33,6 +33,10 @@ export interface GameLibrary {
/** Enregistre la partie id (nouvelle ou non), qui devient la partie en
* cours. Renvoie son résumé. */
save(id: string, journal: GameJournal, details: SavedGameDetails): Promise<SavedGameSummary>;
/** Enregistre le journal d'une partie analysée en arrière-plan (étape
* 1e) : ni la partie en cours ni la date de la dernière action ne
* changent. Rien si la partie n'existe plus. */
saveAnalyses(id: string, journal: GameJournal, details: SavedGameDetails): Promise<void>;
/** Supprime une partie (rien si elle n'existe pas). */
remove(id: string): Promise<void>;
/** La partie en cours : la dernière enregistrée ou choisie (setCurrent),
@@ -118,6 +122,15 @@ export function createGameLibrary(
await backend.setCurrentId(id);
return summary;
}),
saveAnalyses: (id, journal, details) =>
enqueue(async () => {
const known = await backend.summary(id);
if (known === undefined) {
return;
}
const times = { startedAt: known.startedAt, updatedAt: known.updatedAt };
await backend.write(summarizeGame(id, journal, details, times), journal);
}),
remove: (id) => enqueue(() => backend.remove(id)),
current: () =>
enqueue(async () => {
+5 -7
View File
@@ -26,8 +26,8 @@ export const ADVICE_TEXTS = {
replay: "Rejouer le coup",
numbers: "Voir les chiffres du moteur",
you: "(vous)",
moveNote: (ply: number) =>
`Écart d'équité à ${ply} plis, par rapport au meilleur coup. Un écart de 0,03 ou moins reste un bon coup.`,
moveNote: (plies: string) =>
`Écart d'équité à ${plies}, par rapport au meilleur coup. Un écart de 0,03 ou moins reste un bon coup.`,
cubeNote: (ply: number) =>
`Équités de celui qui double, pour un videau de 1, à ${ply} plis. Écart de votre décision : `,
cubeRows: {
@@ -48,8 +48,6 @@ export const CUBE_GLOSSARY: Readonly<Record<CubeAction, { file: string; term: st
pass: { file: "passer", term: "Passer" },
};
/** Un nombre à la française, signé, à trois décimales : « −0,123 ». */
export function formatEquity(value: number): string {
const text = Math.abs(value).toFixed(3).replace(".", ",");
return value < -0.0005 ? `−${text}` : value > 0.0005 ? `+${text}` : text;
}
/** Un nombre à la française, signé, à trois décimales : « −0,123 » ; la
* même écriture que les prompts (domain/analysis/numbers.ts). */
export { formatEquity } from "../domain/analysis/numbers.js";
+43 -103
View File
@@ -7,6 +7,7 @@
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import { pliesText, rankingPly, rankingRows } from "../domain/analysis/numbers.js";
import { type MasterPhrases, masterWords } from "../domain/analysis/phrases.js";
import {
type Advice,
@@ -15,16 +16,16 @@ import {
masterCubeAction,
type Verdict,
} from "../domain/game/advice.js";
import type { Game, MoveSteps } from "../domain/game/game.js";
import type { Game } from "../domain/game/game.js";
import { ADVICE_TEXTS, CUBE_GLOSSARY, formatEquity } from "./advice-texts.js";
import { boardModel, moveTrace, placeOf } from "./board-model.js";
import { checkerSpot, NO_MARKS, renderBoard, slideChecker } from "./board-view.js";
import { boardGeometry, PORTRAIT_ASPECT } from "./geometry.js";
import { askAiLink, clearSheet } from "./ask-ai.js";
import { type IconName, icon } from "./icons.js";
import { boardSvg, createMovePlayer, drawSteps, type MovePlayer } from "./move-board.js";
import { showWithNotation } from "./notation.js";
import { routeHash } from "./router.js";
const SLIDE_MS = 160;
const PAUSE_MS = 120;
/** Préfixe des identifiants du plateau de la feuille. */
const PREFIX = "explain-";
/** Le pictogramme d'une appréciation (interaction.md, pictogrammes). */
export const VERDICT_ICONS: Readonly<Record<Verdict, IconName>> = {
@@ -48,6 +49,8 @@ export interface AdviceView {
/** Ouvre la feuille sur le conseil de l'événement eventId. */
show(eventId: string): Promise<void>;
hide(): void;
/** La feuille, où la page du prompt prend la place du contenu (1f). */
readonly sheet: HTMLElement;
}
type Shown = "mine" | "best";
@@ -85,14 +88,14 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
// Chaque ouverture a son numéro : une ouverture plus récente, ou la
// fermeture, arrête l'animation en cours.
let opened = 0;
// Chaque coup joué sur le plateau de la feuille a aussi le sien.
let playing = 0;
// Le plateau de la feuille joue un coup à la fois.
let player: MovePlayer | null = null;
async function show(eventId: string): Promise<void> {
const id = ++opened;
const game = options.game();
const advice = game?.advice[eventId] ?? null;
sheet.replaceChildren();
clearSheet(sheet);
veil.hidden = false;
const head = element(sheet, "div", { className: "sheet-head" });
element(head, "span", { className: "grip" }).setAttribute("aria-hidden", "true");
@@ -150,12 +153,21 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
});
link.href = routeHash({ screen: "glossary", term: entry.file });
}
closeButton();
closeButton(advice.eventId);
close.focus();
}
function closeButton(): void {
/** « Demander à une IA » (étape 1f), s'il y a un conseil, et
* « Fermer ». */
function closeButton(eventId: string | null = null): void {
const actions = element(sheet, "div", { className: "explain-actions" });
if (eventId !== null) {
askAiLink(
actions,
"explain-ask-ai",
routeHash({ screen: "explanation", event: eventId, ai: true }),
);
}
const done = element(actions, "button", {
id: "explain-done",
className: "secondary",
@@ -165,75 +177,14 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
done.onclick = () => options.close();
}
/** Le plateau de la feuille, dans son cadre. */
function boardSvg(box: HTMLElement): SVGSVGElement {
const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
svg.id = "explain-board";
svg.setAttribute("class", "board explain-board");
svg.setAttribute("role", "img");
box.append(svg);
/** Le plateau de la feuille, dans son cadre, et ce qui y joue les
* coups. */
function sheetBoard(box: HTMLElement): SVGSVGElement {
const svg = boardSvg(box, "explain-board", "explain-board");
player = createMovePlayer(svg, PREFIX, options.reducedMotion);
return svg;
}
function draw(svg: SVGSVGElement, steps: MoveSteps, index: number, traced: boolean): void {
const boards = steps.boards[index];
if (boards === undefined) {
return;
}
const width = svg.getBoundingClientRect().width || 358;
renderBoard(
svg,
boardGeometry("portrait", PORTRAIT_ASPECT, width / 640),
boardModel(boards),
{
...NO_MARKS,
dice: [],
cube: null,
band: null,
controls: null,
trace: traced ? moveTrace(steps.side, steps.halfMoves, steps.hits) : null,
},
);
// Les flèches des traces renvoient à leur pointe par identifiant :
// celui du plateau de jeu serait pris à sa place.
for (const marker of svg.querySelectorAll("marker[id]")) {
marker.id = `explain-${marker.id}`;
}
for (const path of svg.querySelectorAll("[marker-end]")) {
const ref = path.getAttribute("marker-end") ?? "";
path.setAttribute("marker-end", ref.replace("url(#", "url(#explain-"));
}
}
/** Joue un coup pion par pion (sans mouvement si le système le
* demande), puis laisse ses traces. */
async function animate(svg: SVGSVGElement, steps: MoveSteps): Promise<void> {
const id = ++playing;
if (!options.reducedMotion.matches) {
for (const [i, halfMove] of steps.halfMoves.entries()) {
if (id !== playing) {
return;
}
if (i > 0) {
await new Promise((resolve) => setTimeout(resolve, PAUSE_MS));
}
const from = placeOf(steps.side, halfMove.from);
const to = placeOf(steps.side, halfMove.to);
draw(svg, steps, i, false);
const start = checkerSpot(svg, from);
const victim = steps.hits[i] === true ? checkerSpot(svg, to) : null;
draw(svg, steps, i + 1, false);
await Promise.all([
start && slideChecker(svg, to, start, SLIDE_MS),
victim && slideChecker(svg, "bar-computer", victim, SLIDE_MS),
]);
}
}
if (id === playing) {
draw(svg, steps, steps.halfMoves.length, true);
}
}
async function showMoves(
id: number,
game: Game,
@@ -250,13 +201,13 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
return;
}
const legend = element(body, "p", { id: "explain-legend", className: "explain-legend" });
const svg = boardSvg(boardBox);
const svg = sheetBoard(boardBox);
if (best === null) {
svg.dataset.move = "mine";
svg.setAttribute("aria-label", ADVICE_TEXTS.legendSame(advice.played.notation));
legend.textContent = ADVICE_TEXTS.legendSame(advice.played.notation);
draw(svg, mine, 0, false);
void animate(svg, mine);
const text = ADVICE_TEXTS.legendSame(advice.played.notation);
svg.setAttribute("aria-label", text);
showWithNotation(legend, text, advice.played.notation);
void player?.play(mine);
return;
}
const choice = element(body, "div", { id: "explain-choice", className: "segmented" });
@@ -284,12 +235,10 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
shown === "mine"
? ADVICE_TEXTS.legendMine(notation)
: ADVICE_TEXTS.legendBest(notation);
legend.textContent = text;
showWithNotation(legend, text, notation);
svg.setAttribute("aria-label", text);
svg.dataset.move = shown;
const steps = shown === "mine" ? mine : best;
draw(svg, steps, 0, false);
void animate(svg, steps);
void player?.play(shown === "mine" ? mine : best);
};
for (const key of ["mine", "best"] as const) {
const button = buttons[key];
@@ -320,9 +269,9 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
if (id !== opened) {
return;
}
const svg = boardSvg(boardBox);
const svg = boardSvg(boardBox, "explain-board", "explain-board");
svg.setAttribute("aria-label", ADVICE_TEXTS.legendCube);
draw(svg, steps, 0, false);
drawSteps(svg, steps, 0, false, PREFIX);
element(boardBox, "p", { className: "explain-legend", text: ADVICE_TEXTS.legendCube });
}
@@ -342,18 +291,8 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
if (advice.kind === "move") {
// Les écarts du classement se lisent par rapport à son premier
// coup ; votre coup, s'il n'y figure pas, avec l'écart de
// l'analyse du coup joué.
const first = advice.ranking[0]?.equity ?? advice.best.equity;
const listed = advice.ranking.map((move, i) => ({
move,
rank: i + 1,
loss: move.equity - first,
}));
if (!advice.ranking.some((m) => m.notation === advice.played.notation)) {
listed.push({ move: advice.played, rank: advice.rank, loss: advice.equityLoss });
}
for (const { move, rank, loss } of listed) {
const mine = move.notation === advice.played.notation;
// l'analyse du coup joué (les mêmes lignes que le prompt).
for (const { move, rank, loss, played: mine } of rankingRows(advice)) {
row(
[
String(rank),
@@ -365,7 +304,7 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
}
element(details, "p", {
className: "explain-note",
text: ADVICE_TEXTS.moveNote(advice.ply),
text: ADVICE_TEXTS.moveNote(pliesText(rankingPly(advice))),
});
} else {
// Les lignes de votre décision, en gras : doubler mène à l'une des
@@ -397,12 +336,13 @@ export function createAdviceView(options: AdviceViewOptions): AdviceView {
return {
show,
sheet,
hide() {
opened++;
playing++;
player?.stop();
if (!veil.hidden) {
veil.hidden = true;
sheet.replaceChildren();
clearSheet(sheet);
}
},
};
+687
View File
@@ -0,0 +1,687 @@
// L'écran d'analyse d'une partie (#/parties/<id>/analyse/<coup>, étape
// 1e ; charte, ecrans-etape-1.md, « Analyse ») : une page qui défile, avec
// la courbe de vos chances de gagner coup après coup, parcourue du doigt ;
// le visualiseur du coup choisi (votre coup contre le coup du maître,
// « Rejouer d'ici ») ; la liste des coups à revoir, filtrable ; et les
// chiffres du moteur, repliés.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// La courbe est dessinée à la main en SVG (aucune bibliothèque). Chaque
// coup y a une bande verticale sur toute la hauteur, cible du doigt : on
// touche ou on glisse, et le coup sous le doigt est choisi. Le coup choisi
// est dans l'adresse ; en changer remplace l'adresse (le retour du
// téléphone quitte l'écran, il ne repasse pas par chaque coup).
import {
chanceCurve,
computerMoveAdvice,
type GameSummary,
gameTurns,
mainAdvice,
replayPoint,
summarizeAnalysis,
type Turn,
type WinChanceCurve,
} from "../domain/analysis/game-analysis.js";
import { type MasterPhrases, masterWords } from "../domain/analysis/phrases.js";
import { type Advice, type Verdict, verdictOf } from "../domain/game/advice.js";
import type { GameJournal } from "../domain/game/events.js";
import type { Game, MoveSteps } from "../domain/game/game.js";
import { formatHalfMoves } from "../domain/game/position.js";
import { VERDICT_ICONS } from "./advice-view.js";
import { askAiLink } from "./ask-ai.js";
import { icon } from "./icons.js";
import { MATCH_TEXTS } from "./match-texts.js";
import { boardSvg, createMovePlayer, drawSteps, type MovePlayer } from "./move-board.js";
import { percent, REVIEW_TEXTS, signed } from "./review-texts.js";
import { routeHash } from "./router.js";
/** Ce que montre l'écran. */
export interface AnalysisData {
readonly id: string;
readonly journal: GameJournal;
/** La partie, pour rejouer les coups sur le plateau. */
readonly game: Game;
/** Le coup choisi (null : le coup à revoir, ou le premier). */
readonly turn: number | null;
readonly phrases: MasterPhrases | null;
}
export interface AnalysisViewOptions {
/** La page (index.html) ; son contenu est construit ici. */
readonly section: HTMLElement;
readonly reducedMotion: MediaQueryList;
/** Choisir un autre coup : remplacer l'adresse. */
readonly select: (turn: number) => void;
/** « Rejouer d'ici » : revenir à cet événement de la partie. */
readonly replay: (id: string, eventId: string) => void;
/** Le lien « Retour » (quitter l'écran sans empiler d'adresse). */
readonly back: (link: HTMLAnchorElement) => void;
}
export interface AnalysisView {
show(data: AnalysisData | null): void;
hide(): void;
/** ← et → : le coup d'avant ou d'après. */
step(delta: number): void;
}
type Filter = "all" | "errors" | "doubtful";
type Shown = "mine" | "best";
const SVG_NS = "http://www.w3.org/2000/svg";
/** Hauteur de la courbe, et marges du tracé (repère en pixels). */
const CURVE_HEIGHT = 168;
const PAD = { left: 40, right: 10, top: 10, bottom: 10 };
function element<K extends keyof HTMLElementTagNameMap>(
parent: HTMLElement,
tag: K,
options: { id?: string; className?: string; text?: string } = {},
): HTMLElementTagNameMap[K] {
const child = document.createElement(tag);
if (options.id !== undefined) {
child.id = options.id;
}
if (options.className !== undefined) {
child.className = options.className;
}
if (options.text !== undefined) {
child.textContent = options.text;
}
parent.append(child);
return child;
}
function svgElement<K extends keyof SVGElementTagNameMap>(
parent: Element,
tag: K,
attributes: Record<string, string | number>,
): SVGElementTagNameMap[K] {
const child = document.createElementNS(SVG_NS, tag);
for (const [name, value] of Object.entries(attributes)) {
child.setAttribute(name, String(value));
}
parent.append(child);
return child;
}
/** Les verdicts que montre chaque filtre. */
const FILTERS: Readonly<Record<Filter, readonly Verdict[]>> = {
all: ["good", "doubtful", "bad", "veryBad"],
errors: ["bad", "veryBad"],
doubtful: ["doubtful"],
};
export function createAnalysisView(options: AnalysisViewOptions): AnalysisView {
const { section } = options;
let data: AnalysisData | null = null;
let turns: Turn[] = [];
let curve: WinChanceCurve = [];
let selected = 1;
let filter: Filter = "all";
// Ce qui est dessiné dans le visualiseur, pour ne pas rejouer le coup à
// chaque analyse rangée.
let drawnTurn = "";
let player: MovePlayer | null = null;
// Chaque changement de coup a son numéro : un plateau qui arrive trop
// tard n'est pas dessiné.
let request = 0;
// La page : en-tête, courbe, visualiseur, liste, chiffres.
const head = element(section, "div", { className: "analysis-head" });
const back = element(head, "a", {
id: "analysis-back",
className: "button secondary",
text: REVIEW_TEXTS.back,
});
back.href = "#/";
options.back(back);
element(head, "h2", {
id: "analysis-title",
className: "analysis-title",
text: REVIEW_TEXTS.analysisTitle,
});
const message = element(section, "p", {
id: "analysis-message",
className: "analysis-message",
});
message.setAttribute("role", "status");
const curveCard = element(section, "section", { className: "analysis-card curve-card" });
element(curveCard, "h3", { className: "overline", text: REVIEW_TEXTS.curveTitle });
const curveSvg = document.createElementNS(SVG_NS, "svg");
curveSvg.id = "analysis-curve";
curveSvg.setAttribute("class", "analysis-curve");
curveSvg.setAttribute("role", "slider");
curveSvg.setAttribute("tabindex", "0");
curveCard.append(curveSvg);
const viewer = element(section, "section", {
id: "analysis-viewer",
className: "analysis-card viewer",
});
const nav = element(viewer, "div", { className: "viewer-nav" });
const prev = element(nav, "a", { id: "analysis-prev", className: "icon-button viewer-step" });
prev.append(icon("chevron"));
prev.setAttribute("aria-label", REVIEW_TEXTS.previous);
const turnTitle = element(nav, "p", { id: "analysis-turn", className: "viewer-turn" });
turnTitle.setAttribute("aria-live", "polite");
const next = element(nav, "a", { id: "analysis-next", className: "icon-button viewer-step" });
next.append(icon("chevron"));
next.setAttribute("aria-label", REVIEW_TEXTS.next);
for (const [link, delta] of [
[prev, -1],
[next, 1],
] as const) {
link.addEventListener("click", (event) => {
event.preventDefault();
step(delta);
});
}
const viewerBody = element(viewer, "div", { className: "viewer-body" });
const boardBox = element(viewerBody, "div", { className: "viewer-board-box" });
const board = boardSvg(boardBox, "analysis-board", "analysis-board");
player = createMovePlayer(board, "analysis-", options.reducedMotion);
const viewerText = element(viewerBody, "div", { className: "viewer-text" });
const phrase = element(viewerText, "p", { id: "analysis-phrase", className: "viewer-phrase" });
const choice = element(viewerText, "div", { id: "analysis-choice", className: "segmented" });
choice.setAttribute("role", "radiogroup");
choice.setAttribute("aria-label", REVIEW_TEXTS.choiceLabel);
const segments: Record<Shown, HTMLButtonElement> = {
mine: element(choice, "button", { id: "analysis-mine", className: "segment" }),
best: element(choice, "button", {
id: "analysis-best",
className: "segment",
text: REVIEW_TEXTS.masterMove,
}),
};
for (const key of ["mine", "best"] as const) {
segments[key].type = "button";
segments[key].setAttribute("role", "radio");
}
const legend = element(viewerText, "p", { id: "analysis-legend", className: "viewer-legend" });
const chanceLine = element(viewerText, "p", {
id: "analysis-chance",
className: "viewer-chance",
});
const viewerActions = element(viewerText, "div", { className: "viewer-actions" });
const replayButton = element(viewerActions, "button", {
id: "analysis-replay",
text: REVIEW_TEXTS.replayFromHere,
});
replayButton.type = "button";
// « Demander à une IA » (étape 1f) : le prompt de la décision du joueur
// dans ce coup, s'il y en a une.
const slot = element(viewerActions, "div", { className: "ask-ai-slot" });
slot.dataset.slot = "ask-ai";
const askAi = askAiLink(slot, "analysis-ask-ai", "#/");
const replayHint = element(viewerText, "p", {
className: "viewer-legend",
text: REVIEW_TEXTS.replayHint,
});
const listCard = element(section, "section", { className: "analysis-card list-card" });
element(listCard, "h3", { className: "overline", text: REVIEW_TEXTS.listTitle });
const filters = element(listCard, "div", { id: "analysis-filters", className: "filters" });
filters.setAttribute("role", "group");
filters.setAttribute("aria-label", REVIEW_TEXTS.filterLabel);
const filterButtons: Record<Filter, HTMLButtonElement> = {
all: element(filters, "button", { className: "filter" }),
errors: element(filters, "button", { className: "filter" }),
doubtful: element(filters, "button", { className: "filter" }),
};
for (const key of ["all", "errors", "doubtful"] as const) {
const button = filterButtons[key];
button.type = "button";
button.dataset.filter = key;
button.onclick = () => {
filter = key;
renderList();
};
}
const list = element(listCard, "ul", { id: "analysis-list", className: "analysis-list" });
const numbers = element(section, "details", {
id: "analysis-numbers",
className: "analysis-card explain-numbers",
});
element(numbers, "summary", { text: REVIEW_TEXTS.numbers });
const table = element(numbers, "div", { className: "explain-table analysis-table" });
element(numbers, "p", { className: "explain-note", text: REVIEW_TEXTS.numbersNote });
// ------------------------------------------------------------ Courbe
/** Le coup sous l'abscisse x (pixels du tracé). */
function turnAt(x: number): number {
const width = curveSvg.getBoundingClientRect().width;
const inner = Math.max(1, width - PAD.left - PAD.right);
const index = Math.floor(((x - PAD.left) / inner) * turns.length);
return Math.min(turns.length, Math.max(1, index + 1));
}
let dragging = false;
curveSvg.addEventListener("pointerdown", (event) => {
dragging = true;
curveSvg.setPointerCapture?.(event.pointerId);
choose(turnAt(event.clientX - curveSvg.getBoundingClientRect().left));
});
curveSvg.addEventListener("pointermove", (event) => {
if (dragging) {
choose(turnAt(event.clientX - curveSvg.getBoundingClientRect().left));
}
});
for (const end of ["pointerup", "pointercancel"] as const) {
curveSvg.addEventListener(end, () => {
dragging = false;
});
}
curveSvg.addEventListener("keydown", (event) => {
if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
event.preventDefault();
event.stopPropagation();
step(event.key === "ArrowLeft" ? -1 : 1);
}
});
function renderCurve(): void {
const width = Math.round(curveSvg.getBoundingClientRect().width || 360);
const height = CURVE_HEIGHT;
curveSvg.setAttribute("viewBox", `0 0 ${width} ${height}`);
curveSvg.replaceChildren();
const inner = width - PAD.left - PAD.right;
const band = turns.length > 0 ? inner / turns.length : inner;
const x = (turn: number) => PAD.left + (turn - 0.5) * band;
const y = (chance: number) => PAD.top + (1 - chance) * (height - PAD.top - PAD.bottom);
// Axe : 100 %, 50 % (pointillé), 0 %.
for (const level of [1, 0.5, 0]) {
svgElement(curveSvg, "line", {
x1: PAD.left,
x2: width - PAD.right,
y1: y(level),
y2: y(level),
class: level === 0.5 ? "curve-half" : "curve-axis",
});
const label = svgElement(curveSvg, "text", {
x: PAD.left - 6,
y: y(level) + 4,
class: "curve-label",
"text-anchor": "end",
});
label.textContent = percent(level);
}
const known = curve.filter((p) => p.chance !== null) as {
turn: number;
chance: number;
verdict: Verdict | null;
side: string;
}[];
if (known.length > 0) {
const line = known.map((p) => `${x(p.turn)},${y(p.chance)}`).join(" ");
const first = known[0] as { turn: number };
const last = known.at(-1) as { turn: number };
svgElement(curveSvg, "polygon", {
points: `${x(first.turn)},${y(0)} ${line} ${x(last.turn)},${y(0)}`,
class: "curve-area",
});
svgElement(curveSvg, "polyline", { points: line, class: "curve-line" });
}
// Le coup choisi : un trait vertical brique.
svgElement(curveSvg, "line", {
x1: x(selected),
x2: x(selected),
y1: PAD.top,
y2: height - PAD.bottom,
class: "curve-cursor",
});
for (const point of known) {
const commented = point.verdict !== null;
svgElement(curveSvg, "circle", {
cx: x(point.turn),
cy: y(point.chance),
r: commented ? 4 : 2,
class: commented ? `curve-dot verdict-${point.verdict}` : "curve-dot other",
});
}
const chosen = curve[selected - 1];
if (chosen?.chance != null) {
svgElement(curveSvg, "circle", {
cx: x(selected),
cy: y(chosen.chance),
r: 7,
class: "curve-ring",
});
}
// Les bandes, sur toute la hauteur : cibles du doigt.
for (const turn of turns) {
const rect = svgElement(curveSvg, "rect", {
x: PAD.left + (turn.number - 1) * band,
y: 0,
width: band,
height,
class: turn.number === selected ? "curve-band selected" : "curve-band",
});
rect.dataset.turn = String(turn.number);
}
const chance = chosen?.chance;
curveSvg.setAttribute("aria-valuemin", "1");
curveSvg.setAttribute("aria-valuemax", String(turns.length));
curveSvg.setAttribute("aria-valuenow", String(selected));
const spoken =
chance === null || chance === undefined ? REVIEW_TEXTS.curveUnknown : percent(chance);
curveSvg.setAttribute("aria-valuetext", spoken);
curveSvg.setAttribute(
"aria-label",
REVIEW_TEXTS.curveLabel(selected, turns.length, spoken),
);
}
// -------------------------------------------------------- Visualiseur
function renderViewer(): void {
const current = data;
const turn = turns[selected - 1];
if (current === null || turn === undefined) {
return;
}
prev.href = routeHash({
screen: "analysis",
game: current.id,
turn: Math.max(1, selected - 1),
});
next.href = routeHash({
screen: "analysis",
game: current.id,
turn: Math.min(turns.length, selected + 1),
});
prev.setAttribute("aria-disabled", String(selected <= 1));
next.setAttribute("aria-disabled", String(selected >= turns.length));
const roll = turn.roll === null ? "" : ` · ${REVIEW_TEXTS.roll(turn.roll)}`;
turnTitle.textContent = `${REVIEW_TEXTS.turnOf(selected, turns.length)}${roll}`;
const chance = curve[selected - 1]?.chance;
chanceLine.textContent =
chance === null || chance === undefined
? ""
: REVIEW_TEXTS.chanceAfter(percent(chance));
const main = mainAdvice(current.journal, turn);
const theirs = computerMoveAdvice(current.journal, turn);
const key = [
current.id,
selected,
main?.eventId ?? "",
theirs?.eventId ?? "",
current.phrases !== null,
].join("|");
askAi.hidden = main === null;
askAi.href = routeHash({ screen: "analysis", game: current.id, turn: selected, ai: true });
replayButton.hidden = replayPoint(current.journal, turn) === null;
replayHint.hidden = replayButton.hidden;
replayButton.onclick = () => {
const point = replayPoint(current.journal, turn);
if (point !== null) {
options.replay(current.id, point);
}
};
if (key === drawnTurn) {
return;
}
drawnTurn = key;
player?.stop();
phrase.replaceChildren();
delete phrase.dataset.verdict;
legend.textContent = "";
const id = ++request;
// Ce qu'en dit le maître : la décision du joueur à revoir, ou ce
// qu'a fait l'ordinateur.
if (main !== null && current.phrases !== null) {
const words = masterWords(current.phrases, main);
phrase.dataset.verdict = words.verdict;
const word = document.createElement("strong");
word.append(icon(VERDICT_ICONS[words.verdict]), `${words.word}.`);
const said = document.createElement("em");
said.textContent = words.phrase;
phrase.append(word, " ", said);
} else if (turn.side === "computer") {
phrase.textContent =
turn.move === null
? REVIEW_TEXTS.computerCube
: turn.move.halfMoves.length === 0
? REVIEW_TEXTS.computerCannotMove
: REVIEW_TEXTS.computerPlayed(
theirs?.played.notation ?? formatHalfMoves(turn.move.halfMoves),
);
} else if (turn.move !== null && turn.move.halfMoves.length === 0) {
phrase.textContent = REVIEW_TEXTS.playerCannotMove;
}
// Le plateau : le coup joué et, s'il diffère, le meilleur coup.
void (async () => {
const side = turn.side;
let mine: MoveSteps | null = null;
let best: MoveSteps | null = null;
// Les coups s'écrivent dans la notation du moteur, comme dans le
// bilan et la feuille du maître (« 6/off », pas « 6/5 5/off ») ;
// à défaut d'analyse, à partir des demi-coups.
let names = { mine: "", best: "" };
const moveAdvice: Advice | null = side === "player" ? main : theirs;
try {
if (moveAdvice?.kind === "move") {
mine = await current.game.stepsBefore(
moveAdvice.eventId,
side,
moveAdvice.played.halfMoves,
);
names = {
mine: moveAdvice.played.notation,
best: moveAdvice.best.notation,
};
if (moveAdvice.rank > 1) {
best = await current.game.stepsBefore(
moveAdvice.eventId,
side,
moveAdvice.best.halfMoves,
);
}
} else if (moveAdvice?.kind === "cube") {
mine = await current.game.stepsBefore(moveAdvice.eventId, "player", []);
} else if (turn.move !== null) {
mine = await current.game.stepsBefore(turn.move.id, side, turn.move.halfMoves);
names = { mine: formatHalfMoves(turn.move.halfMoves), best: "" };
} else {
const first = turn.events[0];
mine =
first === undefined
? null
: await current.game.stepsBefore(first.id, side, []);
}
} catch {
mine = null;
}
if (id !== request || mine === null) {
return;
}
showMoves(mine, best, side, names);
})();
}
function showMoves(
mine: MoveSteps,
best: MoveSteps | null,
side: "player" | "computer",
names: { readonly mine: string; readonly best: string },
): void {
const who = side === "player" ? REVIEW_TEXTS.yourMoveSegment : REVIEW_TEXTS.theirMove;
segments.mine.textContent = who;
choice.hidden = best === null;
const select = (shown: Shown) => {
const steps = shown === "best" && best !== null ? best : mine;
for (const key of ["mine", "best"] as const) {
segments[key].setAttribute("aria-checked", String(key === shown));
}
board.dataset.move = shown;
if (steps.halfMoves.length === 0) {
legend.textContent = REVIEW_TEXTS.legendPosition;
board.setAttribute("aria-label", REVIEW_TEXTS.legendPosition);
drawSteps(board, steps, 0, false, "analysis-");
return;
}
const text = REVIEW_TEXTS.legendMove(
shown === "best" ? REVIEW_TEXTS.masterMove : who,
shown === "best" ? names.best : names.mine,
);
legend.textContent = text;
board.setAttribute("aria-label", text);
void player?.play(steps);
};
segments.mine.onclick = () => select("mine");
segments.best.onclick = () => select("best");
choice.onkeydown = (event) => {
if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
event.preventDefault();
event.stopPropagation();
const nextShown =
segments.mine.getAttribute("aria-checked") === "true" ? "best" : "mine";
select(nextShown);
segments[nextShown].focus();
}
};
select("mine");
}
// -------------------------------------------------------------- Liste
function renderList(): void {
const current = data;
if (current === null) {
return;
}
const rows = turns
.map((turn) => ({ turn, advice: mainAdvice(current.journal, turn) }))
.filter((row): row is { turn: Turn; advice: Advice } => row.advice !== null);
const count = (f: Filter) =>
rows.filter((r) => FILTERS[f].includes(verdictOf(r.advice.skill))).length;
for (const key of ["all", "errors", "doubtful"] as const) {
filterButtons[key].textContent = `${REVIEW_TEXTS.filters[key]} · ${count(key)}`;
filterButtons[key].setAttribute("aria-pressed", String(key === filter));
}
list.replaceChildren();
const shown = rows.filter((r) => FILTERS[filter].includes(verdictOf(r.advice.skill)));
if (shown.length === 0) {
element(list, "li", { className: "analysis-empty", text: REVIEW_TEXTS.emptyFilter });
return;
}
for (const { turn, advice } of shown) {
const item = element(list, "li");
const link = element(item, "a", { className: "analysis-row" });
link.href = routeHash({ screen: "analysis", game: current.id, turn: turn.number });
link.dataset.turn = String(turn.number);
if (turn.number === selected) {
link.setAttribute("aria-current", "true");
}
const verdict = verdictOf(advice.skill);
const word = current.phrases === null ? "" : masterWords(current.phrases, advice).word;
const roll = turn.roll === null ? "" : REVIEW_TEXTS.roll(turn.roll);
const move =
advice.kind === "move"
? advice.played.notation
: REVIEW_TEXTS.cubeActions[advice.action];
link.setAttribute("aria-label", REVIEW_TEXTS.rowLabel(turn.number, roll, move, word));
element(link, "span", { className: "row-number", text: String(turn.number) });
element(link, "span", { className: "row-roll", text: roll });
element(link, "span", { className: "row-move", text: move });
const mark = element(link, "span", { className: "row-word" });
mark.dataset.verdict = verdict;
mark.append(icon(VERDICT_ICONS[verdict]), word);
link.addEventListener("click", (event) => {
if (event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey) {
return;
}
event.preventDefault();
choose(turn.number);
});
}
}
// ------------------------------------------------- Chiffres du moteur
function renderNumbers(summary: GameSummary): void {
table.replaceChildren();
const cell = (text: string, className = "") => element(table, "span", { className, text });
cell("");
cell(REVIEW_TEXTS.numbersHead.you, "strong");
cell(REVIEW_TEXTS.numbersHead.computer, "strong");
const rows: [string, (s: GameSummary["player"]) => string][] = [
[REVIEW_TEXTS.numbersRows.errorRate, (s) => signed(-s.errorRate.perDecision)],
[REVIEW_TEXTS.numbersRows.decisions, (s) => String(s.errorRate.decisions)],
[REVIEW_TEXTS.numbersRows.level, (s) => MATCH_TEXTS.levels[s.errorRate.level].name],
[REVIEW_TEXTS.numbersRows.luck, (s) => signed(s.luck.perRoll)],
];
for (const [name, value] of rows) {
cell(name);
cell(value(summary.player));
cell(value(summary.computer));
}
}
// ---------------------------------------------------------- Ensemble
function choose(turn: number): void {
if (turn === selected || turn < 1 || turn > turns.length) {
return;
}
selected = turn;
renderCurve();
renderViewer();
renderList();
options.select(turn);
}
function step(delta: number): void {
choose(selected + delta);
}
window.addEventListener("resize", () => {
if (!section.hidden && data !== null) {
renderCurve();
}
});
return {
show(next) {
data = next;
if (next === null) {
message.textContent = REVIEW_TEXTS.missingGame;
curveCard.hidden = true;
viewer.hidden = true;
listCard.hidden = true;
numbers.hidden = true;
return;
}
turns = gameTurns(next.journal);
curve = chanceCurve(next.journal);
const summary = summarizeAnalysis(next.journal);
const fallback = summary.toReview?.turn ?? 1;
selected = Math.min(Math.max(1, next.turn ?? fallback), Math.max(1, turns.length));
message.textContent = turns.length === 0 ? REVIEW_TEXTS.emptyFilter : "";
curveCard.hidden = turns.length === 0;
viewer.hidden = turns.length === 0;
listCard.hidden = turns.length === 0;
numbers.hidden = turns.length === 0;
renderCurve();
renderViewer();
renderList();
renderNumbers(summary);
},
hide() {
data = null;
drawnTurn = "";
player?.stop();
request++;
},
step,
};
}
+454 -21
View File
@@ -21,6 +21,13 @@
// dessine l'écran que désigne l'adresse, au démarrage et à chaque
// changement. Les actions de jeu restent des boutons.
import {
gameTurns,
mainAdvice,
missingAnalyses,
readyForSummary,
summarizeAnalysis,
} from "../domain/analysis/game-analysis.js";
import {
type MasterPhrases,
masterLine,
@@ -29,9 +36,10 @@ import {
} from "../domain/analysis/phrases.js";
import type { Advice } from "../domain/game/advice.js";
import type { Cube } from "../domain/game/cube.js";
import type { MoveNotation } from "../domain/game/engine.js";
import type { GameJournal } from "../domain/game/events.js";
import type { Game, MoveSteps, NewGame, SideBoards } from "../domain/game/game.js";
import { formatHalfMoves, type HalfMove } from "../domain/game/position.js";
import type { HalfMove } from "../domain/game/position.js";
import { type PositionLink, type SharedPosition, setupOf } from "../domain/game/position-link.js";
import type { SavedGameSummary } from "../domain/game/saved-game.js";
import { otherSide, type Side } from "../domain/game/side.js";
@@ -39,6 +47,9 @@ import type { GameState } from "../domain/game/state.js";
import { ADVICE_TEXTS } from "./advice-texts.js";
import { type Analyse, createAdviceTracker } from "./advice-tracker.js";
import { createAdviceView, VERDICT_ICONS } from "./advice-view.js";
import { createAnalysisView } from "./analysis-view.js";
import { createPromptView, type PromptResult } from "./ask-ai.js";
import { ASK_AI_TEXTS } from "./ask-ai-texts.js";
import {
boardModel,
moveTargets,
@@ -74,7 +85,17 @@ import { installPlatform, startInstaller } from "./install.js";
import { MATCH_TEXTS } from "./match-texts.js";
import { replacingLink, startNavigation } from "./navigation.js";
import { createNewGameView } from "./new-game-view.js";
import { isHelpScreen, type Route, routeHash } from "./router.js";
import { showWithNotation } from "./notation.js";
import { createPromptSource, type PromptsAccess } from "./prompt-source.js";
import { createReviewRunner, type RunAnalysis } from "./review-runner.js";
import {
type AiRoute,
isAiRoute,
isHelpScreen,
type Route,
routeHash,
withoutAi,
} from "./router.js";
import {
chosenGame,
isFirstLaunch,
@@ -83,6 +104,7 @@ import {
parseSettings,
type Settings,
} from "./settings.js";
import { createSummaryView } from "./summary-view.js";
import { type PromptText, TEXTS } from "./texts.js";
import { seenAfter } from "./tutorial-nav.js";
import { createTutorialView, type TutorialAccess } from "./tutorial-view.js";
@@ -133,6 +155,11 @@ export interface AppOptions {
/** Le conseil du maître : l'analyse d'une décision du joueur, sur un
* moteur à part (elle ne retarde jamais la partie). */
readonly analyse: Analyse;
/** L'analyse d'une partie pour son bilan (étape 1e), une analyse à la
* fois, sur le même moteur à part. */
readonly analyseGame: RunAnalysis;
/** Les positions que décrivent les prompts pour une IA (étape 1f). */
readonly prompts: PromptsAccess;
}
/** La source des phrases du maître, copiée dans le site (make site). */
@@ -148,6 +175,12 @@ export interface SavedGamesAccess {
/** Une partie reprise, au bout de la branche branchHead si elle est
* donnée ; elle devient la partie à l'écran. */
readonly open: (id: string, branchHead?: string) => Promise<Game>;
/** Une partie enregistrée, reprise pour la regarder (bilan, analyse)
* sans qu'elle devienne la partie à l'écran ; null si elle n'existe
* pas ou est illisible. */
readonly view: (id: string) => Promise<Game | null>;
/** Enregistre les analyses d'une partie qui n'est pas à l'écran. */
readonly saveAnalyses: (id: string, journal: GameJournal) => void;
readonly remove: (id: string) => Promise<void>;
readonly exportSgf: (id: string) => Promise<{ fileName: string; text: string }>;
}
@@ -213,6 +246,9 @@ export function startApp(options: AppOptions): void {
info: byId("info"),
adviceLine: byId<HTMLAnchorElement>("advice-line"),
explainVeil: byId("explain-veil"),
summaryVeil: byId("summary-veil"),
promptVeil: byId("prompt-veil"),
analysis: byId("analysis"),
menuAdvice: byId<HTMLButtonElement>("menu-advice"),
prompt: byId("prompt"),
strips: { computer: stripOf("strip-computer"), player: stripOf("strip-player") },
@@ -409,6 +445,10 @@ export function startApp(options: AppOptions): void {
let stuck = false;
let busy = true;
let info: string = TEXTS.loading;
// La dernière ligne « L'ordinateur a joué … » et le coup qu'elle cite :
// tant qu'elle est la ligne d'information, ce coup mène à la fiche
// « Notation des coups ».
let computerLine: ComputerTurnLine | null = null;
let engineFailed = false;
// Le dernier coup de l'ordinateur, montré (traces, « Revoir ») jusqu'à
// la prochaine action du joueur ; null : rien à montrer.
@@ -612,7 +652,11 @@ export function startApp(options: AppOptions): void {
} else if (computerCouldNotMove(game)) {
ui.info.textContent = TEXTS.computerCannotMove(rollBefore(game));
} else {
ui.info.textContent = info;
showWithNotation(
ui.info,
info,
computerLine?.text === info ? computerLine.notation : null,
);
}
ui.prompt.textContent = panelShown
? ""
@@ -665,6 +709,7 @@ export function startApp(options: AppOptions): void {
document.body.classList.toggle("busy", busy);
announceEnd(game);
void keepScreenOn(isPlaying(game) || state.phase === "doubled");
reviewFinishedGame();
}
/** Le conseil du maître à montrer : le réglage le permet, ses phrases
@@ -841,7 +886,13 @@ export function startApp(options: AppOptions): void {
/** Le panneau centré : fin de partie, ou double de l'ordinateur en
* paysage (en portrait, la barre d'actions s'en charge). */
function renderPanel(g: Game, landscape: boolean, doubled: boolean): void {
const over = g.state.phase === "over" && !panelDismissed;
// Le panneau appartient à l'écran de jeu : ni sur une page, ni sous
// le bilan.
const over =
g.state.phase === "over" &&
!panelDismissed &&
!ui.game.hidden &&
navigation.route.screen !== "summary";
const ask = landscape && doubled;
ui.panelVeil.hidden = !(over || ask);
const overline = byId("panel-overline");
@@ -996,7 +1047,8 @@ export function startApp(options: AppOptions): void {
while (game !== null && game.state.turn === "computer" && isPlaying(game)) {
await refresh();
await game.playComputerTurn();
info = describeComputerTurn(game);
computerLine = await describeComputerTurn(game);
info = computerLine.text;
save();
played = true;
}
@@ -1123,6 +1175,9 @@ export function startApp(options: AppOptions): void {
/** Commence une partie : celle des choix de l'écran « Nouvelle partie »
* si rien d'autre n'est demandé. */
function startNewGame(chosen: NewGame = chosenGame(settings)): void {
// L'analyse d'une partie passée laisse le moteur à part au conseil
// du maître.
reviewRunner.stop();
game = options.newGame(chosen);
panelDismissed = false;
announcedEnd = null;
@@ -1212,7 +1267,8 @@ export function startApp(options: AppOptions): void {
route.screen === "menu" ||
route.screen === "games" ||
route.screen === "install" ||
route.screen === "explanation";
route.screen === "explanation" ||
route.screen === "summary";
// « Mes parties » : reprendre une partie (ou une branche) en change à
// l'écran, sans recharger la page.
@@ -1245,6 +1301,296 @@ export function startApp(options: AppOptions): void {
close: () => leaveSheet(),
});
// ------------------------------------------- Bilan et analyse (1e)
// Les analyses qui manquent à une partie, en arrière-plan, sur le
// moteur à part ; la partie regardée (bilan, analyse) et son journal.
const reviewRunner = createReviewRunner(options.analyseGame);
let reviewed: { id: string; journal: GameJournal; game: Game } | null = null;
const summaryView = createSummaryView({
veil: ui.summaryVeil,
close: () => leaveSheet(),
again: () => afterGame(),
});
const analysisView = createAnalysisView({
section: ui.analysis,
reducedMotion,
select: (turn) => {
const route = navigation.route;
if (route.screen === "analysis") {
navigation.replace(routeHash({ ...route, turn }));
}
},
replay: (id, eventId) => void replayFrom(id, eventId),
back: (link) => leavingLink(link, (route) => route.screen === "analysis"),
});
// ------------------------------------------- Demander à une IA (1f)
// La feuille du prompt, à l'adresse …/ia : à la place de la feuille du
// maître ou du bilan, ou dans sa propre feuille au-dessus de l'analyse et
// du glossaire. Une seule feuille à la fois.
const promptSource = createPromptSource({
access: options.prompts,
phrases: () => phrasesLoading,
glossaryEntry: loadGlossaryEntry,
});
const promptView = createPromptView({
veil: ui.promptVeil,
back: () => closePrompt(),
close: () => closePromptSheet(),
});
// L'adresse de la feuille ouverte (null : fermée).
let promptShown: string | null = null;
/** « ‹ Explication », Échap ou le retour du téléphone : retour à l'écran
* d'où on l'a ouverte. */
function closePrompt(): void {
const route = navigation.route;
promptView.hide();
promptShown = null;
navigation.leave(isAiRoute, isAiRoute(route) ? routeHash(withoutAi(route)) : "#/");
}
/** La croix et « Fermer » : la feuille se ferme. Celle du maître ou le
* bilan, dont elle avait pris la place, se ferme avec elle. */
function closePromptSheet(): void {
const route = navigation.route;
if (route.screen === "explanation" || route.screen === "summary") {
promptView.hide();
promptShown = null;
leaveSheet();
return;
}
closePrompt();
}
/** Ouvre (ou met à jour) la feuille du prompt de l'adresse route. */
function showPrompt(route: AiRoute): void {
promptShown = routeHash(route);
const host =
route.screen === "explanation"
? adviceView.sheet
: route.screen === "summary"
? summaryView.panel
: null;
promptView.show(promptOf(route), {
host,
back: ASK_AI_TEXTS.back[route.screen],
backHref: routeHash(withoutAi(route)),
});
}
/** Le journal de la partie id, pour son bilan ou son analyse : celui de
* la partie à l'écran, ou celui du stockage. */
async function journalOf(id: string): Promise<GameJournal | null> {
const live = liveGame(id);
if (live !== null) {
return live.journal;
}
return reviewed?.id === id ? reviewed.journal : options.games.journal(id);
}
/** Le prompt de l'écran sous la feuille (route sans « /ia »). */
async function promptOf(route: AiRoute): Promise<PromptResult> {
await options.engineReady;
switch (route.screen) {
case "explanation": {
const advice = game?.advice[route.event];
return game === null || advice === undefined
? { message: ASK_AI_TEXTS.noAdvice }
: promptSource.decision(game.journal, advice);
}
case "summary": {
const journal = await journalOf(route.game);
if (journal === null) {
return { message: ASK_AI_TEXTS.missingGame };
}
return readyForSummary(journal)
? promptSource.summary(journal)
: { message: ASK_AI_TEXTS.notReady };
}
case "analysis": {
const journal = await journalOf(route.game);
if (journal === null) {
return { message: ASK_AI_TEXTS.missingGame };
}
// Le coup que montre l'analyse : celui de l'adresse, ou le
// coup à revoir (analysis-view.ts).
const turns = gameTurns(journal);
const fallback = summarizeAnalysis(journal).toReview?.turn ?? 1;
const n = Math.min(Math.max(1, route.turn ?? fallback), Math.max(1, turns.length));
const turn = turns[n - 1];
const advice = turn === undefined ? null : mainAdvice(journal, turn);
return advice === null
? { message: ASK_AI_TEXTS.noAdvice }
: promptSource.decision(journal, advice);
}
case "glossary":
return promptSource.concept(route.term ?? "", game?.journal ?? null);
}
}
/** La partie à l'écran, si c'est la partie id. */
function liveGame(id: string): Game | null {
return game !== null && options.games.shownId() === id ? game : null;
}
/** Ouvre le bilan ou l'analyse de la partie id, et lance ce qui manque
* à son analyse. */
async function openReview(id: string): Promise<void> {
const live = liveGame(id);
if (live !== null) {
reviewed = { id, journal: live.journal, game: live };
} else if (reviewed?.id !== id) {
const [journal, viewed] = await Promise.all([
options.games.journal(id),
options.games.view(id),
]);
reviewed = journal === null || viewed === null ? null : { id, journal, game: viewed };
if (reviewed === null) {
showReview(id, true);
return;
}
}
if (reviewed !== null) {
review(reviewed.id, reviewed.journal);
}
showReview(id, false);
}
/** Lance l'analyse de ce qui manque à la partie id (rien si tout est
* là, ou si elle est déjà en cours). */
function review(id: string, journal: GameJournal): void {
if (missingAnalyses(journal).length === 0) {
return;
}
reviewRunner.start(id, journal, (analysed) => {
const live = liveGame(id);
if (live !== null) {
live.recordAnalyses(analysed);
save();
} else {
options.games.saveAnalyses(id, analysed);
}
if (reviewed?.id === id) {
reviewed = { ...reviewed, journal: live?.journal ?? analysed };
}
showReview(id, false);
render();
});
}
/** L'analyse en cours d'une partie qui n'est ni regardée ni à l'écran
* s'arrête : le moteur à part revient au conseil du maître. */
function stopForeignReview(): void {
const running = reviewRunner.running;
if (running !== null && liveGame(running) === null) {
reviewRunner.stop();
}
}
/** Redessine le bilan ou l'analyse de la partie id, s'ils sont à
* l'écran. */
function showReview(id: string, missing: boolean): void {
const route = navigation.route;
if ((route.screen !== "summary" && route.screen !== "analysis") || route.game !== id) {
return;
}
// La feuille du prompt attendait l'analyse : elle se met à jour.
if (isAiRoute(route) && promptView.isOpen && !promptView.ready) {
showPrompt(route);
}
const live = liveGame(id);
const shown =
missing || reviewed?.id !== id
? null
: { ...reviewed, journal: live?.journal ?? reviewed.journal };
if (route.screen === "summary") {
summaryView.show(
shown === null
? null
: {
id,
journal: shown.journal,
game: shown.game,
end: shown.game.state.phase === "over" ? endParts(shown.game) : null,
afterLabel: live === null ? null : afterGameLabel(live),
phrases,
},
);
} else {
analysisView.show(
shown === null
? null
: {
id,
journal: shown.journal,
game: shown.game,
turn: route.turn,
phrases,
},
);
}
}
/**
* La partie à l'écran vient de finir : son analyse part en
* arrière-plan, et le bilan remplace le panneau de fin de partie dès
* qu'il est prêt (charte 1e), si le panneau est toujours là.
*
* Le bilan s'ouvre un peu plus tard (microtâche) : seulement si cette
* partie finie est encore celle de l'écran. Sinon, « Commencer » de
* l'écran « Nouvelle partie » ouvrait le bilan de l'ancienne partie
* par-dessus la nouvelle, qui venait de commencer entre-temps (défaut
* signalé le 2026-11-11).
*/
function reviewFinishedGame(): void {
const id = options.games.shownId();
const finished = game;
if (finished === null || id === null || busy || finished.state.phase !== "over") {
return;
}
// L'analyse d'une autre partie, regardée, passe d'abord.
const running = reviewRunner.running;
if (running === null || running === id) {
review(id, finished.journal);
}
if (
navigation.route.screen === "game" &&
!panelDismissed &&
phrases !== null &&
readyForSummary(finished.journal)
) {
queueMicrotask(() => {
if (
game === finished &&
options.games.shownId() === id &&
navigation.route.screen === "game" &&
!panelDismissed
) {
navigation.go(routeHash({ screen: "summary", game: id }));
}
});
}
}
/** « Rejouer d'ici » : la partie id reprend à l'événement eventId ; le
* prochain coup ouvre une branche, la partie d'origine reste. */
async function replayFrom(id: string, eventId: string): Promise<void> {
if (busy) {
return;
}
reviewRunner.stop();
const other = await options.games.open(id);
other.goBackTo(eventId);
hideBanner();
navigation.replace("#/");
await act(() => showGame(other));
}
/** Joue un demi-coup du joueur ; le coup attend ensuite sa suite ou sa
* validation. Le pion qui se pose vibre (deux fois s'il frappe). */
function playHalfMove(halfMove: HalfMove): void {
@@ -1372,6 +1718,8 @@ export function startApp(options: AppOptions): void {
navigation.leave((r) => r.screen === "position");
} else if (route.screen === "newGame") {
navigation.leave((r) => r.screen === "newGame");
} else if (route.screen === "analysis") {
navigation.leave((r) => r.screen === "analysis");
} else if (route.screen === "tutorial" || route.screen === "tutorialEnd") {
navigation.leave((r) => r.screen === "tutorial" || r.screen === "tutorialEnd");
}
@@ -1415,6 +1763,11 @@ export function startApp(options: AppOptions): void {
ui.installVeil.hidden = true;
gamesView?.hide();
adviceView.hide();
if (summaryView.isOpen) {
// Le bilan fermé laisse voir la partie finie, sans le panneau.
panelDismissed = true;
summaryView.hide();
}
if (menuWasOpen) {
(menuReturnFocus ?? ui.menuButton).focus();
}
@@ -1510,6 +1863,8 @@ export function startApp(options: AppOptions): void {
let menuReturnFocus: HTMLElement | null = null;
// L'écran sous la feuille d'installation : le dernier écran affiché.
let underSheet: Route = { screen: "game" };
// L'événement de la feuille d'explication ouverte.
let explained: string | null = null;
/** Dessine l'écran que désigne l'adresse (ADR 0013, amendement). */
function applyRoute(route: Route): void {
@@ -1524,7 +1879,8 @@ export function startApp(options: AppOptions): void {
const home = below.screen === "home";
const tutorial = below.screen === "tutorial" || below.screen === "tutorialEnd";
const choosing = below.screen === "newGame";
const page = help || position || home || tutorial || choosing;
const analysing = below.screen === "analysis";
const page = help || position || home || tutorial || choosing || analysing;
const wasPage = ui.game.hidden;
const wasScreen = ui.root.dataset.screen;
ui.game.hidden = page;
@@ -1532,6 +1888,7 @@ export function startApp(options: AppOptions): void {
ui.position.hidden = !position;
ui.home.hidden = !home;
ui.tutorial.hidden = !tutorial;
ui.analysis.hidden = !analysing;
const opening = choosing && ui.newGameSection.hidden;
ui.newGameSection.hidden = !choosing;
ui.root.classList.toggle("page-open", page);
@@ -1587,10 +1944,38 @@ export function startApp(options: AppOptions): void {
if (route.screen === "explanation") {
closeTransient();
ui.menuVeil.hidden = true;
void adviceView.show(route.event);
// Ouvrir ou fermer la feuille du prompt ne redessine pas
// l'explication dessous.
if (ui.explainVeil.hidden || explained !== route.event) {
explained = route.event;
void adviceView.show(route.event);
}
} else {
explained = null;
adviceView.hide();
}
// Le bilan et l'analyse d'une partie : son journal, lu dans le
// stockage (ouvert avec le moteur), puis analysé en arrière-plan.
if (route.screen !== "summary" && summaryView.isOpen) {
// Quitter le bilan (pour l'analyse, ou par le retour du
// téléphone) laisse la partie finie sans le panneau.
panelDismissed = true;
summaryView.hide();
}
if (!analysing) {
analysisView.hide();
}
if (route.screen === "summary" || route.screen === "analysis") {
closeTransient();
ui.menuVeil.hidden = true;
const id = route.game;
void options.engineReady.then(
() => openReview(id),
() => undefined,
);
} else {
stopForeignReview();
}
if (route.screen === "games") {
const expanded = route.game;
// La liste vient du stockage, ouvert avec le moteur.
@@ -1620,6 +2005,18 @@ export function startApp(options: AppOptions): void {
shownPosition = null;
}
// La feuille du prompt pour une IA, au-dessus de son écran.
if (isAiRoute(route)) {
closeTransient();
ui.menuVeil.hidden = true;
if (!promptView.isOpen || promptShown !== routeHash(route)) {
showPrompt(route);
}
} else if (promptView.isOpen) {
promptView.hide();
promptShown = null;
}
// Une adresse inconnue : la partie, avec un message, à l'adresse de
// la partie.
if (route.screen === "unknown") {
@@ -1641,8 +2038,10 @@ export function startApp(options: AppOptions): void {
welcomed: () => saveSettings(welcomed()),
});
// L'écran « Nouvelle partie » : « Commencer » remplace son adresse par
// celle de la partie (le retour du téléphone ne le rouvre pas).
// L'écran « Nouvelle partie » : « Commencer » lance la partie, puis
// remplace son adresse par celle de la partie (le retour du téléphone
// ne le rouvre pas). Dans cet ordre : l'écran de jeu ne se redessine
// jamais avec l'ancienne partie, finie, et son panneau de fin.
const newGameView = createNewGameView({
section: ui.newGameSection,
settings: () => settings,
@@ -1651,8 +2050,8 @@ export function startApp(options: AppOptions): void {
if (busy || game === null) {
return;
}
navigation.replace("#/");
newGame(chosenGame(settings));
navigation.replace("#/");
},
});
leavingLink(newGameView.closeLink, (route) => route.screen === "newGame");
@@ -2057,8 +2456,26 @@ export function startApp(options: AppOptions): void {
if (event.altKey || event.metaKey || (event.ctrlKey && event.key.toLowerCase() !== "z")) {
return;
}
// La feuille du prompt ouverte : Échap la ferme, et rien d'autre ne
// répond (les flèches font défiler le texte).
if (promptView.isOpen) {
if (event.key === "Escape") {
event.preventDefault();
closePrompt();
}
return;
}
const onButton =
event.target instanceof HTMLButtonElement || event.target instanceof HTMLAnchorElement;
// L'écran d'analyse : les flèches passent d'un coup à l'autre.
if (
navigation.route.screen === "analysis" &&
(event.key === "ArrowLeft" || event.key === "ArrowRight")
) {
event.preventDefault();
analysisView.step(event.key === "ArrowLeft" ? -1 : 1);
return;
}
let name: ActionName | null = null;
switch (event.key) {
case " ":
@@ -2143,6 +2560,12 @@ export function startApp(options: AppOptions): void {
if (route.screen === "explanation") {
void adviceView.show(route.event);
}
if (isAiRoute(route)) {
showPrompt(route);
}
if (route.screen === "summary" || route.screen === "analysis") {
void openReview(route.game);
}
// Comme après une action du joueur : l'ordinateur joue si c'est
// à lui (partie nouvelle ou reprise pendant son tour). Une partie
// reprise juste après son coup le montre, sans l'animer.
@@ -2263,21 +2686,30 @@ async function computerMoveToShow(game: Game): Promise<MoveSteps | null> {
return game.lastMoveSteps();
}
/** Ce qu'a fait l'ordinateur pendant son tour (sans durée de calcul). */
function describeComputerTurn(game: Game): string {
/** La ligne d'information après le tour de l'ordinateur, et le coup
* qu'elle cite (null s'il n'a pas joué de coup). */
interface ComputerTurnLine {
readonly text: string;
readonly notation: MoveNotation | null;
}
/** Ce qu'a fait l'ordinateur pendant son tour (sans durée de calcul). Son
* coup s'écrit dans la notation du moteur, comme dans l'analyse. */
async function describeComputerTurn(game: Game): Promise<ComputerTurnLine> {
const last = game.events.at(-1);
if (last?.type === "CubeOffered") {
return "";
return { text: "", notation: null };
}
const played = game.events.findLast((e) => e.type === "MovePlayed");
if (played?.type !== "MovePlayed") {
return "";
return { text: "", notation: null };
}
const dice = rollBefore(game);
if (played.halfMoves.length === 0) {
return TEXTS.computerCannotMove(dice);
return { text: TEXTS.computerCannotMove(dice), notation: null };
}
return TEXTS.computerMoved(dice, formatHalfMoves(played.halfMoves));
const notation = await game.moveNotation(played.id);
return { text: TEXTS.computerMoved(dice, notation), notation };
}
/** Le résultat d'une partie finie, en deux parties : le titre du panneau
@@ -2290,6 +2722,7 @@ function endParts(game: Game): { title: string; detail: string } {
}
const { winner, kind, points } = result;
const dropped = game.events.some((e) => e.type === "CubeDropped");
const how = dropped ? TEXTS.droppedDouble(winner) : "";
const { match, matchAfter } = game.state;
if (match !== null && matchAfter !== null) {
const { player, computer } = matchAfter.score;
@@ -2304,13 +2737,13 @@ function endParts(game: Game): { title: string; detail: string } {
return {
title: matchAfter.over
? MATCH_TEXTS.matchWonTitle(winner)
: TEXTS.endTitle(winner, kind, dropped),
detail: matchAfter.crawford ? `${detail} ${MATCH_TEXTS.crawfordNext}` : detail,
: TEXTS.endTitle(winner, kind),
detail: `${how}${matchAfter.crawford ? `${detail} ${MATCH_TEXTS.crawfordNext}` : detail}`,
};
}
return {
title: TEXTS.endTitle(winner, kind, dropped),
detail: TEXTS.endDetail(winner, points, game.state.cube.value),
title: TEXTS.endTitle(winner, kind),
detail: `${how}${TEXTS.endDetail(winner, points, game.state.cube.value)}`,
};
}
+30
View File
@@ -0,0 +1,30 @@
// Les textes de l'interface de « Demander à une IA » (étape 1f). Les
// prompts eux-mêmes sont dans docs/prompts/ (une seule source, ADR 0008).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
export const ASK_AI_TEXTS = {
button: "Demander à une IA",
title: "Demander à une IA",
lead: "Une question toute prête, avec la position et les chiffres de GNU Backgammon. Relisez-la, copiez-la, puis collez-la dans l'IA de votre choix : le moteur décide, l'IA explique.",
textLabel: "Le prompt, à relire avant de le copier",
copy: "Copier le prompt",
copied: "Copié",
notCopied:
"Le navigateur refuse la copie : le texte est sélectionné, copiez-le avec le menu de votre téléphone.",
preparing: "Préparation du prompt…",
close: "Fermer",
/** « ‹ Explication » : l'écran d'où l'on vient, pour y revenir. */
back: {
explanation: "Explication",
summary: "Bilan",
analysis: "Analyse",
glossary: "Glossaire",
},
failed: "Le prompt n'a pas pu être préparé.",
noAdvice: "Pas de prompt pour cette décision : le maître ne l'a pas encore analysée.",
notReady: "Le maître analyse encore la partie : le prompt sera prêt avec le bilan.",
missingGame: "Cette partie n'est plus sur ce téléphone.",
missingTerm: "Ce terme n'est pas dans le glossaire.",
} as const;
+310
View File
@@ -0,0 +1,310 @@
// « Demander à une IA » (étape 1f ; charte, ecrans-etape-1.md, « 1f ») :
// le bouton, secondaire, avec l'icône de copie ; et la feuille du prompt
// (…/ia, ADR 0013), où le texte se relit avant d'être copié.
//
// Une seule feuille à la fois (recette de 1f) : ouverte depuis la feuille du
// maître ou le bilan, la page du prompt prend la place de leur contenu, à la
// même hauteur, avec « ‹ Explication » (ou « ‹ Bilan ») pour y revenir ;
// depuis l'analyse ou le glossaire, qui ne sont pas des feuilles, elle monte
// dans sa propre feuille. La copie passe par navigator.clipboard ; à défaut,
// le texte est sélectionné dans la feuille et copié par le navigateur, ou
// laissé sélectionné pour être copié à la main. Le bouton la confirme
// (« ✓ Copié », 2 s).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// L'application n'appelle aucune IA et n'envoie rien : elle copie un texte.
import { ASK_AI_TEXTS } from "./ask-ai-texts.js";
import { icon } from "./icons.js";
/** Durée de « ✓ Copié » sur le bouton (charte : 2 s). */
export const COPIED_MS = 2000;
/** Ce que montre la feuille : le prompt, ou pourquoi il n'y en a pas. */
export type PromptResult = { readonly text: string } | { readonly message: string };
/** Classe de la page du prompt, posée dans une autre feuille. */
const PAGE_CLASS = "prompt-page";
/** Le bouton « Demander à une IA » : un lien vers la feuille du prompt. */
export function askAiLink(parent: HTMLElement, id: string, href: string): HTMLAnchorElement {
const link = document.createElement("a");
link.id = id;
link.className = "button secondary ask-ai";
link.href = href;
link.append(icon("copy"), ASK_AI_TEXTS.button);
parent.append(link);
return link;
}
/** Vide une feuille qui peut accueillir la page du prompt, sans l'ôter. */
export function clearSheet(sheet: HTMLElement): void {
for (const child of [...sheet.children]) {
if (!child.classList.contains(PAGE_CLASS)) {
child.remove();
}
}
}
/** D'où l'on vient : la feuille dont la page prend la place (null : sa
* propre feuille) et le nom de l'écran, pour « ‹ Explication ». */
export interface PromptPlace {
readonly host: HTMLElement | null;
readonly back: string;
/** L'adresse de l'écran d'où l'on vient (le lien de « ‹ … »). */
readonly backHref: string;
}
export interface PromptViewOptions {
/** Le voile de sa propre feuille (index.html) ; elle est construite ici. */
readonly veil: HTMLElement;
/** « ‹ Explication » : revenir à l'écran d'où l'on vient. */
readonly back: () => void;
/** La croix et « Fermer » : fermer la feuille. */
readonly close: () => void;
}
export interface PromptView {
/** Ouvre la feuille (ou la met à jour) sur un prompt en préparation. */
show(prompt: Promise<PromptResult>, place: PromptPlace): void;
hide(): void;
readonly isOpen: boolean;
/** Le prompt est affiché (pas un message). */
readonly ready: boolean;
}
function element<K extends keyof HTMLElementTagNameMap>(
parent: HTMLElement,
tag: K,
options: { id?: string; className?: string; text?: string } = {},
): HTMLElementTagNameMap[K] {
const child = document.createElement(tag);
if (options.id !== undefined) {
child.id = options.id;
}
if (options.className !== undefined) {
child.className = options.className;
}
if (options.text !== undefined) {
child.textContent = options.text;
}
parent.append(child);
return child;
}
export function createPromptView(options: PromptViewOptions): PromptView {
const { veil } = options;
// Sa propre feuille, pour l'analyse et le glossaire.
const sheet = element(veil, "div", { id: "prompt-sheet", className: "sheet prompt-sheet" });
veil.addEventListener("click", (event) => {
if (event.target === veil) {
options.close();
}
});
// La page du prompt, posée dans sa feuille ou dans celle d'où l'on vient.
const page = element(sheet, "div", { id: "prompt-page", className: PAGE_CLASS });
page.setAttribute("role", "dialog");
page.setAttribute("aria-modal", "true");
page.setAttribute("aria-labelledby", "prompt-title");
const head = element(page, "div", { className: "sheet-head prompt-head" });
element(head, "span", { className: "grip" }).setAttribute("aria-hidden", "true");
const back = element(head, "a", { id: "prompt-back", className: "prompt-back" });
back.addEventListener("click", (event) => {
if (event.button !== 0 || event.ctrlKey || event.metaKey || event.shiftKey) {
return;
}
event.preventDefault();
options.back();
});
const closeIcon = element(head, "button", { id: "prompt-close", className: "icon-button" });
closeIcon.type = "button";
closeIcon.append(icon("close"));
closeIcon.setAttribute("aria-label", ASK_AI_TEXTS.close);
closeIcon.onclick = () => options.close();
element(page, "h2", { id: "prompt-title", className: "sheet-title", text: ASK_AI_TEXTS.title });
element(page, "p", { className: "prompt-lead", text: ASK_AI_TEXTS.lead });
const text = element(page, "pre", { id: "prompt-text", className: "prompt-text" });
text.tabIndex = 0;
text.setAttribute("aria-label", ASK_AI_TEXTS.textLabel);
const status = element(page, "p", { id: "prompt-status", className: "prompt-status" });
status.setAttribute("role", "status");
const actions = element(page, "div", { className: "prompt-actions" });
const done = element(actions, "button", {
id: "prompt-done",
className: "secondary",
text: ASK_AI_TEXTS.close,
});
done.type = "button";
done.onclick = () => options.close();
const copy = element(actions, "button", { id: "prompt-copy" });
copy.type = "button";
// Le libellé du bouton est annoncé quand il passe à « Copié ».
const copyLabel = document.createElement("span");
copyLabel.setAttribute("aria-live", "polite");
// Chaque ouverture a son numéro : un prompt qui arrive après une autre
// ouverture, ou après la fermeture, n'est pas montré.
let opened = 0;
let ready = false;
let open = false;
// La feuille d'où l'on vient, dont la page a pris la place.
let host: HTMLElement | null = null;
let copiedTimeout: ReturnType<typeof setTimeout> | null = null;
/** « Copier le prompt », ou « ✓ Copié » pendant 2 s. */
function showCopied(copied: boolean): void {
if (copiedTimeout !== null) {
clearTimeout(copiedTimeout);
copiedTimeout = null;
}
copy.classList.toggle("copied", copied);
copyLabel.textContent = copied ? ASK_AI_TEXTS.copied : ASK_AI_TEXTS.copy;
copy.replaceChildren(icon(copied ? "verdictGood" : "copy"), copyLabel);
if (copied) {
copiedTimeout = setTimeout(() => showCopied(false), COPIED_MS);
}
}
showCopied(false);
/** Pose la page dans la feuille d'où l'on vient, ou dans la sienne. */
function place(next: HTMLElement | null): void {
if (host !== next) {
host?.classList.remove("prompting");
host = next;
}
if (next === null) {
if (page.parentElement !== sheet) {
sheet.append(page);
}
veil.hidden = false;
return;
}
veil.hidden = true;
// La page couvre la feuille telle qu'elle s'affiche, défilée en haut.
next.scrollTop = 0;
next.classList.add("prompting");
if (page.parentElement !== next) {
next.append(page);
}
}
/** Le texte de la feuille, sélectionné : le repli quand le
* presse-papiers n'est pas accessible. */
function selectText(): void {
const selection = window.getSelection();
if (selection === null) {
return;
}
const range = document.createRange();
range.selectNodeContents(text);
selection.removeAllRanges();
selection.addRange(range);
}
async function copyText(): Promise<boolean> {
try {
await navigator.clipboard.writeText(text.textContent ?? "");
return true;
} catch {
// Hors contexte sûr (http sur le réseau local), ou refusé :
// repli ci-dessous.
}
selectText();
try {
return document.execCommand("copy");
} catch {
return false;
}
}
copy.onclick = async () => {
if (!ready) {
return;
}
const id = opened;
const copied = await copyText();
if (id !== opened) {
return;
}
if (copied) {
status.textContent = "";
showCopied(true);
} else {
selectText();
showCopied(false);
status.textContent = ASK_AI_TEXTS.notCopied;
}
};
return {
show(prompt, where) {
const id = ++opened;
const opening = !open || host !== where.host;
open = true;
back.textContent = `‹ ${where.back}`;
back.href = where.backHref;
place(where.host);
if (opening) {
ready = false;
text.textContent = "";
text.hidden = true;
copy.disabled = true;
showCopied(false);
status.textContent = ASK_AI_TEXTS.preparing;
delete page.dataset.ready;
back.focus();
}
prompt.then(
(result) => {
if (id !== opened) {
return;
}
if ("text" in result) {
ready = true;
text.textContent = result.text;
text.hidden = false;
copy.disabled = false;
status.textContent = "";
page.dataset.ready = "true";
} else {
ready = false;
text.hidden = true;
copy.disabled = true;
status.textContent = result.message;
delete page.dataset.ready;
}
},
() => {
if (id === opened) {
ready = false;
copy.disabled = true;
status.textContent = ASK_AI_TEXTS.failed;
}
},
);
},
hide() {
opened++;
ready = false;
if (!open) {
return;
}
open = false;
showCopied(false);
host?.classList.remove("prompting");
host = null;
veil.hidden = true;
sheet.append(page);
text.textContent = "";
delete page.dataset.ready;
},
get isOpen() {
return open;
},
get ready() {
return ready;
},
};
}
+37
View File
@@ -156,6 +156,43 @@ export function pointSlot(number: number): { top: boolean; column: number } {
return { top: true, column: number - 13 };
}
/**
* Le jan intérieur d'un camp : ses six dernières flèches avant la sortie,
* numérotées du point de vue du joueur (1 à 6 pour lui, 19 à 24 pour
* l'ordinateur), dans le sens de marche du camp. Pur dessin : le moteur
* reste seul juge des règles qui en dépendent (sortie, rentrée).
* Glossaire : docs/glossaire/jan-interieur.md
*/
export interface HomeBoard {
readonly side: Side;
readonly points: readonly number[];
}
/**
* Le jan extérieur d'un camp : les six flèches qui précèdent son jan
* intérieur (7 à 12 pour le joueur, 13 à 18 pour l'ordinateur), dans le sens
* de marche du camp.
* Glossaire : docs/glossaire/jan-exterieur.md
*/
export interface OuterBoard {
readonly side: Side;
readonly points: readonly number[];
}
/** Six flèches d'un camp, de sa flèche first à first - 5 dans sa propre
* numérotation, renumérotées pour le joueur. */
function sixPoints(side: Side, first: number): number[] {
return Array.from({ length: 6 }, (_, i) => (side === "player" ? first - i : 25 - (first - i)));
}
export function homeBoard(side: Side): HomeBoard {
return { side, points: sixPoints(side, 6) };
}
export function outerBoard(side: Side): OuterBoard {
return { side, points: sixPoints(side, 12) };
}
/** Le plateau de la position de départ, pour le dessiner avant que le
* moteur soit chargé (première ouverture) : chaque camp a 2 pions sur sa case
* 24, 5 sur la 13, 3 sur la 8 et 5 sur la 6 ; 167 points chacun. Une donnée,
+4 -10
View File
@@ -303,23 +303,17 @@ function drawPoint(
"data-point": number,
points: `${left},${base} ${left + g.pointWidth},${base} ${center},${tip}`,
});
// Numéros : sur le cadre en paysage, dans la bande centrale en
// portrait. Leur taille (12 px au moins à l'écran) dépend de l'échelle
// Numéros : sur le cadre, bandes haute et basse, en portrait comme en
// paysage. Leur taille (12 px au moins à l'écran) dépend de l'échelle
// du dessin : c'est une mesure du dessin, comme x et y.
const size = g.numberSize;
let y: number;
if (g.layout === "landscape") {
y = top ? g.edge / 2 + size * 0.36 : g.height - g.edge / 2 + size * 0.36;
} else {
y = top ? middle - g.die / 2 - 4 : middle + g.die / 2 + 4 + size * 0.72;
}
add(
svg,
"text",
{
class: g.layout === "landscape" ? "point-number on-frame" : "point-number",
class: "point-number",
x: center,
y,
y: top ? g.edge / 2 + size * 0.36 : g.height - g.edge / 2 + size * 0.36,
"font-size": size,
},
String(number),
+1
View File
@@ -28,6 +28,7 @@ export const GAMES_TEXTS = {
close: "Fermer",
resume: "Reprendre",
showBranches: "Branches",
summary: "Bilan",
resumeBranch: "Reprendre cette branche",
exportSgf: "Exporter (SGF)",
remove: "Supprimer",
+10
View File
@@ -123,6 +123,7 @@ export function createGamesView(options: GamesViewOptions): GamesView {
"resume",
),
branchesLink(game.id),
...(game.status === "over" ? [summaryLink(game.id)] : []),
button(
GAMES_TEXTS.exportSgf,
run(async () => download(await options.exportSgf(game.id))),
@@ -171,6 +172,15 @@ export function createGamesView(options: GamesViewOptions): GamesView {
return link;
}
/** « Bilan » : le lien vers le bilan d'une partie finie (étape 1e). */
function summaryLink(id: string): HTMLAnchorElement {
const link = element("a", "button secondary");
link.textContent = GAMES_TEXTS.summary;
link.dataset.action = "summary";
link.href = routeHash({ screen: "summary", game: id });
return link;
}
async function renderBranches(id: string, target: HTMLElement): Promise<void> {
const journal = await options.journal(id);
const all = journal === null ? [] : branches(journal);
+10 -5
View File
@@ -25,7 +25,7 @@ export interface Geometry {
readonly height: number;
/** Épaisseur du cadre sur les côtés. */
readonly frame: number;
/** Hauteur du cadre en haut et en bas : la bande des numéros en paysage. */
/** Hauteur du cadre en haut et en bas : la bande des numéros des flèches. */
readonly edge: number;
/** Colonne de commandes à gauche (0 en portrait). */
readonly left: number;
@@ -95,14 +95,19 @@ export function boardGeometry(layout: Layout, aspect: number, pxPerUnit: number)
arrowWidth: 2.5 / pxPerUnit,
};
if (layout === "portrait") {
// Les mesures du plateau d'origine : flèches de 44, pions de 20.
// Les mesures du plateau d'origine : flèches de 44. Les bandes haute
// et basse du cadre portent les numéros des flèches, comme en
// paysage (12 px au moins à l'écran) : pions de 19 au plus. La bande ne
// dépasse pas 36 unités : sur une miniature (moins de 275 px de
// large), les numéros rapetissent plutôt que d'écraser les flèches.
const frame = 8;
const edge = Math.min(36, Math.max(24, numberSize + 8));
const tray = 48;
const bar = 40;
const width = 640;
const pointWidth = (width - 3 * frame - tray - bar) / 12;
const band = 84;
const radius = Math.min(pointWidth / 2 - 2, (height / 2 - frame - band / 2) / 10);
const radius = Math.min(pointWidth / 2 - 2, (height / 2 - edge - band / 2) / 10);
const x0 = frame;
const barLeft = x0 + 6 * pointWidth;
return {
@@ -110,7 +115,7 @@ export function boardGeometry(layout: Layout, aspect: number, pxPerUnit: number)
width,
height,
frame,
edge: frame,
edge,
left: 0,
tray,
bar,
@@ -123,7 +128,7 @@ export function boardGeometry(layout: Layout, aspect: number, pxPerUnit: number)
rightHalf: barLeft + bar,
trayLeft: barLeft + bar + 6 * pointWidth + frame,
target,
numberSize,
numberSize: Math.min(numberSize, edge - 8),
bandFont: atLeast(13.5, pxPerUnit, 17),
chipFont: atLeast(13.5, pxPerUnit, 17),
...sizes,
+17 -3
View File
@@ -13,6 +13,7 @@
// que dit la réponse, ne s'affichent pas
// (docs/identite/charte/accueil-tutoriel-aide.md, « Aide »).
import { askAiLink } from "./ask-ai.js";
import {
type GlossaryEntry,
type HelpFeature,
@@ -31,6 +32,8 @@ export const FEATURES = [
"docs/scenarios/jouer-une-partie.feature",
"docs/scenarios/jouer-un-match.feature",
"docs/scenarios/comprendre-mes-coups.feature",
"docs/scenarios/revoir-ma-partie.feature",
"docs/scenarios/demander-a-une-ia.feature",
"docs/scenarios/apprendre-les-regles.feature",
"docs/scenarios/mes-parties.feature",
"docs/scenarios/partager-une-position.feature",
@@ -123,7 +126,10 @@ export function createHelpView(container: HTMLElement, tabs: HTMLElement): HelpV
notice.className = "help-notice";
notice.setAttribute("role", "status");
const questions: Question[] = [];
const terms = new Map<string, { dt: HTMLElement; card: HTMLElement; entry: GlossaryCard }>();
const terms = new Map<
string,
{ dt: HTMLElement; card: HTMLElement; entry: GlossaryCard; askAi: HTMLAnchorElement }
>();
let loading: Promise<boolean> | null = null;
// La question ouverte au dernier affichage : refermée, elle reste en vue.
let lastOpen: Question | null = null;
@@ -212,7 +218,14 @@ export function createHelpView(container: HTMLElement, tabs: HTMLElement): HelpV
a.href = routeHash({ screen: "glossary", term: other.name });
});
}
terms.set(entry.name, { dt, card, entry });
// « Demander à une IA » (étape 1f), sur la fiche ouverte.
const askAi = askAiLink(
dd,
`glossary-ask-ai-${entry.name}`,
routeHash({ screen: "glossary", term: entry.name, ai: true }),
);
askAi.hidden = true;
terms.set(entry.name, { dt, card, entry, askAi });
}
search.addEventListener("input", () => {
let shown = 0;
@@ -306,7 +319,8 @@ export function createHelpView(container: HTMLElement, tabs: HTMLElement): HelpV
q.section.classList.toggle("open", open);
}
const term = route.screen === "glossary" ? route.term : null;
for (const [name, { dt, card }] of terms) {
for (const [name, { dt, card, askAi }] of terms) {
askAi.hidden = name !== term;
dt.classList.toggle("current", name === term);
card.classList.toggle("current", name === term);
if (name === term) {
+3 -2
View File
@@ -94,14 +94,15 @@ export const HOME_TEXTS = {
drop: "Passer",
tutorialLoading: "Chargement du tutoriel…",
tutorialFailed: "Le tutoriel n'a pas pu se charger.",
pathLabel: "Le sens du jeu de vos pions, en pointillés",
pathLabel:
"Le sens du jeu : la flèche claire pour vos pions, la sombre pour ceux de l'ordinateur",
/** Le résultat d'une partie finie par le coup illustré (étape 7). */
illustratedEnd: (kind: ResultKind) =>
kind === "single"
? "Partie finie : l'ordinateur avait sorti des pions, c'est une partie simple."
: kind === "gammon"
? "Partie finie : l'ordinateur n'a sorti aucun pion, c'est un gammon."
: "Partie finie : il reste un pion de l'ordinateur dans votre camp, c'est un backgammon.",
: "Partie finie : il reste un pion de l'ordinateur dans votre jan intérieur, c'est un backgammon.",
computerDoubles: "L'ordinateur double.",
// Aide
+1 -1
View File
@@ -57,7 +57,7 @@ export const MATCH_TEXTS = {
advice: "Conseil du maître",
adviceDetail: "Une ligne après chacun de vos coups",
startGame: "Commencer la partie",
startMatch: (n: number) => `Commencer le match en ${n} points`,
startMatch: "Commencer le match",
kept: "Vos choix sont gardés pour la prochaine fois.",
// Score du match sur l'écran de jeu
+109
View File
@@ -0,0 +1,109 @@
// Un petit plateau qui rejoue un coup pion par pion, sur la position
// d'avant le coup, puis laisse ses traces : la feuille d'explication du
// maître (1d), le coup à revoir du bilan et le visualiseur de l'analyse
// (1e).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import type { MoveSteps } from "../domain/game/game.js";
import { boardModel, moveTrace, placeOf } from "./board-model.js";
import { checkerSpot, NO_MARKS, renderBoard, slideChecker } from "./board-view.js";
import { boardGeometry, PORTRAIT_ASPECT } from "./geometry.js";
const SLIDE_MS = 160;
const PAUSE_MS = 120;
/** Un plateau SVG vide, dans son cadre. */
export function boardSvg(box: HTMLElement, id: string, className: string): SVGSVGElement {
const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
svg.id = id;
svg.setAttribute("class", `board ${className}`);
svg.setAttribute("role", "img");
box.append(svg);
return svg;
}
/**
* Dessine le plateau d'un coup après index demi-coups (0 : avant le
* coup), avec ses traces si traced. Les flèches des traces renvoient à leur
* pointe par identifiant : prefix les distingue de celles du plateau de jeu.
*/
export function drawSteps(
svg: SVGSVGElement,
steps: MoveSteps,
index: number,
traced: boolean,
prefix: string,
): void {
const boards = steps.boards[index];
if (boards === undefined) {
return;
}
const width = svg.getBoundingClientRect().width || 358;
renderBoard(svg, boardGeometry("portrait", PORTRAIT_ASPECT, width / 640), boardModel(boards), {
...NO_MARKS,
dice: [],
cube: null,
band: null,
controls: null,
trace: traced ? moveTrace(steps.side, steps.halfMoves, steps.hits) : null,
});
for (const marker of svg.querySelectorAll("marker[id]")) {
marker.id = `${prefix}${marker.id}`;
}
for (const path of svg.querySelectorAll("[marker-end]")) {
const ref = path.getAttribute("marker-end") ?? "";
path.setAttribute("marker-end", ref.replace("url(#", `url(#${prefix}`));
}
}
/** Un plateau qui joue des coups ; un coup demandé arrête le précédent. */
export interface MovePlayer {
/** Joue le coup pion par pion (sans mouvement si le système le
* demande), puis laisse ses traces. */
play(steps: MoveSteps): Promise<void>;
/** Arrête le coup en cours. */
stop(): void;
}
export function createMovePlayer(
svg: SVGSVGElement,
prefix: string,
reducedMotion: MediaQueryList,
): MovePlayer {
let playing = 0;
return {
async play(steps) {
const id = ++playing;
drawSteps(svg, steps, 0, false, prefix);
if (!reducedMotion.matches) {
for (const [i, halfMove] of steps.halfMoves.entries()) {
if (id !== playing) {
return;
}
if (i > 0) {
await new Promise((resolve) => setTimeout(resolve, PAUSE_MS));
}
const from = placeOf(steps.side, halfMove.from);
const to = placeOf(steps.side, halfMove.to);
drawSteps(svg, steps, i, false, prefix);
const start = checkerSpot(svg, from);
const bar = steps.side === "player" ? "bar-computer" : "bar-player";
const victim = steps.hits[i] === true ? checkerSpot(svg, to) : null;
drawSteps(svg, steps, i + 1, false, prefix);
await Promise.all([
start && slideChecker(svg, to, start, SLIDE_MS),
victim && slideChecker(svg, bar, victim, SLIDE_MS),
]);
}
}
if (id === playing) {
drawSteps(svg, steps, steps.halfMoves.length, true, prefix);
}
},
stop() {
playing++;
},
};
}
+5 -4
View File
@@ -26,8 +26,9 @@ export interface Navigation {
replace(hash: string): void;
/** Quitte l'écran courant : revient à la dernière adresse de l'onglet
* qui ne vérifie pas stay, ou, s'il n'y en a pas (lien ouvert dans un
* nouvel onglet), remplace l'adresse par celle de la partie. */
leave(stay: (route: Route) => boolean): void;
* nouvel onglet), remplace l'adresse par fallback (celle de la partie,
* par défaut). */
leave(stay: (route: Route) => boolean, fallback?: string): void;
}
interface TrailState {
@@ -123,13 +124,13 @@ export function startNavigation(onChange: (route: Route) => void): Navigation {
},
go,
replace,
leave(stay) {
leave(stay, fallback = "#/") {
if (leaving !== null) {
return; // déjà en route
}
const steps = stepsBack(trail, stay);
if (steps === null) {
replace("#/");
replace(fallback);
return;
}
// Au cas où le navigateur ne reviendrait pas (historique
+1 -3
View File
@@ -200,9 +200,7 @@ export function createNewGameView(options: NewGameViewOptions): NewGameView {
levelName.textContent = MATCH_TEXTS.levels[s.level].name;
levelText.textContent = MATCH_TEXTS.levels[s.level].text;
advice.setAttribute("aria-checked", String(s.masterAdvice));
start.textContent = isMatch
? MATCH_TEXTS.startMatch(s.matchLength)
: MATCH_TEXTS.startGame;
start.textContent = isMatch ? MATCH_TEXTS.startMatch : MATCH_TEXTS.startGame;
start.disabled = busy;
},
focus() {
+34
View File
@@ -0,0 +1,34 @@
// Un coup écrit dans la notation du moteur (« 24/22* 6/1 », « 8/4(2) »),
// touchable vers sa fiche du glossaire : un débutant y apprend ce que
// veulent dire l'étoile, « off », « bar » et « (2) ».
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import type { MoveNotation } from "../domain/game/engine.js";
import { routeHash } from "./router.js";
/** La fiche du glossaire de la notation (docs/glossaire/, sans .md). */
export const NOTATION_TERM = "notation-des-coups";
/**
* Remplace le contenu de parent par text, où la première occurrence de
* notation devient un lien vers la fiche « Notation des coups ». Sans
* notation dans le texte, le texte seul.
*/
export function showWithNotation(
parent: HTMLElement,
text: string,
notation: MoveNotation | null,
): void {
const at = notation === null || notation === "" ? -1 : text.indexOf(notation);
if (notation === null || at < 0) {
parent.textContent = text;
return;
}
const link = document.createElement("a");
link.className = "notation";
link.href = routeHash({ screen: "glossary", term: NOTATION_TERM });
link.textContent = notation;
parent.replaceChildren(text.slice(0, at), link, text.slice(at + notation.length));
}
+132
View File
@@ -0,0 +1,132 @@
// Les prompts pour une IA tels que les demande l'interface (étape 1f) :
// les gabarits, lus dans la copie de docs/prompts/ faite par make site
// (ADR 0008), les phrases du maître, et les positions que le domaine lit
// avec le moteur (PromptsAccess, branché par main.ts). Le remplissage
// lui-même est dans le domaine (domain/prompts/prompts.ts).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import type { MasterPhrases } from "../domain/analysis/phrases.js";
import type { Advice } from "../domain/game/advice.js";
import type { GameJournal } from "../domain/game/events.js";
import type { PromptPosition } from "../domain/prompts/position.js";
import {
type ConceptExample,
conceptPrompt,
decisionPrompt,
summaryPrompt,
} from "../domain/prompts/prompts.js";
import {
PROMPT_FILES,
PROMPT_KINDS,
type PromptTemplates,
parsePromptTemplate,
} from "../domain/prompts/templates.js";
import type { PromptResult } from "./ask-ai.js";
import { ASK_AI_TEXTS } from "./ask-ai-texts.js";
import type { GlossaryEntry } from "./help-text.js";
/** La copie des gabarits dans le site (make site). */
const PROMPTS_DIR = "docs/prompts/";
/** Ce que les prompts demandent au domaine et au moteur : la position à
* décrire. */
export interface PromptsAccess {
/** La position d'avant une décision de la partie. */
readonly before: (journal: GameJournal, eventId: string) => Promise<PromptPosition>;
/** La position que montre le prompt du bilan (coup à revoir, ou
* position finale). */
readonly summary: (journal: GameJournal) => Promise<PromptPosition>;
/** La position d'exemple d'un concept et son évaluation. */
readonly concept: (journal: GameJournal | null) => Promise<ConceptExample>;
}
export interface PromptSourceOptions {
readonly access: PromptsAccess;
readonly phrases: () => Promise<MasterPhrases>;
/** Une fiche du glossaire, par son nom de fichier. */
readonly glossaryEntry: (file: string) => Promise<GlossaryEntry | null>;
}
export interface PromptSource {
/** Le prompt d'une décision du joueur (coup ou videau). */
decision(journal: GameJournal, advice: Advice): Promise<PromptResult>;
/** Le prompt du bilan d'une partie finie et analysée. */
summary(journal: GameJournal): Promise<PromptResult>;
/** Le prompt d'un terme du glossaire (nom de sa fiche, sans .md). */
concept(term: string, journal: GameJournal | null): Promise<PromptResult>;
}
async function fetchText(url: string): Promise<string> {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`${url} : ${response.status}`);
}
return response.text();
}
export function createPromptSource(options: PromptSourceOptions): PromptSource {
let loading: Promise<PromptTemplates> | null = null;
/** Les gabarits, lus une fois (une nouvelle tentative après un
* échec). */
function templates(): Promise<PromptTemplates> {
loading ??= Promise.all(
PROMPT_KINDS.map(async (kind) =>
parsePromptTemplate(await fetchText(PROMPTS_DIR + PROMPT_FILES[kind])),
),
).then(
([move, cube, summary, concept, exercises]) => ({
move: move ?? "",
cube: cube ?? "",
summary: summary ?? "",
concept: concept ?? "",
exercises: exercises ?? "",
}),
(error: unknown) => {
loading = null;
throw error;
},
);
return loading;
}
return {
async decision(journal, advice) {
const [all, phrases, position] = await Promise.all([
templates(),
options.phrases(),
options.access.before(journal, advice.eventId),
]);
return { text: decisionPrompt(all, phrases, { journal, advice, position }) };
},
async summary(journal) {
const [all, phrases, position] = await Promise.all([
templates(),
options.phrases(),
options.access.summary(journal),
]);
return { text: summaryPrompt(all, phrases, { journal, position }) };
},
async concept(term, journal) {
const [all, entry, example] = await Promise.all([
templates(),
options.glossaryEntry(`${term}.md`).catch(() => null),
options.access.concept(journal),
]);
if (entry === null) {
return { message: ASK_AI_TEXTS.missingTerm };
}
return {
text: conceptPrompt(all, {
term: entry.term,
english: entry.english,
brief: entry.brief,
journal,
example,
}),
};
},
};
}
+87
View File
@@ -0,0 +1,87 @@
// L'analyse d'une partie en arrière-plan (étape 1e) : les analyses qui
// manquent au bilan et à l'écran d'analyse sont demandées une à une au
// second moteur, rangées au fur et à mesure, et l'ensemble s'arrête dès
// qu'on n'en a plus besoin (une autre partie, une nouvelle partie). Sans
// DOM : testé sous Node (app/tests/review-runner.test.ts).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// Une analyse déjà partie vers le moteur ne s'interrompt pas : l'arrêt
// prend effet entre deux analyses, et le résultat d'une analyse arrêtée
// n'est pas rangé.
import { type AnalysisTask, missingAnalyses } from "../domain/analysis/game-analysis.js";
import type { GameJournal } from "../domain/game/events.js";
/** Fait une analyse et renvoie le journal qui la contient. */
export type RunAnalysis = (journal: GameJournal, task: AnalysisTask) => Promise<GameJournal>;
export interface ReviewRunner {
/** La partie en cours d'analyse (null : aucune). */
readonly running: string | null;
/**
* Analyse ce qui manque au journal de la partie id ; record reçoit le
* journal après chaque analyse rangée, done une fois tout analysé.
* Une analyse en cours d'une autre partie est arrêtée ; la même partie
* continue sans repartir.
*/
start(
id: string,
journal: GameJournal,
record: (journal: GameJournal) => void,
done?: () => void,
): void;
/** Arrête l'analyse en cours. */
stop(): void;
}
export function createReviewRunner(run: RunAnalysis): ReviewRunner {
// Chaque analyse lancée a son jeton : stop() ou une autre partie
// l'annulent.
let token: object | null = null;
let running: string | null = null;
return {
get running() {
return running;
},
start(id, journal, record, done) {
if (running === id && token !== null) {
return;
}
const mine = {};
token = mine;
running = id;
void (async () => {
let current = journal;
try {
for (;;) {
const task = missingAnalyses(current)[0];
if (task === undefined) {
break;
}
const next = await run(current, task);
if (token !== mine) {
return;
}
current = next;
record(current);
}
} catch {
// Le moteur a échoué : l'analyse s'arrête là, ce qui est
// rangé reste, et la prochaine demande reprendra.
}
if (token === mine) {
token = null;
running = null;
done?.();
}
})();
},
stop() {
token = null;
running = null;
},
};
}
+95
View File
@@ -0,0 +1,95 @@
// Les textes de l'interface du bilan et de l'écran d'analyse (étape 1e).
// Les phrases du maître elles-mêmes (lecture du bilan, dés en mots) sont
// dans docs/maitre/phrases.md (une seule source, ADR 0008).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import type { CubeAction } from "../domain/game/engine.js";
import type { Roll } from "../domain/game/roll.js";
const plural = (n: number, one: string, many: string) => (n > 1 ? many : one);
/** « 41 % » et « +0,021 » : la même écriture que les prompts
* (domain/analysis/numbers.ts). */
export {
formatEquity as signed,
formatPercent as percent,
} from "../domain/analysis/numbers.js";
export const REVIEW_TEXTS = {
// Bilan
summaryLabel: "Bilan de la partie",
analysing: "Le maître analyse la partie…",
progress: (done: number, total: number) => `Analyse : ${done} sur ${total}`,
notOver: "Cette partie n'est pas finie : son bilan viendra à la fin.",
missingGame: "Cette partie n'est plus sur ce téléphone.",
counts: {
good: (n: number) => plural(n, "Bon coup", "Bons coups"),
doubtful: (n: number) => plural(n, "Imprécision", "Imprécisions"),
bad: (n: number) => plural(n, "Erreur", "Erreurs"),
},
countsLabel: "Vos décisions, par appréciation",
yourPlay: "Votre jeu",
theDice: "Les dés",
playGauge: (level: string) => `Votre jeu : niveau ${level}`,
diceGauge: (words: string) => `Les dés : ${words}`,
howToRead: "Comment lire ces mesures",
toReview: "Le coup à revoir",
yourMove: (notation: string) => `Votre coup : ${notation}`,
yourDecision: (action: string) => `Votre décision : ${action}`,
reviewMove: "Revoir ce coup",
seeAnalysis: "Voir l'analyse",
newGame: "Nouvelle partie",
close: "Fermer",
cubeActions: {
double: "doubler",
noDouble: "lancer sans doubler",
take: "prendre",
pass: "passer",
} satisfies Record<CubeAction, string>,
toReviewBoard: "La position au moment de la décision à revoir.",
// Analyse
analysisTitle: "Analyse de la partie",
back: "Retour",
curveTitle: "Vos chances de gagner",
curveLabel: (turn: number, total: number, chance: string) =>
`Courbe de vos chances de gagner : coup ${turn} sur ${total}, ${chance}. Flèches gauche et droite pour changer de coup.`,
curveUnknown: "pas encore calculé",
turnOf: (turn: number, total: number) => `Coup ${turn} sur ${total}`,
roll: (roll: Roll) => `${roll[0]}-${roll[1]}`,
previous: "Coup précédent",
next: "Coup suivant",
who: { player: "Vous", computer: "L'ordinateur" },
computerPlayed: (notation: string) => `L'ordinateur a joué ${notation}.`,
computerCannotMove: "L'ordinateur ne pouvait pas jouer.",
playerCannotMove: "Vous ne pouviez pas jouer.",
computerCube: "L'ordinateur a doublé.",
chanceAfter: (chance: string) => `Vos chances de gagner après ce coup : ${chance}`,
theirMove: "Son coup",
masterMove: "Le coup du maître",
yourMoveSegment: "Votre coup",
choiceLabel: "Coup montré sur le plateau",
legendMove: (who: string, notation: string) =>
`${who} : ${notation}, joué pion par pion sur la position d'avant le coup.`,
legendPosition: "La position avant la décision.",
replayFromHere: "Rejouer d'ici",
replayHint: "Une nouvelle branche : la partie d'origine reste intacte.",
listTitle: "Les coups à revoir",
filters: { all: "Tout", errors: "Erreurs", doubtful: "Imprécisions" },
filterLabel: "Filtrer les coups",
emptyFilter: "Aucun coup de ce genre dans la partie.",
rowLabel: (turn: number, roll: string, move: string, word: string) =>
`Coup ${turn}, ${roll}, ${move} : ${word}`,
numbers: "Voir les chiffres du moteur",
numbersRows: {
errorRate: "Erreur par décision",
decisions: "Décisions comptées",
luck: "Chance par tour",
level: "Niveau",
},
numbersHead: { you: "Vous", computer: "L'ordinateur" },
numbersNote:
"Calculés comme GNU Backgammon : équité perdue par décision non forcée, chance des dés par tour, à 2 plis.",
} as const;
+87 -4
View File
@@ -14,8 +14,9 @@ export type Route =
| { readonly screen: "home" }
/** #/aide, et une question ouverte : #/aide/<identifiant>. */
| { readonly screen: "help"; readonly question: string | null }
/** #/glossaire, et un terme : #/glossaire/<fiche sans .md>. */
| { readonly screen: "glossary"; readonly term: string | null }
/** #/glossaire, et un terme : #/glossaire/<fiche sans .md> ; son
* prompt pour une IA : #/glossaire/<fiche>/ia. */
| { readonly screen: "glossary"; readonly term: string | null; readonly ai?: boolean }
/** #/a-propos. */
| { readonly screen: "about" }
/** #/tutoriel, une étape : #/tutoriel/<n>, et son écran « à vous » :
@@ -27,13 +28,27 @@ export type Route =
| { readonly screen: "install" }
/** #/parties, et une partie : #/parties/<identifiant>. */
| { readonly screen: "games"; readonly game: string | null }
/** #/parties/<identifiant>/bilan : le bilan de fin de partie (1e) ;
* son prompt pour une IA : #/parties/<identifiant>/bilan/ia (1f). */
| { readonly screen: "summary"; readonly game: string; readonly ai?: boolean }
/** #/parties/<identifiant>/analyse/<coup> : l'écran d'analyse, placé
* sur un coup (un tour de la partie, à partir de 1) ; sans coup :
* #/parties/<identifiant>/analyse ; le prompt du coup pour une IA :
* #/parties/<identifiant>/analyse/<coup>/ia (1f). */
| {
readonly screen: "analysis";
readonly game: string;
readonly turn: number | null;
readonly ai?: boolean;
}
/** #/menu. */
| { readonly screen: "menu" }
/** #/nouvelle-partie : le choix de la partie (type, niveau, conseil). */
| { readonly screen: "newGame" }
/** #/explication/<événement> : la feuille d'explication du maître sur
* une décision de la partie en cours (étape 1d). */
| { readonly screen: "explanation"; readonly event: string }
* une décision de la partie en cours (étape 1d) ; son prompt pour une
* IA : #/explication/<événement>/ia (1f). */
| { readonly screen: "explanation"; readonly event: string; readonly ai?: boolean }
/** #/position/<Position ID>/<Match ID> (Match ID facultatif). */
| { readonly screen: "position"; readonly position: string; readonly match: string | null }
/** Une adresse que l'application ne connaît pas. */
@@ -65,12 +80,20 @@ export function parseRoute(hash: string): Route {
if (rest.at(-1) === "") {
rest.pop();
}
// La feuille du prompt pour une IA (étape 1f) : « /ia » au bout de
// l'adresse de l'écran d'où on la demande.
if (rest.length > 1 && rest.at(-1) === "ia") {
return aiRoute(parseRoute(`#/${[head, ...rest.slice(0, -1)].join("/")}`)) ?? unknown;
}
if (head === "position") {
return positionRoute(rest.join("/")) ?? unknown;
}
if (head === "tutoriel") {
return tutorialRoute(rest) ?? unknown;
}
if (head === "parties" && rest.length > 1) {
return gameReviewRoute(rest) ?? unknown;
}
if (rest.length > 1) {
return unknown;
}
@@ -104,6 +127,55 @@ export function parseRoute(hash: string): Route {
}
}
/** Les écrans qui ont une feuille de prompt pour une IA. */
export type AiRoute = Extract<
Route,
{ screen: "explanation" | "summary" | "analysis" | "glossary" }
>;
/** L'écran, avec sa feuille de prompt ouverte (null : écran sans prompt). */
function aiRoute(route: Route): AiRoute | null {
switch (route.screen) {
case "explanation":
case "summary":
case "analysis":
return route.ai === true ? null : { ...route, ai: true };
case "glossary":
return route.term === null || route.ai === true ? null : { ...route, ai: true };
default:
return null;
}
}
/** La feuille du prompt pour une IA est-elle ouverte ? */
export function isAiRoute(route: Route): route is AiRoute {
return "ai" in route && route.ai === true;
}
/** L'écran sous la feuille du prompt. */
export function withoutAi(route: AiRoute): AiRoute {
const { ai: _, ...below } = route;
return below;
}
/** #/parties/<id>/bilan, #/parties/<id>/analyse, #/parties/<id>/analyse/<n>. */
function gameReviewRoute(rest: readonly string[]): Route | null {
const [game = "", part, turn, ...more] = rest;
if (!NAME.test(game) || more.length > 0) {
return null;
}
if (part === "bilan") {
return turn === undefined ? { screen: "summary", game } : null;
}
if (part !== "analyse") {
return null;
}
if (turn === undefined) {
return { screen: "analysis", game, turn: null };
}
return /^[1-9][0-9]{0,3}$/.test(turn) ? { screen: "analysis", game, turn: Number(turn) } : null;
}
/** #/tutoriel, #/tutoriel/<n>, #/tutoriel/<n>/a-vous, #/tutoriel/fin. */
function tutorialRoute(rest: readonly string[]): Route | null {
const [name, part, ...more] = rest;
@@ -152,6 +224,11 @@ function positionRoute(text: string): Route | null {
/** Le fragment d'un écran, # compris. */
export function routeHash(route: Route): string {
const hash = screenHash(route);
return isAiRoute(route) ? `${hash}/ia` : hash;
}
function screenHash(route: Route): string {
switch (route.screen) {
case "game":
return "#/";
@@ -173,6 +250,12 @@ export function routeHash(route: Route): string {
return "#/installer";
case "games":
return route.game === null ? "#/parties" : `#/parties/${route.game}`;
case "summary":
return `#/parties/${route.game}/bilan`;
case "analysis":
return route.turn === null
? `#/parties/${route.game}/analyse`
: `#/parties/${route.game}/analyse/${route.turn}`;
case "menu":
return "#/menu";
case "newGame":
+371
View File
@@ -0,0 +1,371 @@
// Le bilan de fin de partie (#/parties/<id>/bilan, étape 1e ; charte,
// ecrans-etape-1.md, « Bilan ») : un panneau centré sur un voile, à la
// place du panneau de fin de partie. Le résultat et sa lecture, les
// décisions par appréciation, deux jauges (votre jeu, les dés), le coup à
// revoir, puis « Voir l'analyse » et l'action qui suit la partie.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// Tout ce qu'il affiche vient de l'analyse du moteur (game-analysis.ts) et
// des phrases du maître (docs/maitre/phrases.md) ; tant que l'analyse
// n'est pas prête, il dit où elle en est.
import {
type GameSummary,
readyForSummary,
summarizeAnalysis,
} from "../domain/analysis/game-analysis.js";
import {
diceWords,
type MasterPhrases,
masterWords,
nothingToReview,
summaryReading,
} from "../domain/analysis/phrases.js";
import { masterCubeAction } from "../domain/game/advice.js";
import type { GameJournal } from "../domain/game/events.js";
import type { Game } from "../domain/game/game.js";
import { COMPUTER_LEVELS } from "../domain/game/level.js";
import { VERDICT_ICONS } from "./advice-view.js";
import { askAiLink, clearSheet } from "./ask-ai.js";
import { icon } from "./icons.js";
import { MATCH_TEXTS } from "./match-texts.js";
import { boardSvg, drawSteps } from "./move-board.js";
import { REVIEW_TEXTS } from "./review-texts.js";
import { routeHash } from "./router.js";
import { TEXTS } from "./texts.js";
/** Ce que montre le bilan. */
export interface SummaryData {
readonly id: string;
readonly journal: GameJournal;
/** La partie, pour dessiner la position du coup à revoir. */
readonly game: Game;
/** Le titre et le détail du résultat (null : partie pas finie). */
readonly end: { readonly title: string; readonly detail: string } | null;
/** L'action qui suit la partie, si c'est la partie à l'écran :
* « Rejouer » ou « Partie suivante ». Sinon, « Nouvelle partie » mène à
* l'écran des choix. */
readonly afterLabel: string | null;
readonly phrases: MasterPhrases | null;
}
export interface SummaryViewOptions {
/** Le voile du bilan (index.html) ; le panneau est construit ici. */
readonly veil: HTMLElement;
/** La croix : revenir au plateau. */
readonly close: () => void;
/** « Rejouer » ou « Partie suivante ». */
readonly again: () => void;
}
export interface SummaryView {
/** Ouvre (ou met à jour) le bilan. */
show(data: SummaryData | null): void;
hide(): void;
readonly isOpen: boolean;
/** Le panneau, où la page du prompt prend la place du bilan (1f). */
readonly panel: HTMLElement;
}
function element<K extends keyof HTMLElementTagNameMap>(
parent: HTMLElement,
tag: K,
options: { id?: string; className?: string; text?: string } = {},
): HTMLElementTagNameMap[K] {
const child = document.createElement(tag);
if (options.id !== undefined) {
child.id = options.id;
}
if (options.className !== undefined) {
child.className = options.className;
}
if (options.text !== undefined) {
child.textContent = options.text;
}
parent.append(child);
return child;
}
const DICE_SIDE = {
veryLucky: "for-2",
lucky: "for-1",
none: "even",
unlucky: "against-1",
veryUnlucky: "against-2",
} as const;
export function createSummaryView(options: SummaryViewOptions): SummaryView {
const { veil } = options;
const panel = element(veil, "div", { id: "summary", className: "panel summary-panel" });
panel.setAttribute("role", "dialog");
panel.setAttribute("aria-modal", "true");
panel.setAttribute("aria-labelledby", "summary-title");
veil.addEventListener("click", (event) => {
if (event.target === veil) {
options.close();
}
});
// Ce qui est dessiné, pour ne redessiner qu'en cas de changement (le
// bilan est mis à jour à chaque analyse rangée).
let drawn = "";
function render(data: SummaryData | null): void {
const ready = data !== null && data.phrases !== null && readyForSummary(data.journal);
const summary = ready ? summarizeAnalysis(data.journal) : null;
// Seulement ce que le bilan montre : les analyses qui arrivent
// ensuite en arrière-plan pour l'écran d'analyse (coups de
// l'ordinateur, chances de gagner) ne le redessinent pas, sinon le
// panneau et son mini-plateau sauteraient sous les yeux du joueur.
const shown =
summary === null || data === null || data.phrases === null
? null
: {
counts: summary.counts,
level: summary.player.errorRate.level,
dice: summary.player.luck.rating,
reading: summaryReading(data.phrases, summary),
toReview: summary.toReview?.advice.eventId ?? null,
turn: summary.toReview?.turn ?? null,
};
const key =
data === null
? "missing"
: [
data.id,
data.end?.title ?? "",
data.end?.detail ?? "",
data.afterLabel ?? "",
ready,
JSON.stringify(shown),
].join("|");
if (key === drawn) {
return;
}
drawn = key;
clearSheet(panel);
delete panel.dataset.ready;
const head = element(panel, "div", { className: "summary-head" });
element(head, "p", { className: "overline", text: TEXTS.endOverline });
const close = element(head, "button", { id: "summary-close", className: "icon-button" });
close.type = "button";
close.append(icon("close"));
close.setAttribute("aria-label", REVIEW_TEXTS.close);
close.onclick = () => options.close();
const title = element(panel, "h2", { id: "summary-title", className: "summary-title" });
if (data === null) {
title.textContent = REVIEW_TEXTS.summaryLabel;
element(panel, "p", { className: "summary-reading", text: REVIEW_TEXTS.missingGame });
return;
}
if (data.end === null) {
title.textContent = REVIEW_TEXTS.summaryLabel;
element(panel, "p", { className: "summary-reading", text: REVIEW_TEXTS.notOver });
actions(data);
return;
}
title.textContent = data.end.title;
const reading = element(panel, "p", {
id: "summary-reading",
className: "summary-reading",
});
reading.textContent =
summary !== null && data.phrases !== null
? `${data.end.detail} ${summaryReading(data.phrases, summary)}`
: data.end.detail;
if (summary === null || data.phrases === null) {
const status = element(panel, "p", {
id: "summary-status",
className: "summary-status",
text: REVIEW_TEXTS.analysing,
});
status.setAttribute("role", "status");
actions(data);
return;
}
panel.dataset.ready = "true";
counts(summary);
gauges(summary, data.phrases);
toReview(data, summary, data.phrases);
actions(data);
}
function counts(summary: GameSummary): void {
const box = element(panel, "div", { id: "summary-counts", className: "summary-counts" });
box.setAttribute("role", "list");
box.setAttribute("aria-label", REVIEW_TEXTS.countsLabel);
const cells = [
{ verdict: "good", n: summary.counts.good, word: REVIEW_TEXTS.counts.good },
{
verdict: "doubtful",
n: summary.counts.doubtful,
word: REVIEW_TEXTS.counts.doubtful,
},
{
verdict: "bad",
n: summary.counts.bad + summary.counts.veryBad,
word: REVIEW_TEXTS.counts.bad,
},
] as const;
for (const cell of cells) {
const item = element(box, "div", { className: "summary-count" });
item.setAttribute("role", "listitem");
item.dataset.verdict = cell.verdict;
element(item, "span", { className: "summary-number", text: String(cell.n) });
const word = element(item, "span", { className: "summary-word" });
word.append(icon(VERDICT_ICONS[cell.verdict]), cell.word(cell.n));
}
}
function gauges(summary: GameSummary, phrases: MasterPhrases): void {
const box = element(panel, "div", { className: "summary-gauges" });
const level = summary.player.errorRate.level;
const levelName = MATCH_TEXTS.levels[level].name;
const play = element(box, "div", { id: "gauge-play", className: "gauge" });
play.setAttribute("aria-label", REVIEW_TEXTS.playGauge(levelName));
play.setAttribute("role", "img");
element(play, "span", { className: "gauge-name", text: REVIEW_TEXTS.yourPlay });
const track = element(play, "span", { className: "gauge-track" });
element(track, "span", {
className: `gauge-fill level-${COMPUTER_LEVELS.indexOf(level) + 1}`,
});
element(play, "span", { className: "gauge-value", text: levelName });
const words = diceWords(phrases, summary.player.luck.rating);
const dice = element(box, "div", { id: "gauge-dice", className: "gauge" });
dice.setAttribute("aria-label", REVIEW_TEXTS.diceGauge(words));
dice.setAttribute("role", "img");
element(dice, "span", { className: "gauge-name", text: REVIEW_TEXTS.theDice });
const centred = element(dice, "span", { className: "gauge-track centred" });
element(centred, "span", {
className: `gauge-fill dice ${DICE_SIDE[summary.player.luck.rating]}`,
});
element(dice, "span", { className: "gauge-value", text: words });
const link = element(box, "a", {
id: "summary-glossary",
className: "link-button summary-glossary",
text: REVIEW_TEXTS.howToRead,
});
link.href = routeHash({ screen: "glossary", term: "taux-d-erreur" });
}
function toReview(data: SummaryData, summary: GameSummary, phrases: MasterPhrases): void {
const card = element(panel, "section", {
id: "summary-review",
className: "summary-review",
});
card.setAttribute("aria-labelledby", "summary-review-title");
element(card, "h3", {
id: "summary-review-title",
className: "overline",
text: REVIEW_TEXTS.toReview,
});
const reviewed = summary.toReview;
if (reviewed === null) {
element(card, "p", { className: "summary-none", text: nothingToReview(phrases) });
return;
}
const advice = reviewed.advice;
const words = masterWords(phrases, advice);
const body = element(card, "div", { className: "summary-review-body" });
const box = element(body, "div", { className: "summary-board-box" });
const svg = boardSvg(box, "summary-board", "summary-board");
svg.setAttribute("aria-label", REVIEW_TEXTS.toReviewBoard);
const halfMoves = advice.kind === "move" ? advice.played.halfMoves : [];
void data.game
.stepsBefore(advice.eventId, "player", halfMoves)
.then((steps) => drawSteps(svg, steps, steps.halfMoves.length, true, "summary-"))
.catch(() => undefined);
const text = element(body, "div", { className: "summary-review-text" });
const verdict = element(text, "p", { className: "summary-verdict" });
verdict.dataset.verdict = words.verdict;
verdict.append(icon(VERDICT_ICONS[words.verdict]), `${words.word} · ${words.context}`);
element(text, "p", {
className: "summary-played",
text:
advice.kind === "move"
? REVIEW_TEXTS.yourMove(advice.played.notation)
: REVIEW_TEXTS.yourDecision(REVIEW_TEXTS.cubeActions[advice.action]),
});
element(text, "p", {
className: "summary-master",
text:
advice.kind === "move" || masterCubeAction(advice) !== advice.action
? words.title
: words.phrase,
});
const links = element(card, "div", { className: "summary-review-actions" });
const revisit = element(links, "a", {
id: "summary-revisit",
className: "button secondary",
text: REVIEW_TEXTS.reviewMove,
});
revisit.href = routeHash({ screen: "analysis", game: data.id, turn: reviewed.turn });
// « Demander à une IA » (étape 1f) : le prompt du bilan.
const slot = element(links, "div", { className: "ask-ai-slot" });
slot.dataset.slot = "ask-ai";
askAiLink(
slot,
"summary-ask-ai",
routeHash({ screen: "summary", game: data.id, ai: true }),
);
}
function actions(data: SummaryData): void {
// Les actions et le lien des réglages, ensemble : en paysage, en bas
// de la colonne de droite.
const end = element(panel, "div", { className: "summary-end" });
const bar = element(end, "div", { className: "panel-actions summary-actions" });
const analysis = element(bar, "a", {
id: "summary-analysis",
className: "button secondary",
text: REVIEW_TEXTS.seeAnalysis,
});
analysis.href = routeHash({ screen: "analysis", game: data.id, turn: null });
if (data.afterLabel !== null) {
const again = element(bar, "button", {
id: "summary-primary",
text: data.afterLabel,
});
again.type = "button";
again.onclick = () => options.again();
const settings = element(end, "a", {
id: "summary-settings",
className: "panel-link",
text: MATCH_TEXTS.changeSettings,
});
settings.href = routeHash({ screen: "newGame" });
} else {
const start = element(bar, "a", {
id: "summary-primary",
className: "button",
text: REVIEW_TEXTS.newGame,
});
start.href = routeHash({ screen: "newGame" });
}
}
return {
show(data) {
const opening = veil.hidden;
veil.hidden = false;
render(data);
if (opening) {
panel.querySelector<HTMLElement>("#summary-close")?.focus();
}
},
hide() {
if (!veil.hidden) {
veil.hidden = true;
clearSheet(panel);
delete panel.dataset.ready;
drawn = "";
}
},
get isOpen() {
return !veil.hidden;
},
panel,
};
}
+12 -9
View File
@@ -136,15 +136,18 @@ export const TEXTS = {
// Fin de partie
gameOver: "Partie finie",
endOverline: "Fin de partie",
/** Titre du panneau de fin : qui gagne, et comment. */
endTitle: (winner: "player" | "computer", kind: ResultKind, dropped: boolean) => {
if (dropped) {
return winner === "player" ? "L'ordinateur passe" : "Vous passez";
}
return winner === "player"
/** Titre du panneau de fin et du bilan : toujours l'issue, qui gagne
* et comment (un double passé se dit dans le détail). */
endTitle: (winner: "player" | "computer", kind: ResultKind) =>
winner === "player"
? `Vous gagnez ${RESULT_KIND[kind]}`
: `L'ordinateur gagne ${RESULT_KIND[kind]}`;
},
: `L'ordinateur gagne ${RESULT_KIND[kind]}`,
/** Avant le détail des points, quand la partie finit sur un double
* passé : « Vous avez passé son double : 1 point pour lui. ». */
droppedDouble: (winner: "player" | "computer") =>
winner === "player"
? "L'ordinateur a passé votre double : "
: "Vous avez passé son double : ",
/** « 8 points pour lui, videau à 4. » */
endDetail: (winner: "player" | "computer", n: number, cube: number) =>
`${points(n)} pour ${winner === "player" ? "vous" : "lui"}${
@@ -185,7 +188,7 @@ export const TEXTS = {
) =>
[
winner === null
? "Vous avez la main : vos pions ivoire, en bas."
? "Vous avez la main : vos pions blancs, en bas."
: `La partie est finie dans cette position : ${
winner === "player" ? "vous gagnez" : "l'ordinateur gagne"
}.`,
+1 -1
View File
@@ -24,7 +24,7 @@ export interface TutorialScreen {
readonly roll: readonly [number, number] | null;
/** Explication : le coup illustré, en notation de gnubg. */
readonly move: string | null;
/** Explication : le sens du jeu dessiné en pointillés. */
/** Explication : le sens du jeu, deux flèches circulaires. */
readonly path: boolean;
/** « À vous » : les coups justes, en notation de gnubg. */
readonly expected: readonly string[];
+62 -45
View File
@@ -18,11 +18,14 @@ import type { Side } from "../domain/game/side.js";
import type { PracticeVerdict, TutorialBoard } from "../domain/learning/tutorial.js";
import {
boardModel,
homeBoard,
moveTargets,
moveTrace,
onlyHalfMove,
outerBoard,
type Place,
placeOf as placeOfChecker,
pointSlot,
} from "./board-model.js";
import {
type BoardDecor,
@@ -149,57 +152,71 @@ export function fillParagraph(target: HTMLElement, paragraph: Paragraph): void {
const SVG_NS = "http://www.w3.org/2000/svg";
/** Le sens du jeu des pions du joueur, en pointillés : du haut à droite
* (flèche 24) vers la gauche, puis en bas jusqu'à la flèche 1 et la sortie.
* Tracé sous les pions et sous les numéros des flèches, qu'il ne cache
* jamais. pxPerUnit : pixels à l'écran par unité du dessin (le liseré
* ivoire fait 8 px, les points 4 px, quelle que soit la taille). */
function drawPath(svg: SVGSVGElement, g: Geometry, pxPerUnit: number): void {
/** Le sens du jeu : deux flèches circulaires, une claire pour les pions du
* joueur (du haut à droite vers la gauche, puis en bas jusqu'à son jan
* intérieur), une sombre pour ceux de l'ordinateur, en sens inverse et à
* l'intérieur de la première. Chacune a un liseré de la couleur opposée et
* finit par une pointe ; jamais en brique (la brique veut dire « à faire »).
* Dessinées sous les pions, qu'elles ne cachent jamais. pxPerUnit : pixels
* à l'écran par unité du dessin (trait de 5 px sur un liseré de 9 px,
* quelle que soit la taille du plateau). */
function drawDirections(svg: SVGSVGElement, g: Geometry, pxPerUnit: number): void {
const px = (n: number) => n / pxPerUnit;
const center = (column: number) => columnLeft(g, column) + g.pointWidth / 2;
const top = g.height * 0.3;
const bottom = g.height * 0.7;
const right = center(11);
const left = center(0) - g.pointWidth * 0.25;
const turn = g.pointWidth * 0.6;
const end = g.trayLeft + g.tray * 0.25;
const d =
`M ${right} ${top} L ${left + turn} ${top} Q ${left} ${top} ${left} ${top + turn} ` +
`L ${left} ${bottom - turn} Q ${left} ${bottom} ${left + turn} ${bottom} L ${end} ${bottom}`;
const group = document.createElementNS(SVG_NS, "g");
group.setAttribute("class", "tutorial-path");
group.setAttribute("role", "img");
group.setAttribute("aria-label", HOME_TEXTS.pathLabel);
const px = (n: number) => n / pxPerUnit;
const width = px(4);
for (const [className, stroke] of [
["path-edge", px(8)],
["path-dots", width],
] as const) {
const path = document.createElementNS(SVG_NS, "path");
path.setAttribute("class", className);
path.setAttribute("d", d);
path.setAttribute("stroke-width", String(stroke));
if (className === "path-dots") {
path.setAttribute("stroke-dasharray", `0.1 ${px(10)}`);
// Chaque flèche part du jan intérieur adverse (sa flèche 24), longe les
// deux jans extérieurs, tourne au bout du sien et finit dans son jan
// intérieur. Celle de l'ordinateur passe à l'intérieur de la claire.
const column = (point: number) => pointSlot(point).column;
const loops = [
{
side: "player",
from: g.height * 0.29,
to: g.height * 0.71,
left: center(column(outerBoard("player").points[0] ?? 12)) - g.pointWidth * 0.1,
},
{
side: "computer",
from: g.height * 0.62,
to: g.height * 0.38,
left: center(column(outerBoard("computer").points[0] ?? 13) + 1) + g.pointWidth * 0.5,
},
] as const;
const head = px(18);
const half = px(10);
for (const { side, from, to, left } of loops) {
const other = side === "player" ? "computer" : "player";
const start = center(column(homeBoard(other).points[5] ?? 1));
const end = center(column(homeBoard(side).points[4] ?? 2)) + g.pointWidth * 0.3;
const turn = Math.min(Math.abs(to - from) / 2, g.pointWidth * 0.9);
const down = to > from ? 1 : -1;
const d =
`M ${start} ${from} L ${left + turn} ${from} Q ${left} ${from} ${left} ${from + down * turn} ` +
`L ${left} ${to - down * turn} Q ${left} ${to} ${left + turn} ${to} L ${end - head / 2} ${to}`;
for (const [part, stroke] of [
["edge", px(9)],
["line", px(5)],
] as const) {
const path = document.createElementNS(SVG_NS, "path");
path.setAttribute("class", `direction-${part} direction-${side}`);
path.setAttribute("d", d);
path.setAttribute("stroke-width", String(stroke));
group.append(path);
}
group.append(path);
}
const head = document.createElementNS(SVG_NS, "path");
head.setAttribute("class", "path-head");
const size = px(7);
head.setAttribute(
"d",
`M ${end - size} ${bottom - size} L ${end} ${bottom} L ${end - size} ${bottom + size}`,
);
head.setAttribute("stroke-width", String(px(3)));
group.append(head);
// Sous les pions, et sous les numéros des flèches, remontés au-dessus
// du tracé ; les zones à toucher restent devant tout.
const pieces = svg.querySelector(":scope > g.pieces");
svg.insertBefore(group, pieces);
for (const number of svg.querySelectorAll(":scope > .point-number")) {
svg.insertBefore(number, pieces);
const tip = document.createElementNS(SVG_NS, "path");
tip.setAttribute("class", `direction-head direction-${side}`);
tip.setAttribute(
"d",
`M ${end - head} ${to - half} L ${end} ${to} L ${end - head} ${to + half} Z`,
);
tip.setAttribute("stroke-width", String(px(2)));
group.append(tip);
}
// Sous les pions ; les zones à toucher restent devant tout.
svg.insertBefore(group, svg.querySelector(":scope > g.pieces"));
}
/** Crée l'écran du tutoriel dans section (vide dans index.html). */
@@ -359,7 +376,7 @@ export function createTutorialView(options: TutorialViewOptions): TutorialView {
};
renderBoard(svg, g, boardModel(current), decor);
if (screen?.path === true) {
drawPath(svg, g, (svg.getBoundingClientRect().width || g.width) / g.width);
drawDirections(svg, g, (svg.getBoundingClientRect().width || g.width) / g.width);
}
}
+230
View File
@@ -0,0 +1,230 @@
// Saisie d'un coup de sortie demi-coup par demi-coup, sur le vrai moteur
// WebAssembly : tout ordre de saisie que le moteur accepte doit être accepté
// par la partie, même quand un début de coup forme déjà un coup complet.
//
// Défaut corrigé (2026-11-10) : avec 6-1 et des pions sur 6 et 1, 6/off
// mène à la même position que le coup légal « 6/5/off » ; la partie le
// tenait pour complet et refusait ensuite 1/off, alors que 1/off puis 6/off
// passait.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import assert from "node:assert/strict";
import { test } from "node:test";
import type { Engine } from "../src/domain/game/engine.js";
import { Game } from "../src/domain/game/game.js";
import { formatHalfMoves, type HalfMove } from "../src/domain/game/position.js";
import { fixedDice, type Roll } from "../src/domain/game/roll.js";
import { loadNodeEngine } from "./support/node-engine.js";
// Le joueur, au trait, a un pion sur sa case 6 et un sur sa case 1 ;
// l'ordinateur un sur sa case 1 et un sur sa case 2. Le cas signalé par
// Pierre (#/position/BQAACAIAAAAAAA, « Jouer à partir d'ici »).
const SIX_AND_ONE = "BQAACAIAAAAAAA";
/**
* Position ID (format de gnubg) d'une fin de partie : les pions du joueur au
* trait sur ses cases 1 à 6 (player[i] : nombre de pions sur la case i + 1),
* l'ordinateur avec un pion sur sa case 1 et un sur sa case 2 ; les autres
* pions sont sortis. Outil de test seulement : chaque position produite est
* relue par le moteur, qui doit y retrouver ces pions.
*/
function bearOffPosition(player: readonly number[]): string {
const bits: number[] = [];
const side = (counts: readonly number[]) => {
for (let point = 0; point < 25; point++) {
for (let k = 0; k < (counts[point] ?? 0); k++) {
bits.push(1);
}
bits.push(0);
}
};
side([1, 1]); // l'adversaire d'abord, comme dans gnubg
side(player);
const bytes = new Uint8Array(10);
bits.forEach((bit, i) => {
if (bit === 1) {
bytes[i >> 3] = (bytes[i >> 3] ?? 0) | (1 << (i & 7));
}
});
return Buffer.from(bytes).toString("base64").slice(0, 14);
}
/** Une partie où le joueur, au trait dans position, vient de lancer roll. */
async function rolled(engine: Engine, position: string, roll: Roll): Promise<Game> {
const game = Game.start(engine, {
dice: fixedDice(roll),
setup: { position, firstTurn: "player" },
});
await game.roll();
return game;
}
/** Toutes les permutations distinctes des demi-coups. */
function orders(halfMoves: readonly HalfMove[]): HalfMove[][] {
if (halfMoves.length <= 1) {
return [[...halfMoves]];
}
const seen = new Set<string>();
const result: HalfMove[][] = [];
halfMoves.forEach((h, i) => {
const rest = [...halfMoves.slice(0, i), ...halfMoves.slice(i + 1)];
for (const tail of orders(rest)) {
const order = [h, ...tail];
const key = formatHalfMoves(order);
if (!seen.has(key)) {
seen.add(key);
result.push(order);
}
}
});
return result;
}
test("le cas signalé est bien celui que décrit le test", async () => {
const engine = await loadNodeEngine();
assert.equal(bearOffPosition([1, 0, 0, 0, 0, 1]), SIX_AND_ONE);
const board = await engine.board(SIX_AND_ONE, { value: 1, owner: "centered" });
assert.deepEqual(board.onRoll.points.slice(0, 6), [1, 0, 0, 0, 0, 1]);
});
test("6-1 en sortie : 6/off puis 1/off, comme 1/off puis 6/off", async () => {
const engine = await loadNodeEngine();
const allOff = (await engine.legalMoves(SIX_AND_ONE, [6, 1])).find(
(m) => m.notation === "6/off 1/off",
);
assert.ok(allOff, "le moteur propose 6/off 1/off");
// 6/off d'abord : la position est déjà celle d'un coup légal (6/5/off),
// mais le 1 reste jouable et le moteur l'accepte.
const six = await rolled(engine, SIX_AND_ONE, [6, 1]);
assert.equal(await six.playHalfMove({ from: 6, to: 0 }), true);
assert.equal(six.moveComplete, true);
assert.deepEqual(await six.nextHalfMoves(), [{ from: 1, to: 0 }]);
assert.equal(await six.playHalfMove({ from: 1, to: 0 }), true);
assert.equal(six.moveComplete, true);
assert.equal(six.displayedPosition, allOff.position);
assert.deepEqual(
six.diceToPlay.map((d) => d.used),
[true, true],
);
await six.confirmMove();
assert.equal(six.state.phase, "over");
// 1/off d'abord : pas encore complet, puis 6/off.
const one = await rolled(engine, SIX_AND_ONE, [6, 1]);
assert.equal(await one.playHalfMove({ from: 1, to: 0 }), true);
assert.equal(one.moveComplete, false);
assert.equal(await one.playHalfMove({ from: 6, to: 0 }), true);
assert.equal(one.displayedPosition, allOff.position);
// Et le coup 6/off seul (6/5/off) se valide toujours tel quel.
const alone = await rolled(engine, SIX_AND_ONE, [6, 1]);
assert.equal(await alone.playHalfMove({ from: 6, to: 0 }), true);
await alone.confirmMove();
assert.equal(alone.state.turn, "computer");
});
test("tous les dés joués, le moteur n'est plus interrogé", async () => {
// Le moteur de la page refuse plus de quatre demi-coups (erreur de la
// ligne de commande) : la partie ne doit pas en demander un cinquième
// après un double, ni un troisième après un jet simple.
const real = await loadNodeEngine();
const engine: Engine = {
...real,
checkHalfMoves: (position, roll, halfMoves) => {
const dice = roll[0] === roll[1] ? 4 : 2;
if (halfMoves.length > dice) {
throw new Error(`${halfMoves.length} demi-coups pour ${dice} dés`);
}
return real.checkHalfMoves(position, roll, halfMoves);
},
};
const double = await rolled(engine, bearOffPosition([0, 0, 2, 2, 0, 0]), [2, 2]);
for (const h of [
{ from: 4, to: 2 },
{ from: 4, to: 2 },
{ from: 3, to: 1 },
{ from: 3, to: 1 },
]) {
assert.equal(await double.playHalfMove(h), true);
}
assert.equal(double.moveComplete, true);
assert.deepEqual(await double.nextHalfMoves(), []);
assert.equal(await double.playHalfMove({ from: 2, to: 0 }), false);
const simple = await rolled(engine, SIX_AND_ONE, [6, 1]);
assert.equal(await simple.playHalfMove({ from: 1, to: 0 }), true);
assert.equal(await simple.playHalfMove({ from: 6, to: 0 }), true);
assert.deepEqual(await simple.nextHalfMoves(), []);
});
test("en sortie, tout ordre accepté par le moteur l'est par la partie", async () => {
const engine = await loadNodeEngine();
// Toutes les fins de partie d'un à trois pions dans le jan intérieur,
// et quelques-unes à quatre (doubles), avec les 21 jets.
const positions: number[][] = [];
for (let a = 0; a < 6; a++) {
positions.push([a]);
for (let b = a; b < 6; b++) {
positions.push([a, b]);
for (let c = b; c < 6; c++) {
positions.push([a, b, c]);
}
}
}
positions.push([0, 0, 0, 0], [1, 2, 3, 4], [5, 5, 4, 4], [0, 2, 4, 5], [3, 3, 3, 3]);
const rolls: Roll[] = [];
for (let a = 1; a <= 6; a++) {
for (let b = 1; b <= a; b++) {
rolls.push([a, b]);
}
}
const failures: string[] = [];
let checked = 0;
for (const pips of positions) {
const counts = [0, 0, 0, 0, 0, 0];
for (const p of pips) {
counts[p] = (counts[p] ?? 0) + 1;
}
const position = bearOffPosition(counts);
for (const roll of rolls) {
const moves = await engine.legalMoves(position, roll);
const game = await rolled(engine, position, roll);
for (const move of moves) {
for (const order of orders(move.halfMoves)) {
// Le moteur doit accepter chaque début de cet ordre…
let accepted = true;
for (let i = 1; i <= order.length && accepted; i++) {
accepted = (await engine.checkHalfMoves(position, roll, order.slice(0, i)))
.valid;
}
if (!accepted) {
continue;
}
// … et alors la partie aussi, jusqu'au coup complet.
game.cancelHalfMoves();
checked++;
const label = `${position} ${roll.join("-")} ${formatHalfMoves(order)}`;
for (const h of order) {
const offered = (await game.nextHalfMoves()).some(
(n) => n.from === h.from && n.to === h.to,
);
if (!offered || !(await game.playHalfMove(h))) {
failures.push(`${label} : ${formatHalfMoves([h])} refusé`);
break;
}
}
if (game.pendingHalfMoves.length === order.length) {
if (!game.moveComplete || game.displayedPosition !== move.position) {
failures.push(`${label} : coup incomplet ou position différente`);
}
}
}
}
}
}
assert.ok(checked > 1000, `${checked} ordres vérifiés`);
assert.deepEqual(failures, []);
});
+29
View File
@@ -35,6 +35,35 @@ test("ouverture 3-1 : 24/23 13/10 est une erreur très mauvaise, 8/5 6/5 le meil
Math.abs(analysis.equityLoss - (analysis.played.equity - analysis.best.equity)) < 1e-6,
);
assert.ok(analysis.equityLoss < -SKILL_THRESHOLDS.veryBad);
// Le classement de l'analyse, comme gnubg de bureau
// (tests/reference/analysis/move-opening-31-error.json) : le meilleur
// coup et le coup joué, une erreur, réévalués à 2 plis ; les suivants
// restés à 1 pli, puis à 0, écartés par les filtres.
assert.deepEqual(analysis.ranking[0], analysis.best);
assert.deepEqual(analysis.ranking[1], analysis.played);
assert.deepEqual(
analysis.ranking.map((move) => move.ply),
[2, 2, 1, 1, 1, 0, 0, 0, 0, 0],
);
});
test("ouverture 3-1 jouée 8/5 6/5 : un seul coup passe le filtre, tout reste à 1 pli", async () => {
const engine = await loadNodeEngine();
const analysis = await engine.analyseMove(
START_POSITION,
centered,
[3, 1],
"4HPwATCwZ/ABMA",
2,
);
assert.ok(analysis !== null);
assert.equal(analysis.rank, 1);
assert.deepEqual(analysis.ranking[0], analysis.best);
assert.deepEqual(analysis.best, analysis.played);
assert.deepEqual(
analysis.ranking.slice(0, 5).map((move) => move.ply),
[1, 1, 1, 1, 1],
);
});
test("sans coup possible, il n'y a rien à analyser", async () => {
+344
View File
@@ -0,0 +1,344 @@
// L'analyse de partie (étape 1e) : les tours, le format durable de
// l'analyse et sa migration, les chiffres du bilan à la manière de gnubg,
// et une partie complète analysée par le vrai moteur.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import assert from "node:assert/strict";
import { test } from "node:test";
import {
chanceCurve,
gameTurns,
levelOfErrorRate,
luckRatingOf,
mainAdvice,
missingAnalyses,
readyForSummary,
replayPoint,
runAnalysis,
summarizeAnalysis,
} from "../src/domain/analysis/game-analysis.js";
import { ADVICE_VERSION, type Advice, type CubeAdvice } from "../src/domain/game/advice.js";
import type { Engine } from "../src/domain/game/engine.js";
import {
appendEvent,
EMPTY_JOURNAL,
type GameJournal,
migrateJournal,
type NewGameEvent,
withAnalysesOf,
} from "../src/domain/game/events.js";
import { Game } from "../src/domain/game/game.js";
import { formatHalfMoves, START_POSITION } from "../src/domain/game/position.js";
import { emptyReview, REVIEW_VERSION } from "../src/domain/game/review.js";
import { loadNodeEngine } from "./support/node-engine.js";
import { playToTheEnd, seededDice } from "./support/play.js";
/** Un journal fait d'événements donnés, à la suite. */
function journalOf(events: readonly NewGameEvent[]): GameJournal {
return events.reduce(appendEvent, EMPTY_JOURNAL);
}
const START: NewGameEvent = {
type: "GameStarted",
position: START_POSITION,
cube: { value: 1, owner: null },
firstTurn: null,
};
const P = START_POSITION;
/** Une petite partie : ouverture (égalité puis 3-1 pour le joueur), un
* coup de chaque camp, puis le joueur double et l'ordinateur passe. */
const SHORT: NewGameEvent[] = [
START,
{ type: "DiceRolled", side: null, roll: [2, 2] },
{ type: "DiceRolled", side: null, roll: [3, 1] },
{ type: "MovePlayed", side: "player", halfMoves: [{ from: 8, to: 5 }], position: P },
{ type: "DiceRolled", side: "computer", roll: [6, 5] },
{ type: "MovePlayed", side: "computer", halfMoves: [{ from: 24, to: 13 }], position: P },
{ type: "CubeOffered", side: "player" },
{ type: "CubeDropped", side: "computer" },
{ type: "GameEnded", winner: "player", kind: "single", points: 1 },
];
test("les tours d'une partie : ouverture, coups, double passé", () => {
const journal = journalOf(SHORT);
const turns = gameTurns(journal);
assert.deepEqual(
turns.map((t) => [t.number, t.side, t.roll, t.move?.id ?? null, t.end?.id ?? null]),
[
[1, "player", [3, 1], "4", null],
[2, "computer", [6, 5], "6", null],
[3, "player", null, null, "9"],
],
);
// L'égalité d'ouverture appartient au premier tour.
assert.deepEqual(
turns[0]?.events.map((e) => e.id),
["2", "3", "4"],
);
// Le jet d'ouverture qui désigne le joueur a une chance, l'égalité non.
const luck = missingAnalyses(journal).filter((t) => t.kind === "luck");
assert.deepEqual(
luck.map((t) => t.eventId),
["3", "5"],
);
});
/** Un conseil fictif sur un coup du joueur. */
function moveAdvice(eventId: string, equityLoss: number, moveCount = 10): Advice {
const move = { notation: "8/5", halfMoves: [], equity: 0, ply: 2 };
return {
version: ADVICE_VERSION,
kind: "move",
eventId,
ply: 2,
position: P,
roll: [3, 1],
opening: true,
moveCount,
rank: equityLoss === 0 ? 1 : 2,
played: move,
best: move,
playedFacts: { hits: 0, madePoints: [] },
bestFacts: { hits: 0, madePoints: [] },
ranking: [],
equityLoss,
skill:
equityLoss < -0.12
? "veryBad"
: equityLoss < -0.06
? "bad"
: equityLoss < -0.03
? "doubtful"
: "none",
};
}
function cubeAdvice(eventId: string, action: CubeAdvice["action"], equityLoss: number): Advice {
return {
version: ADVICE_VERSION,
kind: "cube",
eventId,
ply: 2,
action,
position: P,
equities: { noDouble: 0.5, doubleTake: 0.6, doublePass: 1, optimal: 0.6 },
equityLoss,
skill: equityLoss < -0.06 ? "bad" : "none",
};
}
test("le taux d'erreur, le niveau et la chance à la manière de gnubg", () => {
// arThrsRating de gnubg : 0,032, 0,020, 0,013, 0,008, 0,005 ; les six
// classements de gnubg prennent, dans l'ordre, les noms des six niveaux
// de l'ordinateur (Advanced de gnubg : Intermédiaire).
assert.equal(levelOfErrorRate(0.05), "beginner");
assert.equal(levelOfErrorRate(0.032), "beginner");
assert.equal(levelOfErrorRate(0.031), "amateur");
assert.equal(levelOfErrorRate(0.015), "intermediate");
assert.equal(levelOfErrorRate(0.01), "advanced");
assert.equal(levelOfErrorRate(0.006), "expert");
assert.equal(levelOfErrorRate(0.001), "champion");
// getLuckRating : chance par tour × 10, seuils 0,3 et 0,6.
assert.equal(luckRatingOf(0.07), "veryLucky");
assert.equal(luckRatingOf(0.04), "lucky");
assert.equal(luckRatingOf(0.02), "none");
assert.equal(luckRatingOf(-0.04), "unlucky");
assert.equal(luckRatingOf(-0.07), "veryUnlucky");
const base = journalOf(SHORT);
const journal: GameJournal = {
...base,
advice: {
"4": moveAdvice("4", -0.08),
"7": cubeAdvice("7", "double", 0),
},
review: {
...emptyReview(2),
luck: {
"3": { value: 0.2, rating: "none" },
"5": { value: -0.1, rating: "none" },
},
computer: { "6": moveAdvice("6", 0) },
},
};
assert.ok(readyForSummary(journal));
const summary = summarizeAnalysis(journal);
// Un coup non forcé (0,08) et un double (compté toujours) : 0,04 par
// décision.
assert.equal(summary.player.errorRate.decisions, 2);
assert.ok(Math.abs(summary.player.errorRate.perDecision - 0.04) < 1e-9);
assert.equal(summary.player.errorRate.level, "beginner");
assert.deepEqual(summary.counts, { good: 1, doubtful: 0, bad: 1, veryBad: 0 });
assert.equal(summary.toReview?.advice.eventId, "4");
assert.equal(summary.toReview?.turn, 1);
// Une seule fois la main pour chacun : chance par tour égale au total.
assert.equal(summary.player.luck.rolls, 1);
assert.equal(summary.player.luck.rating, "veryLucky");
assert.equal(summary.computer.luck.rating, "veryUnlucky");
// Gagné 1 point, avec 0,2 de chance contre −0,1 pour l'ordinateur :
// 1 − 0,2 − 0,1.
assert.equal(summary.result, 1);
assert.ok(Math.abs(summary.luckAdjustedResult - 0.7) < 1e-9);
// Rejouer le premier tour : juste avant le coup, avec le même jet.
const first = gameTurns(journal)[0];
assert.ok(first !== undefined);
assert.equal(mainAdvice(journal, first)?.eventId, "4");
assert.equal(replayPoint(journal, first), "3");
// La courbe : le dernier tour finit la partie, gagnée.
assert.deepEqual(
chanceCurve(journal).map((p) => [p.turn, p.chance, p.verdict]),
[
[1, null, "bad"],
[2, null, null],
[3, 1, "good"],
],
);
});
test("un jet sans doubler ne compte que si la décision est serrée (isCloseCubedecision)", () => {
const base = journalOf([
{ ...START, firstTurn: "player" },
{ type: "DiceRolled", side: "player", roll: [3, 1] },
]);
const noDouble = (equities: CubeAdvice["equities"]): GameJournal => ({
...base,
advice: { "2": { ...(cubeAdvice("2", "noDouble", 0) as CubeAdvice), equities } },
});
// Doubler coûterait 0,2 par rapport à l'optimum : pas serré.
const far = noDouble({ noDouble: 0.5, doubleTake: 0.3, doublePass: 1, optimal: 0.5 });
assert.equal(summarizeAnalysis(far).player.errorRate.decisions, 0);
// Doubler est l'optimum : serré, compté.
const close = noDouble({ noDouble: 0.5, doubleTake: 0.6, doublePass: 1, optimal: 0.6 });
assert.equal(summarizeAnalysis(close).player.errorRate.decisions, 1);
// Un bon jet sans doubler n'est pas une décision visible du bilan.
assert.deepEqual(summarizeAnalysis(close).counts, {
good: 0,
doubtful: 0,
bad: 0,
veryBad: 0,
});
});
test("l'analyse de partie enregistrée : migration du format durable", () => {
const journal = journalOf(SHORT);
const review = {
...emptyReview(2),
luck: { "3": { value: 0.1, rating: "none" as const } },
winChances: { "4": 0.55, "99": 0.5 },
unanalysed: ["5", "98"],
};
// Un journal d'avant l'étape 1e se reprend tel quel.
assert.equal(migrateJournal(journal), journal);
// Les entrées rattachées à un événement absent sont oubliées.
const migrated = migrateJournal({ ...journal, review });
assert.deepEqual(migrated.review?.winChances, { "4": 0.55 });
assert.deepEqual(migrated.review?.unanalysed, ["5"]);
assert.deepEqual(migrated.review?.luck, review.luck);
// Une analyse complète et connue ne change pas.
const clean = { ...journal, review: migrated.review };
assert.equal(migrateJournal(clean), clean);
// Une autre version, ou une analyse mal formée, est oubliée.
const other = migrateJournal({
...journal,
review: { ...review, version: REVIEW_VERSION + 1 },
});
assert.equal(other.review, undefined);
const broken = { ...journal, review: { version: REVIEW_VERSION } } as unknown as GameJournal;
assert.equal(migrateJournal(broken).review, undefined);
// Les analyses d'une copie s'ajoutent au journal sans toucher aux
// conseils déjà là.
const live: GameJournal = { ...journal, advice: { "4": moveAdvice("4", 0) } };
const copy: GameJournal = {
...journal,
advice: { "4": moveAdvice("4", -0.5), "7": cubeAdvice("7", "double", 0) },
review,
};
const merged = withAnalysesOf(live, copy);
assert.equal(merged.advice?.["4"]?.equityLoss, 0);
assert.ok(merged.advice?.["7"] !== undefined);
assert.equal(merged.review, review);
});
/** Toutes les analyses qui manquent, une à une. */
async function analyseAll(engine: Engine, journal: GameJournal): Promise<GameJournal> {
let current = journal;
for (let i = 0; i < 500; i++) {
const next = missingAnalyses(current)[0];
if (next === undefined) {
return current;
}
current = await runAnalysis(engine, current, next);
}
throw new Error("l'analyse ne finit pas");
}
test("une partie complète analysée par le moteur, comme une partie d'avant 1d", async () => {
const engine = await loadNodeEngine();
// Une course courte (tests/reference/positions.json, race-1).
const game = Game.start(engine, {
setup: { position: "trsXAADs7mwAAA", firstTurn: "player" },
level: "2ply",
dice: seededDice(7),
});
await playToTheEnd(game, engine, 1);
// Aucun conseil n'a été rangé pendant la partie (comme avant l'étape
// 1d) : tout est à analyser.
assert.equal(game.journal.advice, undefined);
assert.ok(!readyForSummary(game.journal));
const analysed = await analyseAll(engine, game.journal);
assert.ok(readyForSummary(analysed));
assert.deepEqual(missingAnalyses(analysed), []);
const summary = summarizeAnalysis(analysed);
const advices = Object.values(analysed.advice ?? {});
assert.ok(advices.length > 0);
// Le coup à revoir est la plus grosse perte d'équité du joueur, s'il en
// a une.
const worst = advices
.filter((a) => a.skill !== "none")
.reduce<Advice | null>((w, a) => (w === null || a.equityLoss < w.equityLoss ? a : w), null);
assert.equal(summary.toReview?.advice.eventId, worst?.eventId);
// La chance de chaque tour d'un camp est comptée.
const moves = game.events.filter((e) => e.type === "MovePlayed");
assert.equal(summary.player.luck.rolls + summary.computer.luck.rolls, moves.length);
// Les chances de gagner sont des probabilités, et la courbe finit sur
// le résultat.
const curve = chanceCurve(analysed);
assert.ok(curve.every((p) => p.chance !== null && p.chance >= 0 && p.chance <= 1));
const won = game.state.result?.winner === "player";
assert.equal(curve.at(-1)?.chance, won ? 1 : 0);
// Les coups de l'ordinateur sont analysés aussi.
assert.ok(Object.keys(analysed.review?.computer ?? {}).length > 0);
// Le journal analysé se reprend : l'analyse fait partie du format.
const resumed = Game.resume(engine, JSON.parse(JSON.stringify(analysed)));
assert.deepEqual(resumed.journal.review, analysed.review);
// Chaque coup s'écrit pareil sur l'écran de jeu (« L'ordinateur a
// joué … », moveNotation) et dans l'analyse : la notation du moteur.
let compared = 0;
let rewritten = 0;
for (const move of moves) {
if (move.type !== "MovePlayed" || move.halfMoves.length === 0) {
continue;
}
const advice =
move.side === "computer"
? analysed.review?.computer[move.id]
: analysed.advice?.[move.id];
if (advice?.kind !== "move") {
continue;
}
const notation = await resumed.moveNotation(move.id);
assert.equal(notation, advice.played.notation, `coup ${move.id}`);
compared++;
if (notation !== formatHalfMoves(move.halfMoves)) {
rewritten++;
}
}
assert.ok(compared > 5, `${compared} coups comparés`);
// La course finit en sortie : au moins un coup s'écrit autrement que
// ses demi-coups (« 6/off » pour « 6/2 2/off »…).
assert.ok(rewritten > 0, "aucun coup réécrit par le moteur");
});
+1 -1
View File
@@ -73,7 +73,6 @@ function fakeEngine(overrides: Partial<Engine> = {}): Engine {
};
},
analyseMove: async () => null,
rankMoves: async () => [],
analyseCube: async () => ({
analysed: false,
equities: null,
@@ -81,6 +80,7 @@ function fakeEngine(overrides: Partial<Engine> = {}): Engine {
skill: "none",
}),
luck: async () => ({ value: 0, rating: "none" }),
evaluate: async () => ({ win: 0.5, equity: 0 }),
encodeMatch: async () => "MATCH",
decodeMatch: async () => ({
matchLength: 0,
+29 -5
View File
@@ -9,7 +9,7 @@ import assert from "node:assert/strict";
import { readdirSync, readFileSync, statSync } from "node:fs";
import { test } from "node:test";
import { createSettingsStore } from "../src/storage/settings-store.js";
import { OPENING_BOARDS, pipLead } from "../src/ui/board-model.js";
import { homeBoard, OPENING_BOARDS, outerBoard, pipLead } from "../src/ui/board-model.js";
import { BOARD_HEIGHT, boardGeometry, MAX_STACK, stackY } from "../src/ui/geometry.js";
import { createHaptics, HAPTIC_PATTERNS } from "../src/ui/haptics.js";
import { ICON_PATHS } from "../src/ui/icons.js";
@@ -37,15 +37,32 @@ const LANDSCAPES: [number, number][] = [
[800, 308],
];
test("géométrie en portrait : les mesures du plateau d'origine", () => {
test("géométrie en portrait : les mesures du plateau d'origine, numéros sur le cadre", () => {
const g = boardGeometry("portrait", 640 / 520, 396 / 640);
assert.equal(g.width, 640);
assert.equal(g.pointWidth, 44);
assert.equal(g.radius, 20);
assert.equal(g.step, 42);
// Pions d'un peu moins de 19 unités (20 avant les numéros sur le cadre).
assert.ok(g.radius >= 18.5 && g.radius <= 19, `pions de ${g.radius}`);
assert.equal(g.step, 2 * g.radius + 2);
assert.equal(g.trayLeft + g.tray + g.frame, 640);
// Numéros d'au moins 12 px à l'écran, à 412 px de large.
// Numéros d'au moins 12 px à l'écran, à 412 px de large, logés dans les
// bandes haute et basse du cadre (retours des premiers joueurs).
assert.ok(g.numberSize * (396 / 640) >= 12, `numéros de ${g.numberSize} unités`);
assert.ok(g.numberSize + 8 <= g.edge, `bande de ${g.edge} pour des numéros de ${g.numberSize}`);
});
test("géométrie en portrait : numéros d'au moins 12 px sur le cadre dès 275 px de large", () => {
for (const width of [275, 320, 358, 380, 396, 600]) {
const px = width / 640;
const g = boardGeometry("portrait", 640 / 520, px);
assert.ok(g.numberSize * px >= 12, `${width} px : numéros de ${g.numberSize * px} px`);
assert.ok(g.numberSize < g.edge, `${width} px : numéros hors du cadre`);
assert.ok(g.edge <= 36, `${width} px : bande de ${g.edge}`);
}
// Une miniature : la bande reste de 36 unités, les numéros y tiennent.
const thumbnail = boardGeometry("portrait", 640 / 520, 200 / 640);
assert.equal(thumbnail.edge, 36);
assert.ok(thumbnail.numberSize < thumbnail.edge);
});
test("géométrie en paysage : le plateau remplit l'écran, flèches de 44 px et pions de 22 px au moins", () => {
@@ -93,6 +110,13 @@ test("en paysage, les pions de la barre s'arrêtent avant les pastilles des comp
}
});
test("les jans de chaque camp, numérotés pour le joueur, dans le sens de marche", () => {
assert.deepEqual(homeBoard("player").points, [6, 5, 4, 3, 2, 1]);
assert.deepEqual(outerBoard("player").points, [12, 11, 10, 9, 8, 7]);
assert.deepEqual(homeBoard("computer").points, [19, 20, 21, 22, 23, 24]);
assert.deepEqual(outerBoard("computer").points, [13, 14, 15, 16, 17, 18]);
});
// -------------------------------------------------------------- Vibrations
test("vibrations : les motifs de la charte, et rien quand elles sont coupées", () => {
+519
View File
@@ -0,0 +1,519 @@
// Les prompts pour une IA (étape 1f) : gabarits lus dans leur source
// (docs/prompts/), remplis avec de vraies analyses du moteur. Aucun repère
// vide ni inconnu, et les chiffres sont ceux que l'application affiche.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { test } from "node:test";
import {
missingAnalyses,
runAnalysis,
summarizeAnalysis,
} from "../src/domain/analysis/game-analysis.js";
import { formatEquity, rankingRows } from "../src/domain/analysis/numbers.js";
import { diceWords, masterWords } from "../src/domain/analysis/phrases.js";
import type { Advice } from "../src/domain/game/advice.js";
import type { Engine } from "../src/domain/game/engine.js";
import type { GameJournal } from "../src/domain/game/events.js";
import { Game } from "../src/domain/game/game.js";
import { COMPUTER_LEVELS } from "../src/domain/game/level.js";
import { START_POSITION } from "../src/domain/game/position.js";
import {
boardDiagram,
PUBLIC_SITE,
positionAddress,
positionBefore,
positionNow,
} from "../src/domain/prompts/position.js";
import {
CUBE_ACTION_WORDS,
CUBE_ROW_WORDS,
conceptExample,
conceptPrompt,
decisionPrompt,
exercisesPosition,
exercisesPrompt,
LEVEL_MIN_DECISIONS,
LEVEL_NAMES,
playerSentence,
summaryPosition,
summaryPrompt,
} from "../src/domain/prompts/prompts.js";
import {
fillPrompt,
PROMPT_FILES,
PROMPT_KINDS,
type PromptTemplates,
parsePromptTemplate,
placeholders,
} from "../src/domain/prompts/templates.js";
import { ADVICE_TEXTS } from "../src/ui/advice-texts.js";
import { MATCH_TEXTS } from "../src/ui/match-texts.js";
import { REVIEW_TEXTS, signed } from "../src/ui/review-texts.js";
import { parseRoute, routeHash } from "../src/ui/router.js";
import {
adviceOn,
loadPhrases,
playerAnswers,
playerDoubles,
playerRollsWithoutDoubling,
playOpening,
} from "./support/advice.js";
import { loadNodeEngine } from "./support/node-engine.js";
import { playToTheEnd, seededDice } from "./support/play.js";
const root = new URL("../../../", import.meta.url);
const phrases = loadPhrases();
/** Les gabarits, lus dans leur source. */
function loadTemplates(): PromptTemplates {
const read = (file: string) =>
parsePromptTemplate(readFileSync(new URL(`docs/prompts/${file}`, root), "utf8"));
return {
move: read(PROMPT_FILES.move),
cube: read(PROMPT_FILES.cube),
summary: read(PROMPT_FILES.summary),
concept: read(PROMPT_FILES.concept),
exercises: read(PROMPT_FILES.exercises),
};
}
const templates = loadTemplates();
/** Ce que chaque prompt doit contenir (cadrage, « IA générative en V1 »). */
function assertComplete(prompt: string, position: { positionId: string; matchId: string }): void {
for (const hole of ["{", "}", "inconnu", "undefined", "NaN", "null", " :"]) {
assert.ok(!prompt.includes(hole), `« ${hole} » dans le prompt :\n${prompt}`);
}
assert.ok(prompt.startsWith("Tu es un coach de backgammon"), "rôle absent");
assert.match(
prompt,
/^Tu es un coach de backgammon, bienveillant et précis\. (Je débute au backgammon\.|Je suis un joueur de niveau [A-ZÉ]\S+\.)\n/,
);
assert.ok(prompt.includes(`Position ID : ${position.positionId}`), "Position ID absent");
assert.ok(prompt.includes(`Match ID : ${position.matchId}`), "Match ID absent");
assert.ok(prompt.includes(`${PUBLIC_SITE}#/position/`), "lien absent");
assert.ok(prompt.includes("X : mes pions"), "diagramme absent");
assert.match(prompt, /GNU Backgammon \(analyse à \d plis?\)/);
assert.ok(prompt.includes("ne les contredis pas"), "consigne absente");
assert.ok(prompt.includes("Réponds en français"), "langue absente");
}
test("les cinq gabarits se lisent dans leur source, avec les repères du cadrage", () => {
assert.equal(PROMPT_KINDS.length, 5);
for (const kind of PROMPT_KINDS) {
const names = placeholders(templates[kind]);
for (const name of [
"joueur",
"position_id",
"match_id",
"au_trait",
"lien",
"diagramme",
"score",
"videau",
"niveau_eval",
"langue",
]) {
assert.ok(names.includes(name), `{${name}} absent du gabarit ${kind}`);
}
assert.ok(templates[kind].includes("ne les contredis pas"), `consigne absente : ${kind}`);
}
assert.throws(() => parsePromptTemplate("# Sans gabarit\n"), /Gabarit/);
});
test("un repère inconnu ou vide est une erreur", () => {
assert.equal(fillPrompt("a {b} c", { b: "x" }), "a x c");
assert.throws(() => fillPrompt("a {b}", {}), /inconnu/);
assert.throws(() => fillPrompt("a {b}", { b: " " }), /vide/);
});
test("les mots du prompt sont ceux de l'écran", () => {
for (const level of COMPUTER_LEVELS) {
assert.equal(LEVEL_NAMES[level], MATCH_TEXTS.levels[level].name);
}
assert.deepEqual(CUBE_ACTION_WORDS, REVIEW_TEXTS.cubeActions);
assert.deepEqual(CUBE_ROW_WORDS, ADVICE_TEXTS.cubeRows);
});
test("le niveau du joueur ne se dit qu'à partir de 20 décisions, sans son taux", () => {
assert.equal(LEVEL_MIN_DECISIONS, 20);
assert.equal(playerSentence(null), "Je débute au backgammon.");
for (const level of COMPUTER_LEVELS) {
assert.equal(playerSentence({ decisions: 19, level }), "Je débute au backgammon.");
assert.equal(
playerSentence({ decisions: 20, level }),
`Je suis un joueur de niveau ${MATCH_TEXTS.levels[level].name}.`,
);
}
assert.equal(
playerSentence({ decisions: 120, level: "advanced" }),
"Je suis un joueur de niveau Avancé.",
);
});
test("le diagramme recopie le plateau décodé par le moteur", async () => {
const engine = await loadNodeEngine();
const start = await positionNow(engine, null);
assert.equal(start.positionId, START_POSITION);
const diagram = boardDiagram(start.sides);
assert.ok(diagram.includes("Mes pions (X), case (nombre) : 24 (2), 13 (5), 8 (3), 6 (5)."));
assert.ok(
diagram.includes(
"Pions de l'ordinateur (O), dans ma numérotation : 19 (5), 17 (3), 12 (5), 1 (2).",
),
);
assert.ok(diagram.includes("Compte de points : moi 167, l'ordinateur 167."));
// La rangée du haut : 13 (X, 5 pions) à gauche, 24 (X, 2 pions) à
// droite ; 19 (O) juste après la barre.
const lines = diagram.split("\n");
assert.equal(lines[1], " 13 14 15 16 17 18 | 19 20 21 22 23 24");
assert.equal(lines[2], " X . . . O . | O . . . . X");
assert.equal(lines[3], " X O | O X");
assert.equal(lines[0], "```");
assert.equal(lines[lines.indexOf("```", 1) - 1], " 12 11 10 9 8 7 | 6 5 4 3 2 1");
});
test("le lien de la position est l'adresse publique de l'écran « position »", async () => {
const engine = await loadNodeEngine();
const played = await playOpening(engine, [3, 1], "24/23 13/10");
const position = await positionBefore(engine, played.game.journal, played.eventId);
const address = positionAddress(position);
const hash = routeHash({
screen: "position",
position: position.positionId,
match: position.matchId,
});
assert.equal(address, `${PUBLIC_SITE}${hash}`);
assert.deepEqual(parseRoute(new URL(address).hash), {
screen: "position",
position: position.positionId,
match: position.matchId,
});
});
/** Les lignes du classement telles que la feuille du maître les affiche :
* rang, coup, écart. */
function shownRanking(advice: Advice): string[] {
if (advice.kind !== "move") {
return [];
}
return rankingRows(advice).map((row) => `${row.move.notation}|${formatEquity(row.loss)}`);
}
test("prompt d'un coup : la position, les identifiants et le top 3 du moteur, mêmes chiffres", async () => {
const engine = await loadNodeEngine();
for (const [dice, move] of [
[[3, 1], "24/23 13/10"],
[[3, 1], "8/5 6/5"],
[[2, 1], "13/11 6/5"],
[[6, 5], "24/18 13/8"],
] as const) {
const played = await playOpening(engine, dice, move);
const advice = await adviceOn(engine, played);
assert.equal(advice.kind, "move");
if (advice.kind !== "move") {
continue;
}
// Le conseil, rattaché au journal comme dans l'application.
played.game.recordAdvice(advice);
const position = await positionBefore(engine, played.game.journal, played.eventId);
assert.equal(position.positionId, advice.position);
const prompt = decisionPrompt(templates, phrases, {
journal: played.game.journal,
advice,
position,
});
assertComplete(prompt, position);
assert.ok(prompt.includes(`Dés : ${dice[0]}-${dice[1]}.`), prompt);
assert.ok(prompt.includes(`J'ai joué ${advice.played.notation} : `), prompt);
assert.ok(prompt.includes(`« ${masterWords(phrases, advice).word} »`), prompt);
// Les trois premiers coups du moteur, et le vôtre, avec les écarts
// de « Voir les chiffres du moteur ».
const shown = shownRanking(advice);
for (const row of rankingRows(advice).filter((r) => r.rank <= 3 || r.played)) {
const line = `${row.rank}. ${row.move.notation}${row.played ? " (mon coup)" : ""} : équité ${formatEquity(row.move.equity)}, écart ${formatEquity(row.loss)}`;
assert.ok(prompt.includes(line), `ligne absente : ${line}\n${prompt}`);
assert.ok(shown.includes(`${row.move.notation}|${formatEquity(row.loss)}`));
}
assert.ok(prompt.includes(`1. ${advice.best.notation}`), prompt);
assert.match(prompt, /\(analyse à [12] plis?\)/);
}
});
/** Une équité écrite (« −0,212 ») proche d'une équité de gnubg de bureau :
* à l'arrondi près, plus la tolérance des positions de référence (0,002 ;
* tests/reference/README.md), le moteur WebAssembly ne calculant pas au
* bit près comme gnubg de bureau (ADR 0005). */
function assertNear(text: string, value: number, message: string): void {
const written = Number(text.replace("−", "-").replace("+", "").replace(",", "."));
assert.ok(Math.abs(written - value) <= 0.0005 + 0.002, `${text} ≠ ${value}\n${message}`);
}
/** Le niveau du titre du classement, et chaque ligne du classement : coup,
* équité, écart, niveau propre (null : celui du titre). */
function rankingOfPrompt(prompt: string) {
const title = /^Classement de GNU Backgammon \(analyse à (\d) plis?\)/m.exec(prompt);
assert.ok(title, prompt);
const lines = [
...prompt.matchAll(
/^(\d+)\. (.+?)( \(mon coup\))? : équité (\S+), écart (\S+?)(?:, évalué à (\d) plis?)?$/gm,
),
].map((m) => ({
rank: Number(m[1]),
notation: m[2],
mine: m[3] !== undefined,
equity: m[4],
loss: m[5],
ply: m[6] === undefined ? null : Number(m[6]),
}));
return { ply: Number(title[1]), lines };
}
test("prompt d'un coup : le niveau du titre est celui des lignes, les équités celles de l'analyse", async () => {
const engine = await loadNodeEngine();
// gnubg de bureau, analyse de partie à 2 plis (tests/reference/analysis/).
const reference = (id: string) =>
JSON.parse(readFileSync(new URL(`tests/reference/analysis/${id}.json`, root), "utf8"))
.plies["2"];
for (const [dice, move, id] of [
// Erreur : gnubg réévalue à 2 plis le meilleur coup et le coup joué ;
// les autres restent au niveau où ses filtres les ont laissés.
[[3, 1], "24/23 13/10", "move-opening-31-error"],
// Meilleur coup : un seul coup passe le filtre de 1 pli, gnubg
// s'arrête là, tout le classement est à 1 pli.
[[3, 1], "8/5 6/5", "move-opening-31-best"],
[[6, 5], "13/8 13/7", "move-opening-65-error"],
] as const) {
const played = await playOpening(engine, dice, move);
const advice = await adviceOn(engine, played);
assert.ok(advice.kind === "move");
played.game.recordAdvice(advice);
const position = await positionBefore(engine, played.game.journal, played.eventId);
const prompt = decisionPrompt(templates, phrases, {
journal: played.game.journal,
advice,
position,
});
const { ply, lines } = rankingOfPrompt(prompt);
const expected = reference(id);
// Le titre dit le niveau du meilleur coup, celui que gnubg de bureau
// donne ; une ligne sans niveau propre est à ce niveau, une ligne
// avec un niveau propre, à un niveau inférieur.
assert.equal(ply, expected.ranking[0].ply, prompt);
assert.equal(ply, advice.best.ply);
assert.ok(lines.length >= 3, prompt);
for (const line of lines) {
const reference = expected.ranking.find(
(m: { move: string }) => m.move === line.notation,
);
assert.ok(reference, `${line.notation} absent du classement de gnubg`);
assert.equal(line.ply ?? ply, reference.ply, `${line.notation}\n${prompt}`);
assert.ok(line.ply === null || line.ply < ply, prompt);
assertNear(line.equity, reference.equity, `${line.notation}\n${prompt}`);
}
// Les équités et l'écart du meilleur coup et du vôtre sont ceux de
// l'analyse, que disent la feuille du maître et l'écran d'analyse.
const best = lines[0];
const mine = lines.find((line) => line.mine);
assert.ok(best && mine, prompt);
assert.equal(best.notation, advice.best.notation);
assert.equal(best.equity, formatEquity(advice.best.equity));
assert.equal(best.loss, formatEquity(0));
assert.equal(mine.notation, advice.played.notation);
assert.equal(mine.rank, advice.rank);
assert.equal(mine.equity, formatEquity(advice.played.equity));
assert.equal(mine.loss, formatEquity(advice.equityLoss));
assertNear(mine.loss, expected.equity_loss, prompt);
assert.ok(shownRanking(advice).includes(`${mine.notation}|${mine.loss}`));
}
});
test("prompt d'une décision de videau : les équités de la feuille du maître", async () => {
const engine = await loadNodeEngine();
const cases = [
{ play: playerDoubles, who: "moi", question: "doubler ou lancer" },
{ play: playerRollsWithoutDoubling, who: "moi", question: "doubler ou lancer" },
{ play: (e: Engine) => playerAnswers(e, true), who: "l'ordinateur", question: "prendre" },
{ play: (e: Engine) => playerAnswers(e, false), who: "l'ordinateur", question: "prendre" },
];
for (const { play, who, question } of cases) {
const played = await play(engine);
const advice = await adviceOn(engine, played);
assert.equal(advice.kind, "cube");
if (advice.kind !== "cube") {
continue;
}
played.game.recordAdvice(advice);
const position = await positionBefore(engine, played.game.journal, played.eventId);
assert.equal(position.positionId, advice.position);
const prompt = decisionPrompt(templates, phrases, {
journal: played.game.journal,
advice,
position,
});
assertComplete(prompt, position);
assert.ok(prompt.includes(`Il fallait choisir : ${question}`), prompt);
assert.ok(prompt.includes(`(${who}), pour un videau de 1`), prompt);
assert.ok(prompt.includes(`J'ai choisi de ${CUBE_ACTION_WORDS[advice.action]},`), prompt);
for (const key of ["noDouble", "doubleTake", "doublePass"] as const) {
const value = formatEquity(advice.equities[key]);
assert.match(
prompt,
new RegExp(
`- ${ADVICE_TEXTS.cubeRows[key]}( \\(ma décision\\))? : ${value.replace("+", "\\+")}\\n`,
),
);
}
assert.ok(prompt.includes(`Écart de ma décision : ${formatEquity(advice.equityLoss)}.`));
}
});
/** Toutes les analyses qui manquent, une à une, comme l'application en
* arrière-plan. */
async function analyseAll(engine: Engine, journal: GameJournal): Promise<GameJournal> {
let current = journal;
for (let i = 0; i < 500; i++) {
const next = missingAnalyses(current)[0];
if (next === undefined) {
return current;
}
current = await runAnalysis(engine, current, next);
}
throw new Error("l'analyse ne finit pas");
}
/** Une course courte jouée jusqu'au bout et analysée (le joueur prend le
* choice-ième coup légal). */
async function analysedRace(engine: Engine, seed: number, choice: number): Promise<GameJournal> {
const game = Game.start(engine, {
setup: { position: "trsXAADs7mwAAA", firstTurn: "player" },
level: "intermediate",
dice: seededDice(seed),
});
await playToTheEnd(game, engine, choice);
return analyseAll(engine, game.journal);
}
test("prompt du bilan : résultat, décomptes, taux et chance de l'écran, erreurs", async () => {
const engine = await loadNodeEngine();
const journal = await analysedRace(engine, 3, 3);
const summary = summarizeAnalysis(journal);
assert.ok(summary.toReview !== null, "la partie devrait avoir une erreur");
const position = await summaryPosition(engine, journal);
const prompt = summaryPrompt(templates, phrases, { journal, position });
assertComplete(prompt, position);
const { player, computer, counts } = summary;
// Les chiffres de « Voir les chiffres du moteur » de l'analyse, et les
// trois cases du bilan.
assert.ok(
prompt.includes(
`Mon erreur par décision : ${signed(-player.errorRate.perDecision)} sur ${player.errorRate.decisions} décision`,
),
);
assert.ok(
prompt.includes(`soit le niveau ${MATCH_TEXTS.levels[player.errorRate.level].name} ;`),
);
assert.ok(
prompt.includes(`celle de l'ordinateur : ${signed(-computer.errorRate.perDecision)} sur`),
);
assert.ok(
prompt.includes(
`La chance de mes dés par tour : ${signed(player.luck.perRoll)} (${diceWords(phrases, player.luck.rating)})`,
),
);
assert.ok(prompt.includes(`celle de l'ordinateur : ${signed(computer.luck.perRoll)}.`));
assert.ok(prompt.includes(`Mes décisions : ${counts.good} bon`), prompt);
assert.ok(prompt.includes(`, ${counts.bad + counts.veryBad} erreur`), prompt);
assert.ok(prompt.includes("Résultat : "), prompt);
assert.ok(prompt.includes("contre l'ordinateur (niveau Intermédiaire)"), prompt);
// Le coup à revoir : sa position, et sa ligne avec son écart.
const worst = summary.toReview.advice;
assert.equal(position.positionId, worst.position);
assert.ok(
prompt.includes(`Le coup à revoir, ma plus grosse erreur (coup ${summary.toReview.turn})`),
);
assert.ok(
prompt.includes(
`écart ${formatEquity(worst.equityLoss)} (${masterWords(phrases, worst).word})`,
),
prompt,
);
});
test("prompt du bilan sans erreur : la position finale", async () => {
const engine = await loadNodeEngine();
// Le joueur au trait : un pion sur 6, un sur 1 ; il joue 6/off 1/off et
// gagne (scénario « Revoir ma partie »).
const game = Game.start(engine, {
setup: { position: "BQAACAIAAAAAAA", firstTurn: "player" },
dice: () => 6,
});
await game.roll();
const moves = await engine.legalMoves(game.state.position, game.state.roll ?? [6, 6]);
for (const halfMove of moves[0]?.halfMoves ?? []) {
await game.playHalfMove(halfMove);
}
await game.confirmMove();
assert.equal(game.state.phase, "over");
const journal = await analyseAll(engine, game.journal);
const position = await summaryPosition(engine, journal);
const prompt = summaryPrompt(templates, phrases, { journal, position });
assertComplete(prompt, position);
assert.ok(prompt.includes("- aucune : j'ai joué comme GNU Backgammon."), prompt);
assert.ok(prompt.includes("Voici la position finale"), prompt);
assert.ok(prompt.includes("j'ai gagné une partie simple, 1 point"), prompt);
});
test("prompt d'un concept : la position de départ, ou celle de la partie en cours", async () => {
const engine = await loadNodeEngine();
const alone = await conceptExample(engine, null, 2);
const prompt = conceptPrompt(templates, {
term: "Videau",
english: "Cube",
brief: "le dé des enchères.",
journal: null,
example: alone,
});
assertComplete(prompt, alone.position);
assert.ok(prompt.includes("le concept « Videau » (en anglais : Cube)."), prompt);
assert.ok(prompt.includes("voici la position de départ"), prompt);
assert.ok(prompt.includes("précis. Je débute au backgammon.\n"), prompt);
assert.match(prompt, /chances de gagner \d+ %, équité [+−]?\d,\d{3}/);
const played = await playOpening(engine, [3, 1], "24/23 13/10");
played.game.recordAdvice(await adviceOn(engine, played));
const during = await conceptExample(engine, played.game.journal, 2);
assert.ok(during.fromGame);
const second = conceptPrompt(templates, {
term: "Blot",
english: "Blot",
brief: "un pion seul sur une case.",
journal: played.game.journal,
example: during,
});
assertComplete(second, during.position);
assert.ok(second.includes("le concept « Blot »."), second);
assert.ok(second.includes("une position de ma partie en cours"), second);
// Une seule décision analysée : pas de niveau, pas de taux d'erreur.
assert.ok(second.includes("Je débute au backgammon."), second);
assert.ok(!second.includes("erreur par décision"), second);
});
test("prompt des exercices : les erreurs de plusieurs parties, la plus coûteuse en position", async () => {
const engine = await loadNodeEngine();
const journals = [await analysedRace(engine, 3, 3), await analysedRace(engine, 7, 2)];
const position = await exercisesPosition(engine, journals);
assert.ok(position !== null);
const prompt = exercisesPrompt(templates, phrases, { journals, position });
assertComplete(prompt, position);
assert.ok(prompt.includes("Voici mes 2 dernières parties"), prompt);
assert.match(prompt, /- Partie [12], coup \d+/);
assert.ok(prompt.includes("La plus coûteuse (partie"), prompt);
assert.ok(prompt.includes("cinq exercices"), prompt);
assert.equal(await exercisesPosition(engine, []), null);
});
+151
View File
@@ -0,0 +1,151 @@
// L'analyse d'une partie en arrière-plan (app/src/ui/review-runner.ts) :
// une analyse à la fois, rangée au fur et à mesure, arrêtée à la demande
// ou par une autre partie ; et les phrases du bilan.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import assert from "node:assert/strict";
import { test } from "node:test";
import {
type AnalysisTask,
type GameSummary,
missingAnalyses,
} from "../src/domain/analysis/game-analysis.js";
import { diceWords, nothingToReview, summaryReading } from "../src/domain/analysis/phrases.js";
import {
appendEvent,
EMPTY_JOURNAL,
type GameJournal,
type NewGameEvent,
} from "../src/domain/game/events.js";
import { START_POSITION } from "../src/domain/game/position.js";
import { emptyReview, type GameReview } from "../src/domain/game/review.js";
import { createReviewRunner } from "../src/ui/review-runner.js";
import { loadPhrases } from "./support/advice.js";
const P = START_POSITION;
/** Un tour de l'ordinateur, sans décision du joueur. */
const EVENTS: NewGameEvent[] = [
{ type: "GameStarted", position: P, cube: { value: 1, owner: null }, firstTurn: "computer" },
{ type: "DiceRolled", side: "computer", roll: [6, 5] },
{ type: "MovePlayed", side: "computer", halfMoves: [], position: P },
];
const JOURNAL: GameJournal = EVENTS.reduce(appendEvent, EMPTY_JOURNAL);
/** Une fausse analyse : elle range la tâche sans moteur, quand on la
* libère. */
function fakeRun() {
const waiting: (() => void)[] = [];
const run = async (journal: GameJournal, task: AnalysisTask): Promise<GameJournal> => {
await new Promise<void>((resolve) => waiting.push(resolve));
const review: GameReview = journal.review ?? emptyReview(2);
if (task.kind === "luck") {
return {
...journal,
review: { ...review, luck: { [task.eventId]: { value: 0, rating: "none" } } },
};
}
if (task.kind === "chance") {
return {
...journal,
review: { ...review, winChances: { ...review.winChances, [task.eventId]: 0.5 } },
};
}
return { ...journal, review: { ...review, unanalysed: [task.eventId] } };
};
const release = async () => {
while (waiting.length === 0) {
await new Promise((resolve) => setTimeout(resolve, 1));
}
waiting.shift()?.();
await new Promise((resolve) => setTimeout(resolve, 1));
};
return { run, release };
}
test("l'analyse en arrière-plan range chaque analyse, puis s'arrête une fois tout fait", async () => {
const { run, release } = fakeRun();
const runner = createReviewRunner(run);
const recorded: GameJournal[] = [];
let done = false;
// La chance du jet, le jet sans doubler de l'ordinateur, ses chances
// après le coup.
const total = missingAnalyses(JOURNAL).length;
assert.equal(total, 3);
runner.start(
"a",
JOURNAL,
(j) => recorded.push(j),
() => {
done = true;
},
);
assert.equal(runner.running, "a");
// La même partie redemandée ne repart pas.
runner.start("a", JOURNAL, () => assert.fail("deuxième analyse"));
for (let i = 0; i < total; i++) {
await release();
}
assert.equal(recorded.length, total);
assert.deepEqual(missingAnalyses(recorded.at(-1) as GameJournal), []);
assert.ok(done);
assert.equal(runner.running, null);
});
test("l'analyse s'arrête à la demande, ou pour une autre partie, sans ranger la dernière", async () => {
const { run, release } = fakeRun();
const runner = createReviewRunner(run);
const recorded: string[] = [];
runner.start("a", JOURNAL, () => recorded.push("a"));
runner.stop();
assert.equal(runner.running, null);
await release();
assert.equal(recorded.length, 0);
runner.start("b", JOURNAL, () => recorded.push("b"));
runner.start("c", JOURNAL, () => recorded.push("c"));
assert.equal(runner.running, "c");
await release();
await release();
assert.deepEqual(recorded, ["c"]);
});
/** Un bilan réduit à ce que lisent les phrases. */
function summaryWith(result: number, luckAdjustedResult: number): GameSummary {
const side = {
errorRate: { total: 0, decisions: 0, perDecision: 0, level: "champion" as const },
luck: { total: 0, rolls: 1, perRoll: -0.04, rating: "unlucky" as const, points: 0 },
};
return {
player: side,
computer: side,
counts: { good: 0, doubtful: 0, bad: 0, veryBad: 0 },
toReview: null,
result,
luckAdjustedResult,
};
}
test("les phrases du bilan : ce qui a fait la différence, et les dés en mots", () => {
const phrases = loadPhrases();
assert.equal(diceWords(phrases, "unlucky"), "un peu contre vous");
assert.equal(
summaryReading(phrases, summaryWith(1, 1.2)),
"D'après mon analyse, votre jeu a fait la différence, avec des dés un peu contre vous.",
);
assert.equal(
summaryReading(phrases, summaryWith(-2, -1.5)),
"D'après mon analyse, le jeu de l'ordinateur a fait la différence, avec des dés un peu contre vous.",
);
// Gagnée grâce aux dés, ou perdue à cause d'eux : les dés.
for (const [result, adjusted] of [
[1, -0.3],
[-1, 0.2],
] as const) {
assert.equal(
summaryReading(phrases, summaryWith(result, adjusted)),
"D'après mon analyse, les dés ont fait la différence, plus que le jeu.",
);
}
assert.ok(nothingToReview(phrases).startsWith("Aucun coup à revoir"));
});
+38
View File
@@ -8,12 +8,14 @@
import assert from "node:assert/strict";
import { test } from "node:test";
import {
isAiRoute,
isHelpScreen,
parseRoute,
type Route,
routeHash,
slug,
stepsBack,
withoutAi,
} from "../src/ui/router.js";
const START = "4HPwATDgc/ABMA";
@@ -35,9 +37,24 @@ const TABLE: [string, Route][] = [
["#/installer", { screen: "install" }],
["#/parties", { screen: "games", game: null }],
["#/parties/mh2k3x-a1b2c3", { screen: "games", game: "mh2k3x-a1b2c3" }],
["#/parties/mh2k3x-a1b2c3/bilan", { screen: "summary", game: "mh2k3x-a1b2c3" }],
["#/parties/mh2k3x-a1b2c3/analyse", { screen: "analysis", game: "mh2k3x-a1b2c3", turn: null }],
["#/parties/mh2k3x-a1b2c3/analyse/7", { screen: "analysis", game: "mh2k3x-a1b2c3", turn: 7 }],
["#/menu", { screen: "menu" }],
["#/nouvelle-partie", { screen: "newGame" }],
["#/explication/12", { screen: "explanation", event: "12" }],
// La feuille du prompt pour une IA (amendement du 2026-11-10, 1f).
["#/explication/12/ia", { screen: "explanation", event: "12", ai: true }],
["#/glossaire/videau/ia", { screen: "glossary", term: "videau", ai: true }],
["#/parties/mh2k3x-a1b2c3/bilan/ia", { screen: "summary", game: "mh2k3x-a1b2c3", ai: true }],
[
"#/parties/mh2k3x-a1b2c3/analyse/7/ia",
{ screen: "analysis", game: "mh2k3x-a1b2c3", turn: 7, ai: true },
],
[
"#/parties/mh2k3x-a1b2c3/analyse/ia",
{ screen: "analysis", game: "mh2k3x-a1b2c3", turn: null, ai: true },
],
[
"#/position/4HPwATDgc%2FABMA/cAkAAAAAAAAA",
{ screen: "position", position: START, match: MATCH },
@@ -52,6 +69,17 @@ test("chaque adresse du tableau de l'ADR 0013 mène à son écran, et inversemen
}
});
test("la feuille du prompt pour une IA se pose sur son écran, et s'en retire", () => {
const route = parseRoute("#/parties/ab/analyse/3/ia");
assert.ok(isAiRoute(route));
if (isAiRoute(route)) {
assert.equal(routeHash(withoutAi(route)), "#/parties/ab/analyse/3");
}
assert.ok(!isAiRoute(parseRoute("#/parties/ab/analyse/3")));
// Un terme nommé « ia » reste un terme.
assert.deepEqual(parseRoute("#/glossaire/ia"), { screen: "glossary", term: "ia" });
});
test("une adresse vide ou « # » est la partie en cours ; une barre finale ne change rien", () => {
assert.deepEqual(parseRoute(""), { screen: "game" });
assert.deepEqual(parseRoute("#"), { screen: "game" });
@@ -75,6 +103,16 @@ test("une adresse inconnue est reconnue comme telle", () => {
"#/a-propos/x",
"#/position",
"#/position/%E0%A4%A",
"#/parties/ab/autre",
"#/parties/ab/bilan/2",
"#/parties/ab/analyse/0",
"#/parties/ab/analyse/x",
"#/parties/ab/analyse/3/plus",
"#/parties/AB/bilan",
"#/aide/blot/ia",
"#/menu/ia",
"#/parties/ab/ia",
"#/explication/12/ia/ia",
]) {
assert.equal(parseRoute(hash).screen, "unknown", hash);
}
+230
View File
@@ -0,0 +1,230 @@
// Étapes du scénario docs/scenarios/demander-a-une-ia.feature (ADR 0008) :
// les décisions se jouent par le domaine sur le vrai moteur, leur analyse
// par le domaine, et les prompts sont remplis par le domaine
// (domain/prompts/) avec les gabarits de docs/prompts/, comme dans
// l'application.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { BeforeAll, Given, setDefaultTimeout, Then, When } from "@cucumber/cucumber";
import { analyseDecision } from "../../src/domain/analysis/analyse.js";
import {
missingAnalyses,
runAnalysis,
summarizeAnalysis,
} from "../../src/domain/analysis/game-analysis.js";
import { formatEquity, rankingRows } from "../../src/domain/analysis/numbers.js";
import { diceWords } from "../../src/domain/analysis/phrases.js";
import type { Advice } from "../../src/domain/game/advice.js";
import type { Engine } from "../../src/domain/game/engine.js";
import type { GameJournal } from "../../src/domain/game/events.js";
import { Game } from "../../src/domain/game/game.js";
import { parseHalfMoves } from "../../src/domain/game/position.js";
import { fixedDice } from "../../src/domain/game/roll.js";
import {
type PromptPosition,
PUBLIC_SITE,
positionBefore,
} from "../../src/domain/prompts/position.js";
import {
conceptExample,
conceptPrompt,
decisionPrompt,
summaryPosition,
summaryPrompt,
} from "../../src/domain/prompts/prompts.js";
import {
PROMPT_FILES,
type PromptTemplates,
parsePromptTemplate,
} from "../../src/domain/prompts/templates.js";
import { parseGlossaryEntry } from "../../src/ui/help-text.js";
import { MATCH_TEXTS } from "../../src/ui/match-texts.js";
import { loadPhrases, playOpening } from "../support/advice.js";
import { loadNodeEngine } from "../support/node-engine.js";
setDefaultTimeout(60_000);
const root = new URL("../../../../", import.meta.url);
const read = (path: string) => readFileSync(new URL(path, root), "utf8");
const phrases = loadPhrases();
const templates: PromptTemplates = {
move: parsePromptTemplate(read(`docs/prompts/${PROMPT_FILES.move}`)),
cube: parsePromptTemplate(read(`docs/prompts/${PROMPT_FILES.cube}`)),
summary: parsePromptTemplate(read(`docs/prompts/${PROMPT_FILES.summary}`)),
concept: parsePromptTemplate(read(`docs/prompts/${PROMPT_FILES.concept}`)),
exercises: parsePromptTemplate(read(`docs/prompts/${PROMPT_FILES.exercises}`)),
};
/** Le joueur au trait : un pion sur son point 6, un sur son point 1 ;
* l'ordinateur : un sur son point 1, un sur son point 2. */
const BEAROFF = "BQAACAIAAAAAAA";
let engine: Engine;
let game: Game | null;
let journal: GameJournal;
let advice: Advice;
let position: PromptPosition;
let prompt: string;
BeforeAll(async () => {
engine = await loadNodeEngine();
});
Given(/^vous avez joué (.+) avec un (\d)-(\d) d'ouverture$/, async (move, a, b) => {
const played = await playOpening(engine, [Number(a), Number(b)], move);
const analysed = await analyseDecision(engine, played.game.journal, played.eventId);
assert.ok(analysed !== null);
// Le conseil rattaché au journal, comme dans l'application.
played.game.recordAdvice(analysed);
game = played.game;
journal = played.game.journal;
advice = analysed;
});
When("vous demandez à une IA d'expliquer ce coup", async () => {
position = await positionBefore(engine, journal, advice.eventId);
prompt = decisionPrompt(templates, phrases, { journal, advice, position });
});
Then("la question donne la position, avec son Position ID, son Match ID et son lien", () => {
assert.equal(position.positionId, advice.position);
assert.ok(prompt.includes(`Position ID : ${position.positionId}`), prompt);
assert.ok(prompt.includes(`Match ID : ${position.matchId}`), prompt);
assert.ok(prompt.includes(`${PUBLIC_SITE}#/position/`), prompt);
assert.ok(prompt.includes("Mes pions (X), case (nombre) : 24 (2), 13 (5), 8 (3), 6 (5)."));
});
Then(
"elle donne les trois meilleurs coups du maître et le vôtre, avec les chiffres de l'explication",
() => {
assert.equal(advice.kind, "move");
if (advice.kind !== "move") {
return;
}
// Les lignes de « Voir les chiffres du moteur » : coup et écart.
const rows = rankingRows(advice).filter((row) => row.rank <= 3 || row.played);
assert.ok(rows.length >= 3);
for (const row of rows) {
assert.ok(
prompt.includes(`${row.rank}. ${row.move.notation}`) &&
prompt.includes(`écart ${formatEquity(row.loss)}`),
`${row.move.notation} absent :\n${prompt}`,
);
}
assert.ok(prompt.includes(`J'ai joué ${advice.played.notation} : `), prompt);
},
);
Then("elle demande à l'IA de ne pas contredire ces chiffres, et de répondre en français", () => {
assert.ok(prompt.includes("ne les recalcule pas et ne les contredis pas"), prompt);
assert.ok(prompt.includes("Réponds en français"), prompt);
assert.ok(!/[{}]/.test(prompt.replace(/```/g, "")), prompt);
});
/** Toutes les analyses qui manquent, une à une, comme l'application en
* arrière-plan. */
async function analyseAll(start: GameJournal): Promise<GameJournal> {
let current = start;
for (let i = 0; i < 100; i++) {
const next = missingAnalyses(current)[0];
if (next === undefined) {
return current;
}
current = await runAnalysis(engine, current, next);
}
throw new Error("l'analyse ne finit pas");
}
Given(
/^une partie finie où vous avez joué (.+) avec (\d)-(\d), puis passé le double de l'ordinateur$/,
async (move: string, a: string, b: string) => {
const played = Game.start(engine, {
setup: { position: BEAROFF, firstTurn: "player" },
level: "2ply",
dice: fixedDice([Number(a), Number(b)]),
});
await played.roll();
for (const halfMove of parseHalfMoves(move)) {
assert.ok(await played.playHalfMove(halfMove), `demi-coup refusé : ${move}`);
}
await played.confirmMove();
await played.playComputerTurn();
assert.equal(played.state.phase, "doubled", "l'ordinateur ne double pas");
await played.drop();
assert.equal(played.state.phase, "over");
journal = await analyseAll(played.journal);
},
);
When("vous demandez à une IA le bilan de votre partie", async () => {
position = await summaryPosition(engine, journal);
prompt = summaryPrompt(templates, phrases, { journal, position });
});
Then("la question donne vos décisions, votre niveau et la chance des dés, comme le bilan", () => {
const summary = summarizeAnalysis(journal);
const { counts, player } = summary;
assert.ok(prompt.includes(`Mes décisions : ${counts.good} bon`), prompt);
assert.ok(prompt.includes(`${counts.bad + counts.veryBad} erreur`), prompt);
assert.ok(
prompt.includes(`soit le niveau ${MATCH_TEXTS.levels[player.errorRate.level].name}`),
prompt,
);
assert.ok(prompt.includes(`(${diceWords(phrases, player.luck.rating)})`), prompt);
assert.ok(prompt.includes("Résultat : l'ordinateur a gagné"), prompt);
});
Then(/^elle cite votre coup (.+), le coup du maître (.+) et leur écart$/, (mine, best) => {
const toReview = summarizeAnalysis(journal).toReview;
assert.ok(toReview !== null);
assert.ok(
prompt.includes(
`j'ai joué ${mine}, GNU Backgammon préférait ${best} ; écart ${formatEquity(toReview.advice.equityLoss)} (Grosse erreur).`,
),
prompt,
);
});
Then("elle donne la position du coup à revoir", () => {
const toReview = summarizeAnalysis(journal).toReview;
assert.equal(position.positionId, toReview?.advice.position);
assert.ok(prompt.includes(`Position ID : ${position.positionId}`), prompt);
assert.ok(prompt.includes("Le coup à revoir, ma plus grosse erreur (coup 1)"), prompt);
});
Given("aucune partie n'est en cours", () => {
game = null;
});
When(/^vous demandez à une IA d'expliquer le mot « (.+) »$/, async (term: string) => {
const entry = parseGlossaryEntry(read(`docs/glossaire/${term.toLowerCase()}.md`));
assert.ok(entry !== null);
const example = await conceptExample(engine, game?.journal ?? null, 2);
position = example.position;
prompt = conceptPrompt(templates, {
term: entry.term,
english: entry.english,
brief: entry.brief,
journal: game?.journal ?? null,
example,
});
});
Then("la question reprend la définition de sa fiche", () => {
const entry = parseGlossaryEntry(read("docs/glossaire/videau.md"));
assert.ok(entry !== null && prompt.includes(entry.brief), prompt);
assert.ok(prompt.includes("le concept « Videau » (en anglais : Cube)"), prompt);
});
Then(
"elle l'illustre par la position de départ, avec les chances de gagner selon GNU Backgammon",
() => {
assert.ok(prompt.includes("voici la position de départ"), prompt);
assert.ok(prompt.includes("Position ID : 4HPwATDgc/ABMA"), prompt);
assert.match(prompt, /chances de gagner \d+ %/);
},
);
+30
View File
@@ -476,6 +476,36 @@ Given("un joueur a sorti tous ses pions", async () => {
assert.equal(await playAndConfirm("6/off 5/off"), true);
});
// ------------------------------------------------- Sortir dans tout ordre
// Le joueur, au trait : un pion sur sa case 6, un sur sa case 1 ;
// l'ordinateur un pion sur sa case 1 et un sur sa case 2.
const SIX_AND_ONE = "BQAACAIAAAAAAA";
Given("vous avez un pion sur la flèche 6 et un sur la flèche 1, avec le jet 6-1", async () => {
game = Game.start(engine, {
setup: { position: SIX_AND_ONE, firstTurn: "player" },
dice: fixedDice([6, 1]),
});
await game.roll();
});
Then(/^vous pouvez valider ou jouer encore (.+)$/, async (text: string) => {
assert.equal(accepted, true);
// 6/off seul mène à la même position que 6/5/off, un coup légal.
assert.equal(game.moveComplete, true);
assert.deepEqual(await game.nextHalfMoves(), parseHalfMoves(text));
});
Then("vos deux pions sont sortis", async () => {
assert.equal(accepted, true);
assert.equal(game.moveComplete, true);
const board = await game.displayedBoard();
assert.equal(board.player.off, 15);
await game.confirmMove();
assert.equal(game.state.phase, "over");
});
Then("le résultat indique le gagnant et les points gagnés", () => {
// Gammon (l'ordinateur n'a sorti aucun pion), mais 1 point seulement :
// règle Jacoby, le videau n'a pas bougé.
+232
View File
@@ -0,0 +1,232 @@
// Étapes du scénario docs/scenarios/revoir-ma-partie.feature (ADR 0008) :
// la partie se joue par le domaine sur le vrai moteur, avec des dés
// imposés ; son analyse passe par l'analyse en arrière-plan de l'interface
// (review-runner.ts, sans DOM), le bilan par le domaine
// (game-analysis.ts) et les phrases du maître, et l'ancienne partie par le
// stockage des parties sur un localStorage simulé.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import assert from "node:assert/strict";
import { BeforeAll, Given, setDefaultTimeout, Then, When } from "@cucumber/cucumber";
import {
chanceCurve,
gameTurns,
missingAnalyses,
readyForSummary,
replayPoint,
runAnalysis,
summarizeAnalysis,
} from "../../src/domain/analysis/game-analysis.js";
import { diceWords, summaryReading } from "../../src/domain/analysis/phrases.js";
import type { Engine } from "../../src/domain/game/engine.js";
import type { GameJournal } from "../../src/domain/game/events.js";
import { Game } from "../../src/domain/game/game.js";
import { parseHalfMoves } from "../../src/domain/game/position.js";
import { fixedDice } from "../../src/domain/game/roll.js";
import { memoryStorage, openGameLibrary } from "../../src/storage/open-library.js";
import { createReviewRunner } from "../../src/ui/review-runner.js";
import { loadPhrases } from "../support/advice.js";
import { loadNodeEngine } from "../support/node-engine.js";
setDefaultTimeout(60_000);
/** Le joueur au trait : un pion sur son point 6, un sur son point 1 ;
* l'ordinateur : un sur son point 1, un sur son point 2 (Position ID de
* gnubg, chacun vu de lui-même). */
const BEAROFF = "BQAACAIAAAAAAA";
const phrases = loadPhrases();
let engine: Engine;
let game: Game;
let dice: number[];
/** Le journal analysé de la partie. */
let analysed: GameJournal;
/** La partie d'origine, avant « Rejouer d'ici ». */
let original: { head: string; events: number };
/** Les analyses rangées par l'analyse en arrière-plan. */
let recorded: number;
BeforeAll(async () => {
engine = await loadNodeEngine();
});
/** Analyse ce qui manque au journal, comme l'application en
* arrière-plan. */
async function analyse(journal: GameJournal): Promise<GameJournal> {
const runner = createReviewRunner((j, task) => runAnalysis(engine, j, task));
recorded = 0;
let latest = journal;
await new Promise<void>((resolve) => {
runner.start(
"partie",
journal,
(j) => {
latest = j;
recorded++;
},
resolve,
);
});
return latest;
}
async function playMove(move: string): Promise<void> {
for (const halfMove of parseHalfMoves(move)) {
assert.ok(await game.playHalfMove(halfMove), `demi-coup refusé : ${move}`);
}
await game.confirmMove();
}
Given(
"il vous reste deux pions, sur vos points 6 et 1, et à l'ordinateur deux pions sur ses points 1 et 2",
() => {
dice = [];
// Les dés sont tirés au moment voulu : ceux qu'impose le scénario.
game = Game.start(engine, {
setup: { position: BEAROFF, firstTurn: "player" },
level: "2ply",
dice: () => {
const die = dice.shift();
if (die === undefined) {
throw new Error("plus de dés imposés");
}
return die;
},
});
},
);
Given("vous avez {int}-{int} à jouer", async (a: number, b: number) => {
dice.push(a, b);
await game.roll();
assert.deepEqual(game.state.roll, [a, b]);
});
When(/^vous choisissez (?:cette fois )?le coup (.+)$/, async (move: string) => {
await playMove(move);
});
/** L'ordinateur, sûr de sortir ses deux pions au jet suivant, double ; le
* joueur passe. */
async function computerDoublesAndPlayerPasses(): Promise<void> {
await game.playComputerTurn();
assert.equal(game.state.phase, "doubled", "l'ordinateur ne double pas");
await game.drop();
assert.equal(game.state.phase, "over");
}
When("l'ordinateur, sûr de gagner, double et que vous passez", async () => {
await computerDoublesAndPlayerPasses();
analysed = await analyse(game.journal);
});
Then("la partie est finie, gagnée par l'ordinateur", () => {
assert.equal(game.state.result?.winner, "computer");
});
Then("le bilan compte une grosse erreur", () => {
assert.ok(readyForSummary(analysed));
assert.equal(summarizeAnalysis(analysed).counts.veryBad, 1);
});
Then("sa phrase dit ce qui a fait la différence, et comment étaient vos dés", () => {
const summary = summarizeAnalysis(analysed);
const reading = summaryReading(phrases, summary);
assert.ok(reading.startsWith("D'après mon analyse, "), reading);
assert.ok(!reading.includes("!"), reading);
// Perdue : le jeu de l'ordinateur a fait la différence, si le résultat
// corrigé de la chance reste négatif ; sinon les dés.
if (summary.luckAdjustedResult < 0) {
assert.ok(reading.includes(diceWords(phrases, summary.player.luck.rating)), reading);
} else {
assert.ok(reading.includes("les dés ont fait la différence"), reading);
}
});
Then("le coup à revoir est votre coup {}, le premier de la partie", (move: string) => {
const toReview = summarizeAnalysis(analysed).toReview;
assert.equal(toReview?.turn, 1);
assert.equal(toReview?.advice.kind, "move");
assert.equal(toReview?.advice.kind === "move" && toReview.advice.played.notation, move);
});
Then("le maître y aurait joué {}", (move: string) => {
const advice = summarizeAnalysis(analysed).toReview?.advice;
assert.equal(advice?.kind === "move" && advice.best.notation, move);
assert.equal(advice?.skill, "veryBad");
});
Then("la courbe de vos chances de gagner finit à {int} %", (percent: number) => {
const curve = chanceCurve(analysed);
assert.equal(curve.length, gameTurns(analysed).length);
assert.equal(curve.at(-1)?.chance, percent / 100);
assert.ok(curve.every((p) => p.chance !== null && p.chance >= 0 && p.chance <= 1));
});
When("vous rejouez d'ici le coup à revoir", () => {
game.recordAnalyses(analysed);
original = { head: game.journal.head ?? "", events: game.events.length };
const toReview = summarizeAnalysis(game.journal).toReview;
const turn = gameTurns(game.journal)[(toReview?.turn ?? 0) - 1];
assert.ok(turn !== undefined);
const point = replayPoint(game.journal, turn);
assert.ok(point !== null);
game.goBackTo(point);
});
Then("vous avez de nouveau {int}-{int} à jouer", (a: number, b: number) => {
assert.equal(game.state.phase, "moving");
assert.equal(game.state.turn, "player");
assert.deepEqual(game.state.roll, [a, b]);
});
Then("la partie est finie, gagnée par vous", () => {
assert.equal(game.state.result?.winner, "player");
});
Then("la partie a deux branches, dont la partie d'origine, intacte", () => {
const branches = game.branches;
assert.equal(branches.length, 2);
const origin = branches.find((b) => b.forkedFrom === null);
assert.equal(origin?.head, original.head);
assert.ok(origin?.over);
// L'analyse de la partie d'origine reste attachée à ses événements.
assert.ok(game.journal.review !== undefined);
});
Given("une partie finie enregistrée sans aucune analyse", async () => {
dice = [6, 1];
game = Game.start(engine, {
setup: { position: BEAROFF, firstTurn: "player" },
level: "2ply",
dice: fixedDice(dice),
});
await game.roll();
await playMove("6/5 5/off");
await computerDoublesAndPlayerPasses();
const { library } = await openGameLibrary({ localStorage: memoryStorage() });
await library.save("ancienne", game.journal, { level: "2ply" });
const saved = await library.load("ancienne");
assert.ok(saved !== null);
analysed = saved.journal;
assert.equal(analysed.advice, undefined);
assert.equal(analysed.review, undefined);
});
When("vous ouvrez son bilan", () => {
assert.ok(!readyForSummary(analysed));
});
Then("le maître l'analyse d'abord en arrière-plan", async () => {
const before = missingAnalyses(analysed).length;
analysed = await analyse(analysed);
assert.equal(recorded, before);
assert.ok(readyForSummary(analysed));
});
Then("le bilan nomme ensuite le coup à revoir", () => {
const advice = summarizeAnalysis(analysed).toReview?.advice;
assert.equal(advice?.kind === "move" && advice.played.notation, "6/off");
});
+51
View File
@@ -222,6 +222,57 @@ test("les identifiants de partie sont distincts", () => {
assert.match(newGameId(), /^[0-9a-z]+-[0-9a-z]{6}$/);
});
// Régression du test navigateur « mes parties » sous Firefox (disque lent) :
// la nouvelle partie n'est pas perdue quand son enregistrement attend
// derrière ceux, lents, de l'analyse de la partie finie ; seule une lecture
// directe du stockage, hors de la file, peut la précéder.
test("stockage lent : la nouvelle partie est enregistrée après l'analyse de l'ancienne", async () => {
const storage = memoryStorage();
const raw = createKeyValueBackend(storage);
const pause = () => new Promise((resolve) => setTimeout(resolve, 30));
const slow = {
...raw,
write: async (...args: Parameters<typeof raw.write>) => {
await pause();
await raw.write(...args);
},
setCurrentId: async (id: string) => {
await pause();
await raw.setCurrentId(id);
},
};
const games = createGameLibrary(slow, { now: clock() });
const engine = {} as Engine;
const session = createGameSession(games, {
start: () => Game.start(engine, { dice: fixedDice([5, 2]) }),
resume: (j) => Game.resume(engine, j),
});
const finished = session.newGame();
const finishedId = session.shownId as string;
session.save(finished.journal);
assert.equal((await games.current())?.summary.id, finishedId);
// L'analyse de la partie finie s'enregistre en arrière-plan, puis
// « Rejouer » : nouvelle partie, enregistrée sans attendre.
for (let i = 0; i < 5; i++) {
void games.saveAnalyses(finishedId, finished.journal, { level: "2ply" });
}
const next = session.newGame();
session.save(next.journal);
const nextId = session.shownId as string;
assert.notEqual(nextId, finishedId);
// Lue directement, tout de suite : encore l'ancienne partie.
assert.equal(await raw.currentId(), finishedId);
// Lue par la bibliothèque, après les écritures en attente : la nouvelle,
// avec son journal ; l'ancienne reste là.
const current = await games.current();
assert.equal(current?.summary.id, nextId);
assert.deepEqual(current?.journal, next.journal);
assert.equal(await raw.currentId(), nextId);
assert.deepEqual((await games.load(finishedId))?.journal, finished.journal);
});
test("session : « Reprendre l'ancienne » par l'identifiant, et reprise d'une branche", async () => {
const games = library();
// Game.start et Game.resume n'interrogent pas le moteur.
+82
View File
@@ -0,0 +1,82 @@
// Affiche des prompts remplis sur de vraies analyses du moteur, pour les
// relire (étape 1f) : node build/web/tests/tools/prompt-sample.js
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
import { readFileSync } from "node:fs";
import {
missingAnalyses,
runAnalysis,
summarizeAnalysis,
} from "../../src/domain/analysis/game-analysis.js";
import type { Engine } from "../../src/domain/game/engine.js";
import type { GameJournal } from "../../src/domain/game/events.js";
import { Game } from "../../src/domain/game/game.js";
import { positionBefore } from "../../src/domain/prompts/position.js";
import {
decisionPrompt,
summaryPosition,
summaryPrompt,
} from "../../src/domain/prompts/prompts.js";
import {
PROMPT_FILES,
type PromptTemplates,
parsePromptTemplate,
} from "../../src/domain/prompts/templates.js";
import { adviceOn, loadPhrases, playOpening } from "../support/advice.js";
import { loadNodeEngine } from "../support/node-engine.js";
import { playToTheEnd, seededDice } from "../support/play.js";
const root = new URL("../../../../", import.meta.url);
const read = (file: string) =>
parsePromptTemplate(readFileSync(new URL(`docs/prompts/${file}`, root), "utf8"));
const templates: PromptTemplates = {
move: read(PROMPT_FILES.move),
cube: read(PROMPT_FILES.cube),
summary: read(PROMPT_FILES.summary),
concept: read(PROMPT_FILES.concept),
exercises: read(PROMPT_FILES.exercises),
};
const phrases = loadPhrases();
const engine: Engine = await loadNodeEngine();
const played = await playOpening(engine, [3, 1], "24/23 13/10");
const advice = await adviceOn(engine, played);
played.game.recordAdvice(advice);
const position = await positionBefore(engine, played.game.journal, played.eventId);
console.log(decisionPrompt(templates, phrases, { journal: played.game.journal, advice, position }));
async function analyseAll(journal: GameJournal): Promise<GameJournal> {
let current = journal;
for (;;) {
const next = missingAnalyses(current)[0];
if (next === undefined) {
return current;
}
current = await runAnalysis(engine, current, next);
}
}
for (const [seed, choice] of [
[7, 1],
[7, 2],
[11, 2],
[3, 3],
]) {
const game = Game.start(engine, {
setup: { position: "trsXAADs7mwAAA", firstTurn: "player" },
level: "intermediate",
dice: seededDice(seed ?? 0),
});
await playToTheEnd(game, engine, choice);
const journal = await analyseAll(game.journal);
const summary = summarizeAnalysis(journal);
console.log(
`\n=== graine ${seed}, choix ${choice} : coup à revoir ${summary.toReview?.turn ?? "aucun"}`,
);
if (seed === 3) {
const where = await summaryPosition(engine, journal);
console.log(summaryPrompt(templates, phrases, { journal, position: where }));
}
}
+17 -2
View File
@@ -101,8 +101,8 @@ test("chaque position du tutoriel est valide pour le moteur", async () => {
const s = board.sides[side];
return s.points.reduce((a, b) => a + b, 0) + s.bar + s.off;
};
assert.equal(count("player"), 15, `${name} : pions ivoire`);
assert.equal(count("computer"), 15, `${name} : pions noyer`);
assert.equal(count("player"), 15, `${name} : pions blancs`);
assert.equal(count("computer"), 15, `${name} : pions noirs`);
}
});
@@ -174,6 +174,21 @@ test("le joueur peut revenir en arrière après un coup refusé", async () => {
assert.equal(await practice.play({ from: 6, to: 5 }), "right");
});
test("en sortie, un coup déjà complet peut encore mener au coup attendu", async () => {
// Pions sur 6 et 1, jet 6-1 : 6/off seul est déjà un coup complet (même
// position que 6/5/off), mais le coup attendu sort les deux pions.
const engine = await loadNodeEngine();
const first = await MovePractice.start(engine, "BQAACAIAAAAAAA", [6, 1], ["6/off 1/off"]);
assert.equal(await first.play({ from: 6, to: 0 }), "continue");
assert.equal(await first.play({ from: 1, to: 0 }), "right");
const other = await MovePractice.start(engine, "BQAACAIAAAAAAA", [6, 1], ["6/off 1/off"]);
assert.equal(await other.play({ from: 1, to: 0 }), "continue");
assert.equal(await other.play({ from: 6, to: 0 }), "right");
// 6/5 puis 5/off : complet, mais ce n'est pas le coup attendu.
const wrong = await MovePractice.start(engine, "BQAACAIAAAAAAA", [6, 1], ["6/off 1/off"]);
assert.equal(await wrong.play({ from: 6, to: 5 }), "wrong");
});
test("la réponse au double de l'étape 8 est celle du moteur", async () => {
const engine = await loadNodeEngine();
for (const [name, screen] of screens()) {
+10 -6
View File
@@ -209,14 +209,14 @@ test("aide contextuelle : chaque question ouverte depuis la partie existe dans l
});
test("glossaire : nom anglais, renvois, recherche sans accents", () => {
const entry = parseGlossaryEntry(read("docs/glossaire/camp.md"));
const entry = parseGlossaryEntry(read("docs/glossaire/jan-interieur.md"));
assert.ok(entry !== null);
assert.equal(entry.english, "Home board");
assert.deepEqual(
entry.seeAlso.map((s) => s.name),
["sortie", "barre", "point"],
["jan-exterieur", "sortie", "barre", "point"],
);
assert.ok(matchesSearch(entry, "camp"));
assert.ok(matchesSearch(entry, "jan interieur"));
assert.ok(matchesSearch(entry, "HOME"));
assert.ok(matchesSearch(entry, "fleches sortir"));
assert.ok(!matchesSearch(entry, "videau"));
@@ -242,11 +242,15 @@ test("l'aide lit chaque fiche de l'index du glossaire", () => {
});
test("les textes de fin de partie emploient les mots du glossaire", () => {
assert.equal(TEXTS.endTitle("computer", "gammon", false), "L'ordinateur gagne un gammon");
assert.equal(TEXTS.endTitle("computer", "gammon"), "L'ordinateur gagne un gammon");
assert.equal(TEXTS.endDetail("computer", 8, 4), "8 points pour lui, videau à 4.");
assert.equal(TEXTS.endTitle("player", "single", false), "Vous gagnez la partie simple");
assert.equal(TEXTS.endTitle("player", "single"), "Vous gagnez la partie simple");
assert.equal(TEXTS.endDetail("player", 1, 1), "1 point pour vous.");
assert.equal(TEXTS.endTitle("player", "single", true), "L'ordinateur passe");
// Un double passé : le titre donne l'issue, le détail dit comment.
assert.equal(
`${TEXTS.droppedDouble("computer")}${TEXTS.endDetail("computer", 1, 1)}`,
"Vous avez passé son double : 1 point pour lui.",
);
assert.equal(
TEXTS.computerMoved([6, 4], "24/18 13/9"),
"L'ordinateur a joué 6-4 : 24/18 13/9.",
@@ -150,3 +150,55 @@ relira sans recalcul.
conseils ; un conseil reste attaché à son événement, même hors de la
branche courante.
- Le schéma IndexedDB ne change pas : le journal est enregistré tel quel.
### 2026-11-10 — L'analyse de partie rattachée au journal
Avec le bilan de fin de partie et l'écran d'analyse (étape 1e), le journal
d'une partie (`GameJournal`) gagne un second champ facultatif, `review`
(`GameReview`, `app/src/domain/game/review.ts`) : le reste de l'analyse
de la partie par le moteur, à côté des conseils du maître (`advice`) :
- `luck` : la chance de chaque jet (`DiceRolled`, jet d'ouverture compris)
pour le camp qui le joue ;
- `winChances` : les chances de gagner du joueur après chaque coup
(`MovePlayed`), de 0 à 1 ;
- `computer` : les décisions de l'ordinateur, analysées comme celles du
joueur (même format que les conseils) ;
- `unanalysed` : les décisions que le moteur n'analyse pas (videau
inaccessible, position de départ), pour ne plus les redemander ;
- `version` (`REVIEW_VERSION`, 1) et `ply`, le niveau des analyses (2).
Comme les conseils, ce n'est pas un événement : les événements gardent leur
version (2). Les analyses qui manquent (dont tous les conseils d'une partie
jouée avant l'étape 1d) sont calculées en arrière-plan sur le second moteur,
une à une, rangées au fur et à mesure, et l'ensemble s'arrête quand on n'en
a plus besoin (`app/src/ui/review-runner.ts`).
- À la reprise (`migrateJournal`), une analyse d'une autre version ou mal
formée est oubliée ; ses entrées rattachées à un événement absent aussi.
Un journal enregistré avant l'étape 1e n'a pas de champ `review` et se
reprend tel quel. Testé dans `app/tests/game-analysis.test.ts`.
- Une analyse faite en arrière-plan sur une copie du journal s'y range
sans toucher aux conseils déjà là (`withAnalysesOf`).
- Le schéma IndexedDB ne change pas : le journal est enregistré tel quel.
La bibliothèque gagne `saveAnalyses`, qui enregistre le journal analysé
d'une partie sans en faire la partie en cours ni changer la date de sa
dernière action (l'ordre de « Mes parties »).
### 2026-11-11 — Version 2 des conseils : le classement de l'analyse
Le classement des coups d'un conseil (`ranking`) venait d'un second appel au
moteur, comme la commande « hint » de gnubg, alors que le coup joué et le
meilleur coup venaient de l'analyse de partie. Les deux listes diffèrent :
quand le coup joué est une erreur, l'analyse réévalue le meilleur coup et le
coup joué au niveau demandé, ce que « hint » ne fait pas quand un seul coup
passe ses filtres (ouverture 3-1 jouée 24/23 13/10 : 8/5 6/5 à +0,200 à
2 plis dans l'analyse, +0,204 à 1 pli dans « hint »). Le classement vient
désormais de l'analyse même (`engine_analyse_move`, champ `ranking`), comme
le panneau d'analyse de gnubg de bureau.
- `ADVICE_VERSION` passe à 2 (`app/src/domain/game/advice.ts`). Selon la
règle de l'amendement du 2026-11-10, un conseil de la version 1 est oublié
à la reprise et recalculé en arrière-plan ; les analyses de l'ordinateur
(`review.computer`), du même format, aussi.
- Ni les événements (version 2) ni le schéma IndexedDB ne changent.
@@ -108,3 +108,13 @@ avec Gherkin et l'exécution de bout en bout par l'interface.
- **Perspective** : si les scénarios peuvent un jour être joués dans une
instance réelle de l'application, la même exécution produira les captures
d'écran de l'aide, toujours à jour avec la version installée.
### 2026-11-10 — Les prompts pour une IA, même principe
Avec « Demander à une IA » (étape 1f), les gabarits des prompts suivent la
même règle que le glossaire, les scénarios, le tutoriel et les phrases du
maître : une seule source, `docs/prompts/` (un fichier par gabarit, sous
CC BY-SA 4.0), copiée dans le site par `make site` et lue par l'application
à l'exécution ; jamais recopiée dans le code. `make test` remplit chaque
gabarit avec de vraies analyses du moteur (`app/tests/prompts.test.ts`) et
le scénario `docs/scenarios/demander-a-une-ia.feature` en fait l'aide.
+19
View File
@@ -60,3 +60,22 @@ couleur, en monochrome et en taille réelle d'icône (48 et 24 px).
en dessous de 32 px.
- Les icônes Android (premier plan, arrière-plan, monochrome) sont fournies en
SVG ; leur conversion en `VectorDrawable` se fera avec l'application Android.
## Amendements
### 2026-11-11 — Pions blancs et noirs, avec un contour
Retour des premiers joueurs, relayé par Pierre : les pions sombres se voyaient
mal sur la barre, et les joueurs préféraient le blanc et le noir à l'ivoire et
au noyer. Après comparaison sur le canevas (rangée « Retours des premiers
joueurs »), Pierre retient le blanc et le noir, avec un contour.
- Pions du joueur blancs (`#FAFAF7`), contour et filet gris foncé
(`#55554F` en thème clair, pour 3:1 sur les flèches en chêne ; `#6E6E69` en
sombre) ; pions de l'ordinateur noirs (`#1C1C1C`), contour et filet gris
clair (`#B5B5B0`), dans les deux thèmes. Dés et videau suivent les pions.
- Le contour assure la lisibilité partout : pions noirs sur la barre (6,8:1
en thème clair, 8,5:1 en sombre), pions blancs sur le fond clair (3,8:1).
- Le logo ne change pas : ses pions restent ivoire et noyer, qui sont la
matière de la marque, distincte des pièces du jeu.
- Valeurs dans `docs/identite/charte/tokens.json`.
+62
View File
@@ -130,3 +130,65 @@ conseil est enregistré dans le journal (ADR 0007, amendement du
2026-11-10). Un événement sans conseil donne un message, jamais une page
cassée. L'adresse n'a de sens que sur l'appareil qui a joué la partie : ce
n'est pas un lien à partager (le lien de la position, lui, se partage).
### 2026-11-10 — Adresses du bilan et de l'analyse d'une partie
Ajoutées avec le bilan de fin de partie et l'écran d'analyse (étape 1e),
dans le même schéma, sous l'adresse de la partie dans « Mes parties » :
| Écran | Adresse |
| --- | --- |
| Bilan de fin de partie | `#/parties/<id>/bilan` |
| Analyse d'une partie, placée sur un coup | `#/parties/<id>/analyse/<coup>` |
| Analyse d'une partie, sur le coup à revoir | `#/parties/<id>/analyse` |
`<id>` est l'identifiant de la partie enregistrée ; `<coup>` le numéro d'un
tour de la partie (ce qu'un camp a fait quand il avait la main : doubler ou
non, lancer, jouer), à partir de 1, sur sa ligne courante.
- Le bilan remplace le panneau de fin de partie dès que l'analyse est
prête : l'application va à l'adresse du bilan, par-dessus celle de la
partie (`#/`). Il monte au-dessus de la partie, comme une
feuille ; le fermer (croix, retour du téléphone) laisse voir la partie
finie, sans le panneau. « Mes parties » donne le bilan de chaque partie
finie.
- L'analyse est une page. Choisir un autre coup (courbe, flèches, liste)
remplace l'adresse : le retour du téléphone quitte l'écran au lieu de
repasser par chaque coup. « Rejouer d'ici » ramène à la partie (`#/`),
reprise juste avant la décision du coup.
- Comme la feuille d'explication, ces adresses n'ont de sens que sur
l'appareil qui a joué la partie. Une partie absente donne un message,
jamais une page cassée.
### 2026-11-10 — Adresses de la feuille du prompt pour une IA
Ajoutées avec « Demander à une IA » (étape 1f), dans le même schéma. La
feuille montre le prompt pour qu'on le relise avant de le copier : c'est un
écran à part entière, elle a donc son adresse, celle de l'écran d'où on la
demande suivie de `/ia` :
| Écran | Adresse |
| --- | --- |
| Prompt d'une décision, depuis la feuille d'explication du maître | `#/explication/<événement>/ia` |
| Prompt du bilan d'une partie | `#/parties/<id>/bilan/ia` |
| Prompt de la décision d'un coup, depuis l'analyse | `#/parties/<id>/analyse/<coup>/ia` (ou `…/analyse/ia`, sur le coup à revoir) |
| Prompt d'un terme du glossaire | `#/glossaire/<fiche sans .md>/ia` |
- Une seule feuille à la fois : depuis la feuille du maître ou le bilan,
la page du prompt prend la place de leur contenu, à la même hauteur ;
depuis l'analyse ou le glossaire, elle monte dans sa propre feuille.
« ‹ Explication » (« ‹ Bilan », « ‹ Analyse », « ‹ Glossaire »), Échap et
le retour du téléphone reviennent à l'écran d'où on l'a demandée ; la
croix et « Fermer » ferment la feuille, et avec elle la feuille du maître
ou le bilan dont elle avait pris la place. Ouverte par son adresse, sans
historique, le retour remplace l'adresse par celle de l'écran d'avant.
- Rechargée, l'adresse rouvre la même feuille : le prompt est recalculé à
partir du journal enregistré. Comme ses écrans, elle n'a de sens que sur
l'appareil qui a joué la partie (sauf pour le glossaire). Une décision
sans conseil, une partie absente ou pas encore analysée donne un message,
jamais une page cassée.
- La confirmation de la copie (« Copié » sur le bouton, 2 s) n'a pas
d'adresse.
- Le prompt contient, lui, le lien public de la position
(`https://ustagammon.sans.pub/#/position/<Position ID>/<Match ID>`),
qui se partage.
+2 -2
View File
@@ -21,8 +21,8 @@ Repris du cadrage (modules, écrans clés, IA générative en V1) et des ADR 001
| 1b. Parties enregistrées (fait) | 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 (fait) | 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 (fait) | Après chaque coup du joueur, jamais avant (ADR 0011) : appréciation du moteur (bon coup, imprécision, erreur, grosse erreur) 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 |
| 1e. Fin de partie et analyse (fait) | 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 (fait) | 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 |
+6 -1
View File
@@ -40,11 +40,11 @@ exportée. `make test` vérifie le lien dans les deux sens : chaque fiche avec
| [Barre](barre.md) | Bar |
| [Blot](blot.md) | Blot |
| [Branche](branche.md) | Branch |
| [Camp](camp.md) | Home board |
| [Chance](chance.md) | Luck |
| [Compte de points](compte-de-points.md) | Pip count |
| [Conseil du maître](conseil-du-maitre.md) | Advice |
| [Coup](coup.md) | Move |
| [Courbe des chances de gagner](courbe-des-chances.md) | Win chance curve |
| [Demi-coup](demi-coup.md) | Half-move |
| [Course](course.md) | Race |
| [Doubler](doubler.md) | Double |
@@ -53,11 +53,14 @@ exportée. `make test` vérifie le lien dans les deux sens : chaque fiche avec
| [Gammon](gammon.md) | Gammon |
| [Identifiant de match](identifiant-de-match.md) | Match ID |
| [Identifiant de position](identifiant-de-position.md) | Position ID |
| [Jan extérieur](jan-exterieur.md) | Outer board |
| [Jan intérieur](jan-interieur.md) | Home board |
| [Jet](jet.md) | Roll |
| [Lien de position](lien-de-position.md) | Position link |
| [Match](match.md) | Match |
| [Moteur](moteur.md) | Engine |
| [Niveau de jeu](niveau-de-jeu.md) | Level |
| [Notation des coups](notation-des-coups.md) | Move notation |
| [Partie](partie.md) | Game |
| [Partie enregistrée](partie-enregistree.md) | Saved game |
| [Passer](passer.md) | Drop |
@@ -66,8 +69,10 @@ exportée. `make test` vérifie le lien dans les deux sens : chaque fiche avec
| [Pli](pli.md) | Ply |
| [Point](point.md) | Point |
| [Prendre](prendre.md) | Take |
| [Prompt](prompt.md) | Prompt |
| [Règle de Crawford](regle-de-crawford.md) | Crawford rule |
| [Règle de Jacoby](regle-de-jacoby.md) | Jacoby rule |
| [SGF](sgf.md) | SGF |
| [Sortie](sortie.md) | Bear-off |
| [Taux d'erreur](taux-d-erreur.md) | Error rate |
| [Videau](videau.md) | Cube |
-12
View File
@@ -1,12 +0,0 @@
---
term: Camp
english: Home board
---
# Camp
**En bref** : les six dernières flèches d'un joueur, avant sa sortie : il y rassemble ses pions pour les sortir, et un pion adverse frappé doit y rentrer.
Votre camp est en bas à droite (vos flèches 1 à 6) ; celui de l'ordinateur,
en haut à droite (vos flèches 19 à 24), où rentrent vos pions frappés.
Voir aussi : [Sortie](sortie.md), [Barre](barre.md), [Point](point.md)
+24
View File
@@ -0,0 +1,24 @@
---
term: Courbe des chances de gagner
english: Win chance curve
code: WinChanceCurve
---
# Courbe des chances de gagner
**En bref** : vos chances de gagner la partie après chaque coup, selon le moteur, tracées coup après coup en pourcentage.
Après chaque coup, des deux camps, le moteur évalue la position et donne
vos chances de gagner la partie, sans tenir compte du videau. La courbe
monte quand la partie tourne en votre faveur, descend sinon ; la ligne en
pointillé marque 50 %. Le dernier point est le résultat : 100 % si vous avez
gagné, 0 % sinon.
Les points en couleur sont vos coups commentés par le maître, avec la
couleur de leur [appréciation](appreciation.md) ; les petits points sont les
coups de l'ordinateur. Une chute juste après l'un de vos coups montre ce
qu'une erreur a coûté ; une chute après un jet montre la part des dés.
C'est le « graphe d'équité » de GNU Backgammon, en pourcentage plutôt qu'en
équité, plus parlant pour un débutant.
Voir aussi : [Équité](equite.md), [Taux d'erreur](taux-d-erreur.md), [Chance](chance.md)
+15
View File
@@ -0,0 +1,15 @@
---
term: Jan extérieur
english: Outer board
code: OuterBoard
---
# Jan extérieur
**En bref** : les six flèches qui précèdent le jan intérieur d'un joueur : ses pions y passent avant d'y entrer.
Votre jan extérieur est en bas à gauche (vos flèches 7 à 12) ; celui de
l'ordinateur, en haut à gauche (vos flèches 13 à 18). Vos pions partent du jan
intérieur de l'ordinateur, traversent les deux jans extérieurs, puis entrent
dans votre jan intérieur.
Voir aussi : [Jan intérieur](jan-interieur.md), [Point](point.md)
+16
View File
@@ -0,0 +1,16 @@
---
term: Jan intérieur
english: Home board
code: HomeBoard
---
# Jan intérieur
**En bref** : les six dernières flèches d'un joueur avant la sortie : il y rassemble ses quinze pions pour les sortir, et les pions adverses frappés y rentrent.
Le plateau se partage en quatre jans de six flèches. Votre jan intérieur est
en bas à droite (vos flèches 1 à 6) ; celui de l'ordinateur, en haut à droite
(vos flèches 19 à 24) : c'est là que rentrent vos pions frappés. Un pion
adverse resté dans votre jan intérieur à la fin de la partie en fait un
backgammon.
Voir aussi : [Jan extérieur](jan-exterieur.md), [Sortie](sortie.md), [Barre](barre.md), [Point](point.md)
+27
View File
@@ -0,0 +1,27 @@
---
term: Notation des coups
english: Move notation
code: MoveNotation
---
# Notation des coups
**En bref** : un coup s'écrit case de départ/case d'arrivée pour chaque pion, comme 13/7 ; une étoile signale un pion adverse frappé (24/22*), « off » un pion sorti (6/off), « bar » un pion qui rentre depuis la barre (bar/22), et (2) un déplacement fait deux fois avec un double (8/4(2)).
Ustagammon écrit les coups comme GNU Backgammon, le moteur qui les calcule.
Chaque joueur numérote les cases de son propre point de vue, de 1 (la case la
plus proche de sa sortie) à 24 :
- `13/7` : un pion part de la case 13 et arrive sur la case 7. Un coup de deux
dés compte en général deux déplacements, séparés par une espace :
`13/7 8/7`.
- `24/22*` : l'étoile dit que le pion arrivé sur la 22 y a frappé un pion
seul de l'adversaire, qui part sur la barre.
- `6/off` : le pion de la case 6 sort du plateau.
- `bar/22` : un pion qui était sur la barre rentre sur la case 22.
- `8/4(2)` : le même déplacement, fait deux fois. Avec un double, on joue
quatre fois le dé : `8/4(2) 6/2(2)` déplace deux pions de 8 à 4 et deux de
6 à 2.
- `13/1*` : un seul pion qui avance avec ses deux dés s'écrit d'un trait,
de sa case de départ à sa case d'arrivée.
Voir aussi : [Coup](coup.md), [Demi-coup](demi-coup.md), [Barre](barre.md), [Sortie](sortie.md), [Blot](blot.md)
+16
View File
@@ -0,0 +1,16 @@
---
term: Prompt
english: Prompt
code: Prompt
---
# Prompt
**En bref** : la question toute prête que l'application copie pour une IA (« Demander à une IA ») : la position, les chiffres de GNU Backgammon, et ce qu'on demande ; il suffit de la coller dans l'IA de votre choix.
L'application n'appelle aucune IA et n'envoie rien : elle prépare le texte,
vous le relisez, vous le copiez. Le moteur décide, l'IA explique : le prompt
lui demande de ne pas contredire les évaluations de GNU Backgammon, qui
restent celles que l'application affiche. Il contient aussi le lien de la
position, pour la retrouver dans l'application.
Voir aussi : [Lien de position](lien-de-position.md), [Moteur](moteur.md), [Conseil du maître](conseil-du-maitre.md)
+36
View File
@@ -0,0 +1,36 @@
---
term: Taux d'erreur
english: Error rate
code: ErrorRate
---
# Taux d'erreur
**En bref** : l'équité que vous avez perdue en moyenne à chaque décision de la partie, d'après le moteur ; plus il est bas, mieux vous avez joué.
Le moteur compare chacun de vos coups et chacune de vos décisions de videau
au meilleur choix, et note l'équité perdue (0 pour le meilleur coup). Le
taux d'erreur additionne ces pertes et les divise par le nombre de
décisions qui comptent : les coups où vous aviez le choix (un coup forcé ne
compte pas), vos doubles, vos prises et vos refus, et vos jets sans doubler
quand doubler se discutait. C'est le calcul de GNU Backgammon (« Error rate
per decision »).
Le bilan traduit ce taux en niveau, avec les seuils de GNU Backgammon et
les noms des niveaux de l'ordinateur, dans le même ordre :
| Équité perdue par décision | Classement de GNU Backgammon | Niveau dans Ustagammon |
| --- | --- | --- |
| moins de 0,005 | Super Grandmaster | Champion |
| 0,005 à 0,008 | Grandmaster | Expert |
| 0,008 à 0,013 | Master | Avancé |
| 0,013 à 0,020 | Advanced | Intermédiaire |
| 0,020 à 0,032 | Intermediate | Amateur |
| 0,032 et plus | Beginner | Débutant |
Le bilan montre à côté la [chance](chance.md) de vos dés sur la partie : par
tour, la chance de vos jets ; « un peu » pour vous ou contre vous au-delà de
0,03 par tour, « nettement » au-delà de 0,06, comme GNU Backgammon. La
phrase du bilan compare enfin le résultat à ce qu'il aurait été sans la
chance des deux camps : si l'écart vient surtout des dés, elle le dit.
Voir aussi : [Appréciation](appreciation.md), [Chance](chance.md), [Équité](equite.md), [Courbe des chances de gagner](courbe-des-chances.md)
+34 -15
View File
@@ -76,9 +76,11 @@ interrompre.
demande au moteur si le coup du joueur fait partie des coups permis attendus.
- **Les pions bougent** : sur un écran d'explication, le coup illustré se joue
tout seul après une seconde, pion par pion (`duration-fast`), puis reste
affiché ; « Revoir » le rejoue. Sur les écrans à flèches (sens du jeu), un
tracé en pointillés `text` sur un liseré ivoire, jamais en brique (la brique
veut dire « à faire »).
affiché ; « Revoir » le rejoue. Sur l'écran du sens du jeu, **deux flèches
circulaires** : une claire pour vos pions, une sombre pour ceux de
l'ordinateur, chacune dans le sens de son joueur et finissant par une pointe,
dessinées sous les pions, avec un liseré de la couleur opposée pour rester
lisibles sur le plateau ; jamais en brique (la brique veut dire « à faire »).
- Un geste juste : coche `verdict-good`, vibration « pion posé », phrase
courte, « Continuer » devient l'action principale. Un geste faux : le pion
revient, et une phrase dit pourquoi, sans le mot « erreur ».
@@ -87,14 +89,14 @@ interrompre.
### Texte, première version
1. **Le but du jeu.** « Vous avez quinze pions ivoire, l'ordinateur quinze
pions noyer. Chacun fait faire le tour du plateau à ses pions, puis les
1. **Le but du jeu.** « Vous avez quinze pions blancs, l'ordinateur quinze
pions noirs. Chacun fait faire le tour du plateau à ses pions, puis les
sort. Le premier qui a sorti tous les siens gagne la partie. »
2. **Dans quel sens avancer.** « Vos pions ivoire font le tour du plateau dans
le sens des pointillés : ils partent d'en haut à droite, passent à gauche,
puis reviennent en bas jusqu'aux six dernières flèches, en bas à droite.
C'est là que vous les rassemblerez avant de les sortir. Les pions noyer de
l'ordinateur font le même chemin, en sens inverse. »
2. **Dans quel sens avancer.** « Vos pions suivent la flèche claire : ils
partent d'en haut à droite, passent à gauche, puis reviennent en bas jusqu'à
votre jan intérieur, les flèches 1 à 6. C'est là que vous les rassemblez
avant de les sortir. Les pions de l'ordinateur suivent la flèche sombre, en
sens inverse, jusqu'à son jan intérieur, les flèches 19 à 24. »
3. **Les dés et les doubles.** « Chaque dé déplace un pion d'autant de
flèches. Avec 5 et 2, vous jouez un pion de 5 et un pion de 2, ou le même
pion de 5 puis de 2. Un double se joue quatre fois : avec 4-4, vous avancez
@@ -106,16 +108,16 @@ interrompre.
point 7 avec 6-1.
5. **Rentrer depuis la barre.** « Votre pion frappé attend sur la barre, au
milieu. Avant de jouer quoi que ce soit d'autre, il doit rentrer dans le
camp adverse, en haut à droite. Chaque dé indique une flèche d'entrée :
jan intérieur de l'ordinateur, en haut à droite. Chaque dé indique une flèche d'entrée :
avec 3 et 4, la 22 ou la 21. Si les deux flèches sont fermées, votre tour
passe. »
6. **Sortir ses pions.** « Quand vos quinze pions sont dans les six dernières
flèches, vous pouvez commencer à les sortir : un 6 sort un pion de la
6. **Sortir ses pions.** « Quand vos quinze pions sont dans votre jan intérieur
(flèches 1 à 6), vous pouvez commencer à les sortir : un 6 sort un pion de la
flèche 6, un 1 un pion de la flèche 1. Touchez le pion, puis la sortie à
droite. » *À vous* : sortir deux pions avec 6-3.
7. **Gammon et backgammon.** « Une partie gagnée vaut 1 point. Si
l'adversaire n'a sorti aucun pion, c'est un gammon : 2 points ; s'il lui
reste en plus un pion sur la barre ou dans votre camp, c'est un
reste en plus un pion sur la barre ou dans votre jan intérieur, c'est un
backgammon : 3 points. En partie libre, gammon et backgammon ne comptent
que si le videau a été doublé : c'est la règle de Jacoby. »
8. **Le videau.** « Le cube aux faces 2, 4, 8, 16, 32 et 64 sert à miser.
@@ -164,7 +166,7 @@ ouvrir, partager et retrouver avec le bouton « retour » du téléphone.
| « Je découvre », « Toutes les leçons » | `#/tutoriel/1` |
| Étape *n* du tutoriel (« Continuer », « Retour », segments de la barre de progression) | `#/tutoriel/<n>` |
| « Je connais les règles », « Reprendre la partie » | l'écran de jeu |
| Un terme du jeu dans un texte (blot, barre, camp…) | `#/glossaire/<terme>` |
| Un terme du jeu dans un texte (blot, barre, jan intérieur…) | `#/glossaire/<terme>` |
| Une position illustrée, « Voir sur le plateau » | `#/position/<Position ID>/<Match ID>` |
| Aide, onglet « Jouer » | `#/aide` ; une question ouverte : `#/aide/<scénario>` |
| Menu | `#/menu` |
@@ -174,3 +176,20 @@ ouvrir, partager et retrouver avec le bouton « retour » du téléphone.
- Le bouton « retour » du téléphone ferme d'abord la feuille ou la question
ouverte, puis revient à l'écran précédent ; il ne quitte jamais une partie
sans retour possible.
## Vocabulaire : les jans
Le plateau se partage en quatre jans de six flèches. Les nommer simplifie les
explications (retour des premiers joueurs, 2026-11-11) :
| Flèches | Nom |
| --- | --- |
| 1 à 6 | votre jan intérieur |
| 7 à 12 | votre jan extérieur |
| 13 à 18 | le jan extérieur de l'ordinateur |
| 19 à 24 | le jan intérieur de l'ordinateur |
Le tutoriel, l'aide, le maître et les leçons emploient ces mots, avec un lien
vers leur fiche du glossaire à la première apparition. Fiches à créer :
`jan-interieur.md` (anglais : home board) et `jan-exterieur.md` (anglais :
outer board). « Camp » n'est plus employé dans les textes.
+42 -12
View File
@@ -38,8 +38,8 @@ Ouvert depuis le menu, l'accueil et la fin de partie. Une seule page, sans
3. **Pendant la partie** : interrupteur « Conseil du maître », sous-titre
« Une ligne après chacun de vos coups ».
4. **Barre d'action collée en bas** : un seul bouton principal, qui dit ce
qu'il lance (« Commencer la partie » ou « Commencer le match en 5
points »), et la mention « Vos choix sont gardés pour la prochaine fois. ».
qu'il lance (« Commencer la partie » ou « Commencer le match » ; choix
de Pierre du 2026-11-11, la longueur se lit déjà sur le bouton choisi), et la mention « Vos choix sont gardés pour la prochaine fois. ».
Par défaut : partie libre, Intermédiaire, conseil activé. Fermer (croix en
haut à gauche, ou retour du téléphone) ne change rien à la partie en cours.
@@ -78,7 +78,11 @@ Maquette « Portrait révisé : conseil du maître après le coup ». Une ligne
trop tard (le joueur a déjà relancé), la ligne n'apparaît pas, et le coup
reste commenté dans le bilan ;
- conseil désactivé : la ligne reste réservée et vide (la mise en page ne
bouge pas).
bouge pas) ;
- tant qu'elle est affichée, elle prend la place de « L'ordinateur a joué… »
(les traces laiton et ↻ restent) ;
- **en paysage** : une pastille (pictogramme et mot d'appréciation) en tête
de la bande centrale, à gauche de la consigne ; la toucher ouvre la feuille.
### Les mots
@@ -89,7 +93,7 @@ Maquette « Portrait révisé : conseil du maître après le coup ». Une ligne
| 0,06 à 0,12 (bad) | Erreur | `verdict-bad` | croix |
| plus de 0,12 (very bad) | Grosse erreur | `verdict-bad` | croix |
Pour le videau : « Bon choix » et « Bonne décision » remplacent « Bon coup ».
Pour le videau : « Bonne décision » remplace « Bon coup ».
« Grosse erreur » est la recommandation de design ; `docs/etape-1.md` écrit
« gaffe », et le choix final revient à Pierre (ton).
@@ -130,13 +134,17 @@ permet de le déterminer, sinon rien.
de superlatif. Les bons coups ont plusieurs formules qui tournent
(« C'est le coup du maître. », « Exactement ce que j'aurais joué. »,
« Bien vu. »), pour ne pas lasser.
- **Le rang de votre coup** n'est cité que pour un bon coup qui n'est pas le
meilleur et pour une imprécision, et seulement s'il vaut 2 ou 3. Jamais pour
une erreur ni une grosse erreur : le rang mesure mal la gravité (« 2e
choix » peut cacher un écart de 0,2). Le classement complet reste dans
« Voir les chiffres du moteur ».
- **Exemples** (gabarits à remplir avec les données du moteur) :
- Bon coup : « Bien vu. 8/5 6/5 fait votre point 5. »
- Imprécision : « J'aurais joué {meilleur}. Votre coup était le
{rang}e choix, tout près. »
- Erreur : « J'aurais joué {meilleur}. Votre {joué} était le {rang}e
choix. »
- Videau, prise juste : « Bonne décision : prendre était le bon choix. »
- Erreur : « J'aurais joué {meilleur}. Mon coup fait votre point 5. »
- Videau, prise juste : « Prendre était le bon choix. »
- Videau, double manqué : « Ici, j'aurais doublé. »
## 1e. Bilan et analyse
@@ -198,9 +206,21 @@ Sur ordinateur, `←` et `→` passent d'un coup à l'autre.
Le bouton est secondaire partout, jamais l'action principale, avec l'icône
de copie : dans la feuille du maître (1d), dans la carte « Le coup à
revoir » du bilan, dans le visualiseur de l'analyse, et dans une fiche du
glossaire. Après la copie, le bandeau « Prompt copié » (`verdict-good`, 2 s),
puis le texte du prompt reste lisible dans une zone `surface-sunken`
repliable, pour qui veut le relire avant de le coller (composant `AskAI`).
glossaire. Le bouton ouvre la feuille du prompt : le texte y est lisible
dans une zone `surface-sunken`, pour qui veut le relire avant de le copier
(composant `AskAI`).
Recette de 1f :
- **Une seule feuille à la fois.** Depuis la feuille du maître, la feuille
du prompt en remplace le contenu, à la même hauteur, avec « ‹ Explication »
en haut à gauche pour revenir ; de même depuis le bilan (« ‹ Bilan »).
Depuis l'analyse et le glossaire, elle monte seule (« ‹ Analyse »,
« ‹ Glossaire »). Le retour du téléphone ramène à l'écran précédent.
- **La copie se confirme sur le bouton**, sans bandeau : « Copier le
prompt » devient « ✓ Copié » (coche, `verdict-good`) pendant 2 s, puis
revient. Si le navigateur refuse la copie, le texte est sélectionné et
une phrase invite à le copier avec le menu du téléphone.
## 1g. Leçons (`#/lecons`, `#/lecons/<n>/<écran>`)
@@ -216,8 +236,18 @@ l'ordre, chacune avec une pastille ronde à son numéro :
Toutes les leçons restent ouvertes : l'ordre est conseillé, jamais imposé.
Les écrans d'une leçon suivent la forme du tutoriel (barre de progression,
« Passer », « Retour », « Continuer », écrans « à vous » contrôlés par le
moteur).
« Quitter », « Retour », « Continuer », écrans « à vous » contrôlés par le
moteur), aux adresses `#/lecons/<n>/<écran>`, `…/a-vous` et `…/fin`.
- Une leçon est **terminée** quand tous ses exercices sont réussis.
- « Retour » et « Continuer » restent **en bas de l'écran**, sous le pouce,
comme dans le tutoriel, quelle que soit la longueur du texte.
- « Revoir » (rejouer le coup illustré) se place sur la ligne du titre, à
droite, en portrait comme en paysage : le texte garde toute la largeur.
- En paysage, la colonne de droite garde la ligne `caption` « Leçon 1 · 1 sur
4 · À vous » au-dessus du titre.
- Les titres et les textes n'emploient que les mots du glossaire : « point »
et « flèche », jamais « case ».
## 1h. Progression (`#/progression`)
+1 -1
View File
@@ -22,7 +22,7 @@ La palette, c'est le bois, les pions et le café, avec **un seul accent : le rou
- `accent-soft` : fond léger pour signaler « c'est à vous », avec du texte `text` dessus.
- Les appréciations de coups ont leurs propres couleurs, distinctes de la brique : `verdict-good` (vert), `verdict-doubtful` (ocre), `verdict-bad` (lie-de-vin). **Toujours avec le mot et l'icône**, jamais la couleur seule.
- `brand-laiton` (via `last-move`) marque le dernier coup joué, comme les charnières en laiton d'un plateau de tavla. Rien d'autre.
- Le plateau : cadre `frame` en noyer, fond `bed`, flèches impaires en `point-a` (noyer clair) et paires en `point-b` (chêne), barre `bar`, sorties `tray`. Le joueur a les pions ivoire (`checker-player`, l'apprenti), l'ordinateur les pions noyer (`checker-computer`, le maître), comme dans le logo.
- Le plateau : cadre `frame` en noyer, fond `bed`, flèches impaires en `point-a` (noyer clair) et paires en `point-b` (chêne), barre `bar`, sorties `tray`. Le joueur a les pions blancs (`checker-player`), l'ordinateur les pions noirs (`checker-computer`), chacun avec un contour et un filet (`checker-player-edge`, `checker-computer-edge`) qui le détachent de tous les fonds ; les pions du logo restent ivoire et noyer (ADR 0010, amendement du 2026-11-11).
- **À éviter** : le vert feutre de casino, le noir et or, les dégradés, les néons.
Les deux thèmes, clair et sombre, sont complets. Tous les textes atteignent 4,5:1 sur leurs fonds dans les deux thèmes ; les contours et marques porteuses de sens, 3:1.
+3
View File
@@ -8,6 +8,9 @@ Référence : `interaction.md`, maquettes « Révision UX » du canevas.
## Toutes tailles
- [ ] Flèches impaires en `point-a`, paires en `point-b` ; 12 et 13 de couleurs différentes.
- [ ] Numéros des flèches à l'extérieur du plateau, sur le cadre (bande haute et bande basse), en portrait comme en paysage ; jamais dans le fond du plateau entre les deux rangées. (Vérifié par `tests/browser/retours-joueurs.mjs`.)
- [ ] Pions du joueur lisibles partout : en thème clair, contour `checker-player-edge` à 3:1 au moins sur les flèches en chêne et sur le fond. Règle automatique : `checkerContrastProblems` de `tests/browser/recette.mjs`.
- [ ] Pions de l'ordinateur lisibles partout : contour et filet `checker-computer-edge` (gris clair) visibles sur la barre, sur les flèches sombres et en thème sombre. Règle automatique : là où sa couleur ne se détache pas de son fond (moins de 3:1), son contour s'en détache à 3:1 au moins (`checkerContrasts` de `tests/browser/recette.mjs`).
- [ ] Une seule action principale (brique) visible à la fois.
- [ ] Aucun `window.confirm` ni `alert` dans le code de l'app (`grep -rn "confirm(\|alert(" app/src` vide).
- [ ] Aucune cible tactile sous 44 × 44 px (boutons, pictogrammes, dés, videau).
+32 -32
View File
@@ -216,96 +216,96 @@
{
"name": "checker-player",
"value": {
"light": "#F7F0E2",
"dark": "#EDE3CF"
"light": "#FAFAF7",
"dark": "#F2F2EF"
},
"usage": "Pions du joueur : ivoire, l'apprenti."
"usage": "Pions du joueur : blancs."
},
{
"name": "checker-player-edge",
"value": {
"light": "#8C7A62",
"dark": "#8E7C64"
"light": "#55554F",
"dark": "#6E6E69"
},
"usage": "Contour et filet des pions du joueur."
"usage": "Contour des pions blancs. Thème clair : #55554F, pour 3:1 au moins sur les flèches en chêne (3,5:1) et le fond (5,5:1). Thème sombre : le pion blanc se détache déjà par sa couleur (plus de 5:1)."
},
{
"name": "checker-computer",
"value": {
"light": "#2E1C12",
"dark": "#140D09"
"light": "#1C1C1C",
"dark": "#141414"
},
"usage": "Pions de l'ordinateur : noyer sombre, le maître."
"usage": "Pions de l'ordinateur : noirs."
},
{
"name": "checker-computer-edge",
"value": {
"light": "#120A05",
"dark": "#A8957D"
"light": "#B5B5B0",
"dark": "#B5B5B0"
},
"usage": "Contour et filet des pions de l'ordinateur ; clair en thème sombre pour rester visible."
"usage": "Contour et filet des pions noirs : gris clair dans les deux thèmes, pour qu'ils se détachent de la barre, des flèches sombres et du fond sombre."
},
{
"name": "count-player",
"value": {
"light": "#2B1D15",
"dark": "#2B1D15"
"light": "#1C1C1C",
"dark": "#1C1C1C"
},
"usage": "Nombre écrit sur une pile de pions du joueur."
"usage": "Nombre écrit sur une pile de pions blancs."
},
{
"name": "count-computer",
"value": {
"light": "#F3EAD8",
"dark": "#F3EAD8"
"light": "#FAFAF7",
"dark": "#FAFAF7"
},
"usage": "Nombre écrit sur une pile de pions de l'ordinateur."
"usage": "Nombre écrit sur une pile de pions noirs."
},
{
"name": "die-player",
"value": {
"light": "#F7F0E2",
"dark": "#EDE3CF"
"light": "#FAFAF7",
"dark": "#F2F2EF"
},
"usage": "Dés du joueur."
"usage": "Dés du joueur, blancs comme ses pions."
},
{
"name": "pip-player",
"value": {
"light": "#2B1D15",
"dark": "#2B1D15"
"light": "#1C1C1C",
"dark": "#1C1C1C"
},
"usage": "Points des dés du joueur."
},
{
"name": "die-computer",
"value": {
"light": "#2E1C12",
"dark": "#140D09"
"light": "#1C1C1C",
"dark": "#141414"
},
"usage": "Dés de l'ordinateur."
"usage": "Dés de l'ordinateur, noirs comme ses pions."
},
{
"name": "pip-computer",
"value": {
"light": "#F3EAD8",
"dark": "#EDE3CF"
"light": "#FAFAF7",
"dark": "#F2F2EF"
},
"usage": "Points des dés de l'ordinateur."
},
{
"name": "cube",
"value": {
"light": "#F7F0E2",
"dark": "#EDE3CF"
"light": "#FAFAF7",
"dark": "#F2F2EF"
},
"usage": "Face du videau."
},
{
"name": "cube-text",
"value": {
"light": "#2B1D15",
"dark": "#2B1D15"
"light": "#1C1C1C",
"dark": "#1C1C1C"
},
"usage": "Valeur du videau (2, 4, 8…)."
},
+52 -2
View File
@@ -1,7 +1,8 @@
# Les phrases du maître
Les mots et les phrases du conseil du maître (étape 1d), en une seule source
(ADR 0008) : `make site` copie ce dossier dans le site publié
Les mots et les phrases du conseil du maître (étape 1d) et du bilan de fin
de partie (étape 1e), en une seule source (ADR 0008) : `make site` copie ce
dossier dans le site publié
(`docs/maitre/`), l'application le lit à l'exécution
(`app/src/domain/analysis/phrases.ts`), et `make test` rend chaque gabarit
sur de vraies analyses du moteur (`app/tests/advice.test.ts`).
@@ -37,6 +38,7 @@ mots entre accolades sont remplis avec les données du moteur :
| `{points}` | « votre point 5 » ou « vos points 5 et 7 » |
| `{roll}` | le jet, « 3-1 » |
| `{hits}` | le nombre de pions frappés, en chiffres |
| `{dice}` | la chance de vos dés sur la partie, en mots (bilan, étape 1e) |
Un fait (sections `fait.…`) s'ajoute à la phrase seulement si la ligne reste
sous 140 caractères.
@@ -231,3 +233,51 @@ Grosse erreur : le rang n'est jamais cité.
## contexte.videau.reponse
- le double de l'ordinateur
## bilan.jeu.gagne
Bilan de fin de partie (étape 1e), partie gagnée, quand le résultat corrigé
de la chance (celui qu'on aurait eu sans les dés, à la manière de gnubg)
reste en votre faveur. {dice} : la chance de vos dés sur la partie (sections
bilan.des.…).
- D'après mon analyse, votre jeu a fait la différence, avec des dés {dice}.
## bilan.jeu.perdu
Partie perdue, le résultat corrigé de la chance restant en faveur de
l'ordinateur.
- D'après mon analyse, le jeu de l'ordinateur a fait la différence, avec des dés {dice}.
## bilan.des
Partie gagnée ou perdue, le résultat corrigé de la chance allant dans
l'autre sens que le résultat : les dés des deux camps ont pesé plus que les
erreurs.
- D'après mon analyse, les dés ont fait la différence, plus que le jeu.
## bilan.des.tres-pour
- nettement pour vous
## bilan.des.pour
- un peu pour vous
## bilan.des.neutres
- équilibrés
## bilan.des.contre
- un peu contre vous
## bilan.des.tres-contre
- nettement contre vous
## bilan.aucun-coup
- Aucun coup à revoir : vous avez joué comme je l'aurais fait.
-46
View File
@@ -1,46 +0,0 @@
# Fin de partie et analyse (1e)
- **Date** : 2026-11-03
- **Étape** : 1e (`docs/etape-1.md`)
- **Statut** : prévu (après 1d)
- **Exécutant** : sous-agent general-purpose, dans un worktree
## Objectif
Que le joueur comprenne sa partie : le bilan de fin de partie (ADR 0011), puis un écran d'analyse avec graphe d'équité, liste des erreurs, visualiseur et « Rejouer d'ici ».
## Consignes
Respecter les ADR 0007, 0008, 0011 et 0013. Chaque écran a son adresse : `#/parties/<id>/bilan` et `#/parties/<id>/analyse/<coup>`, à ajouter au tableau de l'ADR 0013 par un amendement. Pour la charte, suivre les maquettes « Fin de partie » du canevas. Aucune nouvelle dépendance : le graphe est dessiné en SVG à la main.
1. **Analyse de la partie.** Elle réutilise les analyses rangées par 1d (coups et videau) et complète celles qui manquent en arrière-plan, de façon progressive et annulable. Elle donne :
- le taux d'erreur à la manière de gnubg ;
- la chance aux dés (`luck`) pour chaque camp ;
- le décompte des coups par appréciation.
2. **Bilan**, dans le panneau de fin de partie existant :
- le résultat ;
- les coups par appréciation ;
- le taux d'erreur comparé à la chance, en phrases simples ;
- « le coup à revoir » : la plus grosse erreur, avec sa position, le coup joué et le meilleur coup ;
- un emplacement pour le bouton « Demander à une IA » (1f) ;
- « Voir l'analyse ».
3. **Écran d'analyse** :
- un graphe d'équité où toucher un point ouvre la position ;
- la liste des erreurs, filtrable par appréciation ;
- un visualiseur pas à pas qui montre sur le plateau le coup joué contre le meilleur coup, avec des pions animés ;
- « Rejouer d'ici », qui crée une branche (domaine de 1b) sans toucher l'original.
4. **Tests** :
- scénarios Gherkin : bilan, coup à revoir, rejouer d'ici, chacun avec des dés imposés ;
- fiches du glossaire : taux d'erreur, graphe d'équité si absentes ;
- `make lint`, `make test`, `make test-browser`, avec des captures pour la recette design.
## Critères de réussite
- Après une partie, le bilan nomme le coup à revoir, conforme à l'analyse du moteur.
- L'analyse s'ouvre par son adresse.
- « Rejouer d'ici » crée une branche.
- Les trois commandes passent.
## Résultat
À remplir à la clôture.
-42
View File
@@ -1,42 +0,0 @@
# Prompts à copier (1f)
- **Date** : 2026-11-03
- **Étape** : 1f (`docs/etape-1.md`)
- **Statut** : prévu (après 1e)
- **Exécutant** : sous-agent general-purpose, dans un worktree
## Objectif
Mettre en place la section « IA générative en V1 » du cadrage. Un bouton « Demander à une IA » copie un prompt rempli avec le contexte exact. Le moteur décide, l'IA explique. L'app n'appelle aucune IA.
## Consignes
1. **Gabarits.** Les cinq gabarits du cadrage sont versionnés dans une source unique sous `docs/prompts/`, sous licence CC BY-SA 4.0 :
- « pourquoi ce coup est meilleur » ;
- « expliquer cette décision de videau » ;
- « bilan de ma partie » ;
- « expliquer ce concept » ;
- « créer des exercices », à garder pour la progression.
Chaque gabarit contient :
- le rôle et le niveau du joueur ;
- le Position ID et le Match ID ;
- un diagramme texte de la position, produit à partir du plateau décodé par le moteur ;
- les chiffres du moteur, avec le niveau d'évaluation ;
- la consigne de ne pas contredire ces chiffres ;
- la langue.
Ajouter aussi le lien `#/position/...` de l'ADR 0013, avec l'adresse publique du site.
2. **Remplissage.** Une fonction pure remplit les gabarits. Elle est testée sur des analyses réelles du moteur : aucun champ vide ni `{inconnu}`, et les chiffres sont identiques à ceux du moteur.
3. **Boutons.** Ils sont placés sur le conseil du maître (feuille d'explication), le bilan, l'analyse et la fiche d'un terme du glossaire. La copie passe par `navigator.clipboard`, avec un repli de sélection du texte. Un bandeau « Prompt copié » l'accompagne, et le texte reste visible pour qui veut le relire.
4. **Tests.**
- Scénarios Gherkin : copier le prompt d'une erreur, et celui d'un bilan.
- `make lint`, `make test` et `make test-browser`, avec lecture du presse-papiers dans Chromium et captures.
## Critères de réussite
Le prompt copié après une erreur contient la position, les identifiants gnubg et le top 3 du moteur avec les mêmes chiffres que l'app. Les trois commandes passent.
## Résultat
À remplir à la clôture.
+58
View File
@@ -0,0 +1,58 @@
# Les prompts à copier pour une IA
Les textes que l'application copie dans le presse-papiers quand on touche
« Demander à une IA » (étape 1f ; `docs/cadrage.md`, « IA générative en
V1 »). L'application n'appelle aucune IA : elle prépare une question
complète, que le joueur colle dans l'IA de son choix. Règle d'or : **le
moteur décide, l'IA explique**.
Une seule source (ADR 0008) : `make site` copie ce dossier dans le site
publié (`docs/prompts/`), l'application lit les gabarits à l'exécution
(`app/src/domain/prompts/`), et `make test` remplit chacun d'eux avec de
vraies analyses du moteur (`app/tests/prompts.test.ts`) : aucun repère
laissé vide, et les chiffres du prompt sont ceux que l'application affiche.
Textes sous licence **CC BY-SA 4.0**. Version 1, rédigée par Claude Code
d'après le cadrage, **à relire** par Pierre.
## Les gabarits
| Fichier | Bouton | Où |
| --- | --- | --- |
| [coup.md](coup.md) | Pourquoi ce coup est meilleur | Feuille du maître, bilan, analyse |
| [videau.md](videau.md) | Expliquer cette décision de videau | Feuille du maître, bilan, analyse |
| [bilan.md](bilan.md) | Bilan de ma partie | Bilan de fin de partie |
| [concept.md](concept.md) | Expliquer ce concept | Fiche d'un terme du glossaire |
| [exercices.md](exercices.md) | Créer des exercices | Progression (étape 1h, pas encore de bouton) |
Chaque prompt contient :
- le rôle de l'IA (un coach) et, quand il est mesuré, le niveau du joueur ;
- la position : Position ID et Match ID de GNU Backgammon, le lien qui
l'ouvre dans l'application (`https://ustagammon.sans.pub/#/position/…`,
ADR 0013) et un diagramme texte dessiné d'après le plateau décodé par le
moteur ;
- les chiffres du moteur, avec le niveau d'évaluation (en plis) ;
- la consigne de ne pas recalculer ni contredire ces chiffres ;
- la langue de la réponse.
## Format
Dans chaque fichier, le gabarit est le bloc de texte qui suit le titre
`## Gabarit`. Le reste du fichier n'est pas lu. Les mots entre accolades sont
remplis par l'application ; un repère inconnu ou une valeur vide est une
erreur, vérifiée par les tests.
Repères communs à plusieurs gabarits :
| Repère | Ce qu'il devient |
| --- | --- |
| `{joueur}` | « Je suis un joueur de niveau Avancé. », le niveau que donne GNU Backgammon d'après l'erreur par décision, seulement à partir de 20 décisions analysées ; en dessous, « Je débute au backgammon. ». Le taux d'erreur lui-même n'apparaît que dans le bilan. |
| `{position_id}`, `{match_id}` | les identifiants de GNU Backgammon de la position |
| `{au_trait}` | « moi » ou « l'ordinateur » : celui dont les identifiants décrivent le point de vue |
| `{lien}` | l'adresse de la position dans l'application publiée |
| `{diagramme}` | le plateau en texte : vos pions X, ceux de l'ordinateur O, dans votre numérotation |
| `{score}` | « partie libre » ou le score du match |
| `{videau}` | sa valeur et qui le possède |
| `{niveau_eval}` | le niveau d'évaluation de GNU Backgammon, « analyse à 2 plis » ; pour un classement de coups, celui auquel le moteur a évalué le meilleur coup (voir [coup.md](coup.md)) |
| `{langue}` | la langue de la réponse : « français » |
+44
View File
@@ -0,0 +1,44 @@
# Bilan de ma partie
Bouton « Demander à une IA » de la carte « Le coup à revoir » du bilan de
fin de partie. Texte sous licence CC BY-SA 4.0 (voir
[README.md](README.md)).
Repères propres à ce gabarit :
| Repère | Ce qu'il devient |
| --- | --- |
| `{ordinateur}` | le niveau de l'ordinateur, « Intermédiaire » |
| `{resultat}` | le résultat de la partie, et le score du match s'il y en a un |
| `{decomptes}` | vos décisions par appréciation, comme les trois cases du bilan |
| `{taux}`, `{decisions}`, `{niveau_jeu}` | votre erreur par décision, le nombre de décisions comptées et le niveau correspondant, comme « Voir les chiffres du moteur » de l'analyse |
| `{taux_ordinateur}` | la même mesure pour l'ordinateur |
| `{chance}`, `{chance_mots}`, `{chance_ordinateur}` | la chance par tour de vos dés, en chiffres et en mots, et celle de l'ordinateur |
| `{erreurs}` | vos imprécisions et erreurs, coup par coup, avec leur coût |
| `{position_titre}` | ce que montre la position : le coup à revoir, ou la position finale s'il n'y en a pas |
## Gabarit
```text
Tu es un coach de backgammon, bienveillant et précis. {joueur}
Je viens de finir une partie contre l'ordinateur (niveau {ordinateur}), analysée par GNU Backgammon ({niveau_eval}).
Résultat : {resultat}.
Mes décisions : {decomptes}.
Mon erreur par décision : {taux} sur {decisions}, soit le niveau {niveau_jeu} ; celle de l'ordinateur : {taux_ordinateur}.
La chance de mes dés par tour : {chance} ({chance_mots}) ; celle de l'ordinateur : {chance_ordinateur}.
Mes imprécisions et erreurs, avec leur coût en équité :
{erreurs}
{position_titre} (GNU Backgammon, Position ID : {position_id}, Match ID : {match_id} ; ces identifiants la décrivent du point de vue du joueur qui a la main : {au_trait}).
Elle s'ouvre aussi à cette adresse : {lien}
{diagramme}
Score : {score}. Videau : {videau}.
Ces évaluations font foi : ne les recalcule pas et ne les contredis pas.
À partir de ce bilan, identifie trois thèmes que je devrais travailler en priorité, avec pour chacun un conseil concret.
Réponds en {langue}, simplement, en moins de 300 mots.
```
+36
View File
@@ -0,0 +1,36 @@
# Expliquer ce concept
Bouton « Demander à une IA » sur la fiche d'un terme du glossaire (« Les
mots du jeu »). La position d'exemple est celle de la partie en cours, ou la
position de départ s'il n'y en a pas. Texte sous licence CC BY-SA 4.0 (voir
[README.md](README.md)).
Repères propres à ce gabarit :
| Repère | Ce qu'il devient |
| --- | --- |
| `{concept}` | le terme, et son nom anglais s'il en a un |
| `{definition}` | la phrase « En bref » de sa fiche |
| `{position_titre}` | « une position de ma partie en cours » ou « la position de départ » |
| `{evaluation}` | les chances de gagner et l'équité du joueur au trait, avant de lancer les dés |
## Gabarit
```text
Tu es un coach de backgammon, bienveillant et précis. {joueur}
Explique-moi le concept {concept}.
Mon application le définit ainsi : {definition}
Pour l'illustrer, voici {position_titre} (GNU Backgammon, Position ID : {position_id}, Match ID : {match_id} ; ces identifiants la décrivent du point de vue du joueur qui a la main : {au_trait}).
Elle s'ouvre aussi à cette adresse : {lien}
{diagramme}
Score : {score}. Videau : {videau}.
Évaluation de GNU Backgammon ({niveau_eval}), pour le joueur qui a la main ({au_trait}), avant de lancer les dés : {evaluation}.
Ces évaluations font foi : ne les recalcule pas et ne les contredis pas.
Explique ce concept simplement, avec une analogie de la vie courante, puis dis s'il joue un rôle dans cette position et comment.
Réponds en {langue}, en moins de 250 mots.
```
+44
View File
@@ -0,0 +1,44 @@
# Pourquoi ce coup est meilleur
Bouton « Demander à une IA » sur un coup du joueur : feuille d'explication
du maître, carte « Le coup à revoir » du bilan, visualiseur de l'analyse.
Texte sous licence CC BY-SA 4.0 (voir [README.md](README.md)).
Repères propres à ce gabarit :
| Repère | Ce qu'il devient |
| --- | --- |
| `{des}` | le jet joué, « 3-1 » |
| `{coup_joue}` | votre coup, dans la notation de GNU Backgammon |
| `{appreciation}` | le mot du maître : « Bon coup », « Imprécision », « Erreur » ou « Grosse erreur » |
| `{rang}` | « le meilleur coup » ou « le 4e choix sur 15 coups possibles » |
| `{classement}` | le classement de l'analyse de votre coup : les trois meilleurs coups, et le vôtre s'il n'en est pas, avec leur équité et leur écart au meilleur, comme dans « Voir les chiffres du moteur » |
Le niveau du titre (`{niveau_eval}`) est celui auquel GNU Backgammon a
évalué le meilleur coup. C'est d'ordinaire le niveau de l'analyse (2 plis),
mais le moteur s'arrête plus tôt quand un seul coup passe ses filtres : à
l'ouverture 3-1 jouée 8/5 6/5, tout le classement est à 1 pli. Les coups que
ses filtres ont écartés gardent l'évaluation d'un niveau inférieur, et leur
ligne le dit (« évalué à 1 pli »). Les équités et l'écart de votre coup sont
ceux de l'analyse, que disent la feuille du maître et l'écran d'analyse.
## Gabarit
```text
Tu es un coach de backgammon, bienveillant et précis. {joueur}
Voici la position avant mon coup (GNU Backgammon, Position ID : {position_id}, Match ID : {match_id} ; ces identifiants la décrivent du point de vue du joueur qui a la main : {au_trait}).
Elle s'ouvre aussi à cette adresse : {lien}
{diagramme}
Score : {score}. Videau : {videau}. Dés : {des}.
J'ai joué {coup_joue} : {rang}, jugé « {appreciation} ».
Classement de GNU Backgammon ({niveau_eval}), équités du point de vue du joueur qui joue :
{classement}
Ces évaluations font foi : ne les recalcule pas et ne les contredis pas.
Explique-moi pourquoi le meilleur coup est supérieur au mien : quels concepts sont en jeu, et ce que je dois retenir pour la prochaine fois.
Réponds en {langue}, simplement, en moins de 200 mots.
```
+36
View File
@@ -0,0 +1,36 @@
# Créer des exercices
Prévu pour l'écran de progression (étape 1h) : le gabarit est écrit et
testé, sans bouton pour l'instant. Il rassemble les erreurs de vos
dernières parties analysées. Texte sous licence CC BY-SA 4.0 (voir
[README.md](README.md)).
Repères propres à ce gabarit :
| Repère | Ce qu'il devient |
| --- | --- |
| `{parties}` | le nombre de parties analysées |
| `{erreurs}` | vos erreurs les plus coûteuses sur ces parties, avec leur coût |
| `{position_titre}` | la plus coûteuse d'entre elles |
## Gabarit
```text
Tu es un coach de backgammon, bienveillant et précis. {joueur}
Voici mes {parties} dernières parties contre l'ordinateur, analysées par GNU Backgammon ({niveau_eval}).
Mes erreurs les plus coûteuses, avec leur coût en équité :
{erreurs}
{position_titre} (GNU Backgammon, Position ID : {position_id}, Match ID : {match_id} ; ces identifiants la décrivent du point de vue du joueur qui a la main : {au_trait}).
Elle s'ouvre aussi à cette adresse : {lien}
{diagramme}
Score : {score}. Videau : {videau}.
Ces évaluations font foi : ne les recalcule pas et ne les contredis pas.
Repère les thèmes qui reviennent dans ces erreurs, puis propose-moi cinq exercices ciblés : pour chacun, le thème, une position type décrite simplement, et ce que je dois y chercher.
Réponds en {langue}, en moins de 350 mots.
```
+40
View File
@@ -0,0 +1,40 @@
# Expliquer cette décision de videau
Bouton « Demander à une IA » sur une décision de videau du joueur (doubler,
lancer sans doubler, prendre, passer) : feuille d'explication du maître,
carte « Le coup à revoir » du bilan, visualiseur de l'analyse. Texte sous
licence CC BY-SA 4.0 (voir [README.md](README.md)).
Repères propres à ce gabarit :
| Repère | Ce qu'il devient |
| --- | --- |
| `{decision}` | la question posée : « doubler ou lancer les dés sans doubler » ou « prendre ou passer le double de l'ordinateur » |
| `{choix}` | votre décision, « passer » |
| `{choix_moteur}` | la décision que préfère GNU Backgammon |
| `{appreciation}` | le mot du maître : « Bonne décision », « Imprécision », « Erreur » ou « Grosse erreur » |
| `{qui_double}` | « moi » ou « l'ordinateur » : celui qui double ou non |
| `{equites}` | les équités sans double, double et prise, double et refus, comme dans « Voir les chiffres du moteur » |
| `{ecart}` | l'équité perdue par votre décision |
## Gabarit
```text
Tu es un coach de backgammon, bienveillant et précis. {joueur}
Voici la position au moment d'une décision de videau (GNU Backgammon, Position ID : {position_id}, Match ID : {match_id} ; ces identifiants la décrivent du point de vue du joueur qui a la main : {au_trait}).
Elle s'ouvre aussi à cette adresse : {lien}
{diagramme}
Score : {score}. Videau : {videau}.
Il fallait choisir : {decision}. J'ai choisi de {choix}, jugé « {appreciation} » ; GNU Backgammon aurait choisi de {choix_moteur}.
Équités calculées par GNU Backgammon ({niveau_eval}), du point de vue de celui qui double ou non ({qui_double}), pour un videau de 1 :
{equites}
Écart de ma décision : {ecart}.
Ces évaluations font foi : ne les recalcule pas et ne les contredis pas.
Explique-moi cette décision : pourquoi doubler ou non, prendre ou passer, quels repères de la position comptent, et ce que je dois retenir.
Réponds en {langue}, simplement, en moins de 200 mots.
```
+2
View File
@@ -58,6 +58,8 @@ Règles d'écriture :
| [jouer-une-partie.feature](jouer-une-partie.feature) | Jouer une partie contre l'ordinateur | Étape 0d |
| [jouer-un-match.feature](jouer-un-match.feature) | Choisir sa partie (libre ou match, niveau) et jouer un match | Étape 1c |
| [comprendre-mes-coups.feature](comprendre-mes-coups.feature) | Comprendre ses coups avec le conseil du maître | Étape 1d |
| [revoir-ma-partie.feature](revoir-ma-partie.feature) | Revoir sa partie : bilan, coup à revoir, analyse, rejouer d'ici | Étape 1e |
| [demander-a-une-ia.feature](demander-a-une-ia.feature) | Demander à une IA d'expliquer un coup, une partie ou un mot | Étape 1f |
| [mes-parties.feature](mes-parties.feature) | Retrouver mes parties, leurs branches, les exporter en SGF | Étape 1b |
| [partager-une-position.feature](partager-une-position.feature) | Ouvrir et partager le lien d'une position | Étape 0e.4 |
| [regler-l-application.feature](regler-l-application.feature) | Régler l'application (menu), la mettre à jour | Étape 0e |
+45
View File
@@ -0,0 +1,45 @@
# language: fr
Fonctionnalité: Demander à une IA d'expliquer un coup, une partie ou un mot
Le maître dit quel coup il aurait joué ; pour comprendre pourquoi, vous
pouvez demander à une IA de votre choix. Touchez « Demander à une IA »
dans l'explication du maître, sur le bilan, dans l'analyse ou sur la fiche
d'un mot du jeu : l'application prépare une question complète, avec la
position, son lien et les chiffres de GNU Backgammon. Relisez-la, copiez-la,
puis collez-la dans l'IA. L'application n'appelle aucune IA et n'envoie
rien : le moteur décide, l'IA explique, et la question lui demande de ne
pas contredire les chiffres du moteur.
Scénario: Comment demander à une IA d'expliquer mon erreur ?
Touchez « Demander à une IA » dans l'explication du maître : la question
donne la position avant votre coup, dessinée en texte, ses identifiants
de GNU Backgammon et son lien, puis les trois meilleurs coups du maître et
le vôtre, avec les mêmes chiffres que l'explication du maître.
Étant donné que vous avez joué 24/23 13/10 avec un 3-1 d'ouverture
Quand vous demandez à une IA d'expliquer ce coup
Alors la question donne la position, avec son Position ID, son Match ID et son lien
Et elle donne les trois meilleurs coups du maître et le vôtre, avec les chiffres de l'explication
Et elle demande à l'IA de ne pas contredire ces chiffres, et de répondre en français
Scénario: Comment demander à une IA le bilan de ma partie ?
Sur le bilan, « Demander à une IA » prépare une question sur toute la
partie : le résultat, vos décisions par appréciation, votre niveau, la
chance des dés, vos erreurs et leur coût, et la position du coup à
revoir. L'IA vous propose trois thèmes à travailler.
Étant donné une partie finie où vous avez joué 6/5 5/off avec 6-1, puis passé le double de l'ordinateur
Quand vous demandez à une IA le bilan de votre partie
Alors la question donne vos décisions, votre niveau et la chance des dés, comme le bilan
Et elle cite votre coup 6/off, le coup du maître 6/off 1/off et leur écart
Et elle donne la position du coup à revoir
Scénario: Puis-je demander à une IA d'expliquer un mot du jeu ?
Oui : sur la fiche d'un mot du glossaire, la question reprend sa
définition et l'illustre par la position de votre partie en cours, ou par
la position de départ, avec l'évaluation de GNU Backgammon.
Étant donné qu'aucune partie n'est en cours
Quand vous demandez à une IA d'expliquer le mot « Videau »
Alors la question reprend la définition de sa fiche
Et elle l'illustre par la position de départ, avec les chances de gagner selon GNU Backgammon
+3 -1
View File
@@ -4,7 +4,9 @@ Fonctionnalité: Choisir sa partie et jouer un match
L'écran « Nouvelle partie » s'ouvre depuis le menu, l'accueil et, à la
fin d'une partie, par « Changer les réglages ». Vous y choisissez une partie libre ou un match en 3, 5, 7
ou 11 points, le niveau de l'ordinateur, et si le maître commente vos
coups. Vos choix sont gardés pour la prochaine fois.
coups. Vos choix sont gardés pour la prochaine fois. « Commencer la
partie » (ou « Commencer le match ») lance aussitôt la partie, sur le
plateau, même juste après le bilan d'une partie finie.
Scénario: Comment choisir le niveau de l'ordinateur ?
Six niveaux, du Débutant, qui laisse passer des occasions, au Champion,
+18
View File
@@ -142,6 +142,24 @@ Fonctionnalité: Jouer une partie contre l'ordinateur
Alors la partie s'arrête
Et vous perdez la partie à sa valeur d'avant le double
@position:BQAACAIAAAAAAA
Scénario: Sortir ses pions dans l'ordre de son choix
Une fois tous vos pions dans votre jan intérieur (flèches 1 à 6), vous les
sortez dans l'ordre que vous voulez. Avec 6-1, un pion sur la flèche 6
et un sur la flèche 1 : sortez l'un puis l'autre, ou l'inverse. Si vous
ne sortez que le pion de la 6, « Jouer ce coup » apparaît déjà, car ce
pion a pu utiliser vos deux dés (6/5, puis 5/off). Touchez l'autre pion
pour le sortir aussi.
Étant donné que vous avez un pion sur la flèche 6 et un sur la flèche 1, avec le jet 6-1
Quand vous jouez 6/off
Alors vous pouvez valider ou jouer encore 1/off
Quand vous jouez 1/off
Alors vos deux pions sont sortis
Étant donné que vous avez un pion sur la flèche 6 et un sur la flèche 1, avec le jet 6-1
Quand vous jouez 1/off 6/off
Alors vos deux pions sont sortis
Scénario: Comment se termine une partie ?
La partie s'arrête dès qu'un joueur a sorti tous ses pions. Le panneau de
fin dit qui gagne, et combien de points : la valeur du videau, doublée
+62
View File
@@ -0,0 +1,62 @@
# language: fr
Fonctionnalité: Revoir ma partie avec le bilan et l'analyse
À la fin de chaque partie, le maître fait le bilan : le résultat, vos
décisions par appréciation (bons coups, imprécisions, erreurs), votre jeu
traduit en niveau, la chance de vos dés, et le coup à revoir, celui qui
vous a coûté le plus. « Voir l'analyse » montre la courbe de vos chances de
gagner, coup après coup : parcourez-la du doigt pour revoir chaque coup sur
le plateau, le vôtre et celui du maître. Tout vient de GNU Backgammon,
comme le conseil du maître ; ce qui manque est calculé en arrière-plan,
même pour une partie jouée avant que le conseil existe.
Scénario: Que dit le bilan d'une partie ?
Le bilan compte vos décisions par appréciation, traduit votre jeu en
niveau, et dit en une phrase ce qui a fait la différence : votre jeu,
celui de l'ordinateur, ou les dés. Ici, après 6/5 5/off, l'ordinateur
est sûr de sortir ses deux derniers pions : il double, et vous passez.
Étant donné qu'il vous reste deux pions, sur vos points 6 et 1, et à l'ordinateur deux pions sur ses points 1 et 2
Et que vous avez 6-1 à jouer
Quand vous choisissez le coup 6/5 5/off
Et que l'ordinateur, sûr de gagner, double et que vous passez
Alors la partie est finie, gagnée par l'ordinateur
Et le bilan compte une grosse erreur
Et sa phrase dit ce qui a fait la différence, et comment étaient vos dés
Scénario: Quel est le coup à revoir ?
C'est votre décision qui a perdu le plus d'équité, d'après le maître. Le
bilan la montre sur le plateau, avec le coup que le maître aurait joué ;
« Revoir ce coup » ouvre l'analyse sur ce coup.
Étant donné qu'il vous reste deux pions, sur vos points 6 et 1, et à l'ordinateur deux pions sur ses points 1 et 2
Et que vous avez 6-1 à jouer
Quand vous choisissez le coup 6/5 5/off
Et que l'ordinateur, sûr de gagner, double et que vous passez
Alors le coup à revoir est votre coup 6/off, le premier de la partie
Et le maître y aurait joué 6/off 1/off
Et la courbe de vos chances de gagner finit à 0 %
Scénario: Comment rejouer un coup autrement ?
Dans l'analyse, « Rejouer d'ici » vous remet juste avant le coup, avec le
même jet. Jouez autre chose : une nouvelle branche commence là, et la
partie d'origine reste intacte dans « Mes parties ».
Étant donné qu'il vous reste deux pions, sur vos points 6 et 1, et à l'ordinateur deux pions sur ses points 1 et 2
Et que vous avez 6-1 à jouer
Quand vous choisissez le coup 6/5 5/off
Et que l'ordinateur, sûr de gagner, double et que vous passez
Et que vous rejouez d'ici le coup à revoir
Alors vous avez de nouveau 6-1 à jouer
Quand vous choisissez cette fois le coup 1/off 6/off
Alors la partie est finie, gagnée par vous
Et la partie a deux branches, dont la partie d'origine, intacte
Scénario: Puis-je voir le bilan d'une partie plus ancienne ?
Oui : une partie enregistrée sans analyse, par exemple jouée avant le
conseil du maître, est analysée quand vous ouvrez son bilan.
Étant donné une partie finie enregistrée sans aucune analyse
Quand vous ouvrez son bilan
Alors le maître l'analyse d'abord en arrière-plan
Et le bilan nomme ensuite le coup à revoir
+2 -1
View File
@@ -51,7 +51,8 @@ Le texte de la fin du tutoriel.
position (par défaut, vous) ;
- `jet` et `coup` : sur un écran d'explication, le coup illustré, qui se
joue tout seul (notation de gnubg) ;
- `chemin: oui` : le sens du jeu, dessiné en pointillés sur le plateau ;
- `chemin: oui` : le sens du jeu, deux flèches circulaires sur le plateau
(claire pour vos pions, sombre pour ceux de l'ordinateur) ;
- `attendu` (une ligne par coup accepté) : sur un écran « à vous », les
coups justes, en notation de gnubg, tels que le moteur les écrit ;
- `réponse` : `prendre` ou `passer`, pour un écran « à vous » où
+11 -9
View File
@@ -1,13 +1,15 @@
# Les règles du backgammon
Tutoriel d'Ustagammon, en huit étapes. Texte sous licence CC BY-SA 4.0,
validé par Pierre le 9 novembre 2026. Format : voir README.md.
validé par Pierre le 9 novembre 2026 ; pions blancs et noirs, flèches
circulaires et jans repris de la charte le 11 novembre 2026
(docs/identite/charte/accueil-tutoriel-aide.md). Format : voir README.md.
## 1. Le but du jeu
- position: 4HPwATDgc/ABMA
Vous avez quinze [pions](pion.md) ivoire, l'ordinateur quinze pions noyer. Chacun fait faire le tour du [plateau](plateau.md) à ses pions, puis les [sort](sortie.md).
Vous avez quinze [pions](pion.md) blancs, l'ordinateur quinze pions noirs. Chacun fait faire le tour du [plateau](plateau.md) à ses pions, puis les [sort](sortie.md).
Le premier qui a sorti tous les siens gagne la [partie](partie.md).
@@ -16,9 +18,9 @@ Le premier qui a sorti tous les siens gagne la [partie](partie.md).
- position: 4HPwATDgc/ABMA
- chemin: oui
Vos pions ivoire font le tour du plateau dans le sens des pointillés : ils partent d'en haut à droite, passent à gauche, puis reviennent en bas jusqu'aux **six dernières flèches**, en bas à droite. C'est là que vous les rassemblerez avant de les sortir.
Vos pions suivent la **flèche claire** : ils partent d'en haut à droite, passent à gauche, puis reviennent en bas jusqu'à votre [jan intérieur](jan-interieur.md), les flèches 1 à 6. C'est là que vous les rassemblez avant de les sortir.
Les pions noyer de l'ordinateur font le même chemin, en sens inverse.
Les pions de l'ordinateur suivent la **flèche sombre**, en sens inverse, jusqu'à son jan intérieur, les flèches 19 à 24.
## 3. Les dés et les doubles
@@ -60,10 +62,10 @@ Une flèche où l'adversaire a deux pions ou plus est fermée : vous ne pouvez p
- attendu: 24/23 13/7*
- attendu: 24/18 8/7*
- attendu: 8/7* 8/2
- juste: Touché : le pion noyer part sur la barre, il devra refaire tout le chemin.
- juste: Touché : le pion noir part sur la barre, il devra refaire tout le chemin.
- refus: Ce coup ne frappe pas le pion seul de la flèche 7. Un pion qui s'y pose le frappe : celui de la flèche 13 avec le 6, ou celui de la flèche 8 avec le 1.
Vous avez 6 et 1. Le pion noyer de la flèche 7 est seul : frappez-le.
Vous avez 6 et 1. Le pion noir de la flèche 7 est seul : frappez-le.
## 5. Rentrer depuis la barre
@@ -71,7 +73,7 @@ Vous avez 6 et 1. Le pion noyer de la flèche 7 est seul : frappez-le.
- jet: 4-3
- coup: bar/22 13/9
Votre pion frappé attend sur la barre, au milieu. Avant de jouer quoi que ce soit d'autre, il doit rentrer dans le [camp](camp.md) adverse, en haut à droite.
Votre pion frappé attend sur la barre, au milieu. Avant de jouer quoi que ce soit d'autre, il doit rentrer dans le jan intérieur de l'ordinateur, en haut à droite.
Chaque dé indique une flèche d'entrée : avec 3 et 4, la 22 ou la 21. Si les deux flèches sont fermées, votre tour passe.
@@ -81,7 +83,7 @@ Chaque dé indique une flèche d'entrée : avec 3 et 4, la 22 ou la 21. Si les d
- jet: 5-2
- coup: 5/off 2/off
Quand vos quinze pions sont dans les six dernières flèches, vous pouvez commencer à les sortir : un 6 sort un pion de la flèche 6, un 1 un pion de la flèche 1.
Quand vos quinze pions sont dans votre jan intérieur (flèches 1 à 6), vous pouvez commencer à les sortir : un 6 sort un pion de la flèche 6, un 1 un pion de la flèche 1.
Touchez le pion, puis la sortie à droite.
@@ -101,7 +103,7 @@ Vous avez 6 et 3 : sortez deux pions.
- jet: 2-1
- coup: 2/off 1/off
Une partie gagnée vaut 1 point. Si l'adversaire n'a sorti aucun pion, c'est un [gammon](gammon.md) : 2 points ; s'il lui reste en plus un pion sur la barre ou dans votre camp, c'est un [backgammon](backgammon.md) : 3 points. En partie libre, gammon et backgammon ne comptent que si le videau a été doublé : c'est la [règle de Jacoby](regle-de-jacoby.md).
Une partie gagnée vaut 1 point. Si l'adversaire n'a sorti aucun pion, c'est un [gammon](gammon.md) : 2 points ; s'il lui reste en plus un pion sur la barre ou dans votre jan intérieur, c'est un [backgammon](backgammon.md) : 3 points. En partie libre, gammon et backgammon ne comptent que si le videau a été doublé : c'est la [règle de Jacoby](regle-de-jacoby.md).
## 8. Le videau
+10 -2
View File
@@ -43,7 +43,8 @@
* analyse du coup joué (POSITION_JOUÉE :
* position après le coup, vue du joueur
* qui l'a joué, comme position_id dans
* moves et legal)
* moves et legal), avec le classement
* de l'analyse (dix coups au plus)
* analysecube POSITION_ID MATCH_ID DÉCISION
* analyse d'une décision de videau :
* no_double ou double (joueur au trait),
@@ -684,7 +685,7 @@ run_analyse_move_command(const options *opt)
const char *played_id = opt->args[3];
engine_move_analysis a;
engine_status status;
int die1, die2;
int die1, die2, i;
if (opt->arg_count != 4)
return usage_error("arguments attendus : POSITION_ID MATCH_ID DÉS POSITION_JOUÉE");
@@ -705,6 +706,13 @@ run_analyse_move_command(const options *opt)
printf(", \"best\": ");
print_move(&a.best, 1);
}
printf(", \"ranking\": [");
for (i = 0; i < a.ranking_count; i++) {
if (i > 0)
printf(", ");
print_move(&a.ranking[i], 1);
}
printf("]");
printf(", \"equity_loss\": " NUMBER ", \"skill\": \"%s\"}\n", a.equity_loss,
skill_names[a.skill]);
return EXIT_SUCCESS;
+31 -9
View File
@@ -512,6 +512,8 @@ engine_level_best_moves(const char *position_id, const char *match_id, int die1,
/* ------------------------------------------------- Analyse d'un coup joué */
static float luck_analysis(const char *position_id, position *pos, int die1, int die2);
engine_status
engine_analyse_move(const char *position_id, const char *match_id, int die1, int die2,
const char *played_position_id, int ply, engine_move_analysis *analysis)
@@ -546,6 +548,17 @@ engine_analyse_move(const char *position_id, const char *match_id, int die1, int
* premier.
*/
memset(analysis, 0, sizeof *analysis);
/*
* gnubg analyse la chance du jet juste avant le coup (AnalyzeMove,
* l. 679-682), à 0 pli sans élagage, et garde ces évaluations dans son
* cache, qui ne distingue pas une évaluation à 0 pli avec ou sans
* réseaux d'élagage : le tri à 0 pli de FindnSaveBestMoves les reprend
* ensuite, ce qui change l'équité des coups restés à 0 pli, et parfois
* ceux que les filtres retiennent. Faire de même, sans garder le
* résultat, donne le classement de gnubg de bureau.
*/
if (luck_analysis(position_id, &pos, die1, die2) == ERR_VAL)
return ENGINE_ERROR_INTERNAL;
if (FindnSaveBestMoves(&list, die1, die2, (ConstTanBoard) pos.board, &played_key, TRUE,
DOUBTFUL_THRESHOLD, &pos.cube, &context,
aaamfMoveFilterSettings[0]) < 0)
@@ -565,6 +578,10 @@ engine_analyse_move(const char *position_id, const char *match_id, int die1, int
status = ENGINE_OK;
break;
}
/* Le classement : le début de la même liste, dans l'ordre de gnubg. */
for (i = 0; i < list.cMoves && i < ENGINE_ANALYSIS_RANKING; i++)
fill_move(&analysis->ranking[i], &list.amMoves[i], &pos, 1);
analysis->ranking_count = (int) i;
g_free(list.amMoves);
return status;
}
@@ -1005,13 +1022,25 @@ luck_first(ConstTanBoard board, int i0, int j0, cubeinfo *cube)
return equities[i0][j0] - mean / 30.0f;
}
/* LuckAnalysis (analysis.c l. 252-268) : dés rangés du plus fort au plus
* faible ; LuckFirst à la position de départ hors doubles. */
static float
luck_analysis(const char *position_id, position *pos, int die1, int die2)
{
int high = (die1 > die2 ? die1 : die2) - 1;
int low = (die1 > die2 ? die2 : die1) - 1;
if (strcmp(position_id, START_POSITION_ID) == 0 && high != low)
return luck_first((ConstTanBoard) pos->board, high, low, &pos->cube);
return luck_normal((ConstTanBoard) pos->board, high, low, &pos->cube);
}
engine_status
engine_luck_of(const char *position_id, const char *match_id, int die1, int die2,
engine_luck *luck)
{
position pos;
engine_status status;
int high, low;
float value;
status = decode_position(position_id, match_id, &pos);
@@ -1021,14 +1050,7 @@ engine_luck_of(const char *position_id, const char *match_id, int die1, int die2
return status;
start_evaluation();
/* LuckAnalysis (analysis.c l. 252-268) : dés rangés du plus fort au plus
* faible ; LuckFirst à la position de départ hors doubles. */
high = (die1 > die2 ? die1 : die2) - 1;
low = (die1 > die2 ? die2 : die1) - 1;
if (strcmp(position_id, START_POSITION_ID) == 0 && high != low)
value = luck_first((ConstTanBoard) pos.board, high, low, &pos.cube);
else
value = luck_normal((ConstTanBoard) pos.board, high, low, &pos.cube);
value = luck_analysis(position_id, &pos, die1, die2);
if (value == ERR_VAL)
return ENGINE_ERROR_INTERNAL;
luck->luck = value;
+21 -1
View File
@@ -207,6 +207,10 @@ typedef struct {
* (double_take <= double_pass) */
} engine_cube;
/* Coups gardés dans le classement d'une analyse : les dix premiers, comme
* les positions de référence (tests/reference/README.md). */
#define ENGINE_ANALYSIS_RANKING 10
/* Analyse d'un coup joué, comme l'analyse de partie de gnubg. */
typedef struct {
int move_count; /* nombre de coups légaux (0 : aucun coup
@@ -218,6 +222,14 @@ typedef struct {
float equity_loss; /* équité du coup joué moins celle du meilleur :
* 0 ou négative */
engine_skill skill; /* appréciation de gnubg pour cette perte */
/* Le classement de l'analyse, du meilleur au moins bon : les premiers
* coups de la liste que gnubg garde pour l'analyse de partie (ce que
* montre son panneau d'analyse), chacun au niveau où gnubg l'a
* évalué. Le meilleur coup et le coup joué y ont les mêmes évaluations
* que best et played ; le coup joué n'y figure que s'il est parmi les
* premiers. */
engine_move ranking[ENGINE_ANALYSIS_RANKING];
int ranking_count;
} engine_move_analysis;
/* Analyse d'une décision de videau, comme l'analyse de partie de gnubg. */
@@ -452,7 +464,15 @@ engine_luck_rating engine_luck_rating_of(float luck);
* Analyse le coup joué par le joueur au trait avec le jet die1, die2, au
* niveau ply, comme l'analyse de partie de gnubg (AnalyzeMove dans
* analysis.c : FindnSaveBestMoves avec le coup joué, seuil « douteux »,
* filtre « Normal », sans RefreshMoveList). played_position_id est la
* filtre « Normal », sans RefreshMoveList), classement compris.
*
* Niveaux : gnubg n'évalue au niveau ply que les coups retenus par ses
* filtres ; les autres gardent l'évaluation d'un niveau inférieur (champ
* ply de chaque coup, même convention que gnubg de bureau : 0 = statique).
* Si un seul coup passe le filtre du niveau ply - 1, gnubg s'arrête là, et
* tout le classement reste à ce niveau, sauf quand le coup joué est une
* erreur (écart au meilleur supérieur au seuil « douteux ») : le meilleur
* coup et le coup joué sont alors réévalués au niveau ply. played_position_id est la
* position après le coup, vue du joueur qui vient de le jouer (champ
* position_id d'engine_move). ENGINE_ERROR_MOVE si ce n'est pas un coup
* légal ; si aucun coup n'est possible, move_count vaut 0.
+45 -5
View File
@@ -9,10 +9,19 @@
# captures dans build/browser-shots/match/.
#
# Le conseil du maître (tests/browser/maitre.mjs), captures dans
# build/browser-shots/maitre/.
# build/browser-shots/maitre/. Le bilan de fin de partie et l'écran
# d'analyse (tests/browser/bilan.mjs), captures dans
# build/browser-shots/bilan/. « Demander à une IA » (tests/browser/prompts.mjs),
# captures dans build/browser-shots/prompts/. « Nouvelle partie » après une
# partie finie et son bilan, par chaque entrée
# (tests/browser/nouvelle-partie.mjs), captures dans
# build/browser-shots/nouvelle-partie/. Les retours des premiers joueurs
# (tests/browser/retours-joueurs.mjs : pions sur la barre, numéros sur le
# cadre, flèches du tutoriel, en thème clair et sombre), captures dans
# build/browser-shots/retours-joueurs/.
#
# BROWSERS=chromium et SCRIPTS=accueil (ou play, match, maitre) restreignent le
# test.
# BROWSERS=chromium et SCRIPTS=accueil (ou play, match, maitre, bilan,
# prompts, nouvelle-partie, retours-joueurs) restreignent le test.
#
# Outils : l'image de Playwright (navigateurs) et le paquet playwright,
# installé une fois par npm dans build/browser-tools/ (réseau nécessaire la
@@ -25,7 +34,7 @@ cd "$(dirname "$0")/.."
image="${PLAYWRIGHT_IMAGE:?lancer via make test-browser}"
browsers="${BROWSERS:-chromium firefox}"
# Les scripts à lancer (tests/browser/<nom>.mjs), tous par défaut.
scripts="${SCRIPTS:-play accueil match maitre}"
scripts="${SCRIPTS:-play accueil match maitre bilan prompts nouvelle-partie retours-joueurs}"
unset MAKEFLAGS MFLAGS MAKELEVEL
make -s package >/dev/null
@@ -63,7 +72,8 @@ update_port="$(docker port "$update_container" 80/tcp | head -n1 | sed 's/.*://'
rm -rf build/browser-shots
mkdir -p build/browser-shots
cp tests/browser/play.mjs tests/browser/accueil.mjs tests/browser/match.mjs tests/browser/recette.mjs \
tests/browser/maitre.mjs "$tools/"
tests/browser/maitre.mjs tests/browser/bilan.mjs tests/browser/prompts.mjs tests/browser/nouvelle-partie.mjs \
tests/browser/retours-joueurs.mjs "$tools/"
status=0
for browser in $browsers; do
# Réseau de l'hôte : le site est sur 127.0.0.1. Le service worker
@@ -96,5 +106,35 @@ for browser in $browsers; do
-v "$PWD/$tools:/tools" -v "$PWD/build/browser-shots:/shots" -w /tools "$image" \
node maitre.mjs "http://localhost:$port/" "$browser" /shots || status=1
fi
if [[ " $scripts " == *" bilan "* ]]; then
# Bilan de fin de partie et écran d'analyse ; captures de la recette
# dans build/browser-shots/bilan/.
docker run --rm --init --ipc=host --network host --user "$(id -u):$(id -g)" -e HOME=/tmp \
-v "$PWD/$tools:/tools" -v "$PWD/build/browser-shots:/shots" -w /tools "$image" \
node bilan.mjs "http://localhost:$port/" "$browser" /shots || status=1
fi
if [[ " $scripts " == *" prompts "* ]]; then
# « Demander à une IA » : boutons, feuille du prompt, copie (relue
# dans Chromium) ; captures dans build/browser-shots/prompts/.
docker run --rm --init --ipc=host --network host --user "$(id -u):$(id -g)" -e HOME=/tmp \
-v "$PWD/$tools:/tools" -v "$PWD/build/browser-shots:/shots" -w /tools "$image" \
node prompts.mjs "http://localhost:$port/" "$browser" /shots || status=1
fi
if [[ " $scripts " == *" nouvelle-partie "* ]]; then
# « Nouvelle partie » après une partie finie et son bilan : la
# nouvelle partie tout de suite ; captures dans
# build/browser-shots/nouvelle-partie/.
docker run --rm --init --ipc=host --network host --user "$(id -u):$(id -g)" -e HOME=/tmp \
-v "$PWD/$tools:/tools" -v "$PWD/build/browser-shots:/shots" -w /tools "$image" \
node nouvelle-partie.mjs "http://localhost:$port/" "$browser" /shots || status=1
fi
if [[ " $scripts " == *" retours-joueurs "* ]]; then
# Retours des premiers joueurs : pions sur la barre, numéros sur le
# cadre, flèches du tutoriel ; captures dans
# build/browser-shots/retours-joueurs/.
docker run --rm --init --ipc=host --network host --user "$(id -u):$(id -g)" -e HOME=/tmp \
-v "$PWD/$tools:/tools" -v "$PWD/build/browser-shots:/shots" -w /tools "$image" \
node retours-joueurs.mjs "http://localhost:$port/" "$browser" /shots || status=1
fi
done
exit "$status"
+25 -8
View File
@@ -16,7 +16,7 @@
import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
import { chromium, firefox } from "playwright";
import { hiddenUnderActionBar } from "./recette.mjs";
import { hiddenUnderActionBar, tutorialWidthProblems, tutorialWidths } from "./recette.mjs";
const [base, browserName, shots, updateBase, updateDir] = process.argv.slice(2);
const browserType = { chromium, firefox }[browserName];
@@ -171,6 +171,7 @@ async function checkTutorialView(page, name) {
return b.scrollHeight - b.clientHeight;
})(),
height: innerHeight,
width: innerWidth,
buttons,
};
});
@@ -189,8 +190,13 @@ async function checkTutorialView(page, name) {
}
tutorialViews++;
tutorialMinNumber = Math.min(tutorialMinNumber, view.minNumber);
// Largeurs du plateau et du texte, comparées d'une étape à l'autre à la
// fin du tutoriel (tutorialWidthProblems).
const widths = await tutorialWidths(page);
tutorialWidthViews.push({ name, size: `${view.width}x${view.height}`, ...widths });
}
let tutorialViews = 0;
const tutorialWidthViews = [];
let tutorialBodyScroll = { px: 0, where: "" };
let tutorialMinNumber = Infinity;
@@ -268,17 +274,16 @@ async function playTouches(page, touches) {
await tutorialReady(page, hash);
}
if (step === 2) {
check(await page.locator("#tutorial-board .tutorial-path").count() === 1,
"étape 2 : pas de chemin en pointillés");
// Sous les pions et sous les numéros des flèches.
check(await page.locator("#tutorial-board .tutorial-path .direction-line").count() === 2,
"étape 2 : pas les deux flèches du sens du jeu");
// Sous les pions (détail : retours-joueurs.mjs).
const order = await page.evaluate(() => {
const children = [...document.getElementById("tutorial-board").children];
const at = (selector) => children.findIndex((c) => c.matches(selector));
const numbers = children.filter((c) => c.matches(".point-number")).map((c) => children.indexOf(c));
return { path: at(".tutorial-path"), pieces: at("g.pieces"), firstNumber: Math.min(...numbers) };
return { path: at(".tutorial-path"), pieces: at("g.pieces") };
});
check(order.path >= 0 && order.path < order.pieces && order.path < order.firstNumber,
`étape 2 : le chemin passe au-dessus des pions ou des numéros ${JSON.stringify(order)}`);
check(order.path >= 0 && order.path < order.pieces,
`étape 2 : les flèches passent au-dessus des pions ${JSON.stringify(order)}`);
}
await tutorialCapture(page, `tutoriel-${step}`);
screens++;
@@ -331,6 +336,18 @@ async function playTouches(page, touches) {
await until(page, "fin", () => location.hash === "#/tutoriel/fin");
await page.click("#tutorial-next");
await until(page, "première partie", () => location.hash === "#/" && window.__shown("game"));
if (full) {
// Les mesures, écran par écran, à côté des captures.
writeFileSync(`${dir}/tutoriel-largeurs.txt`, tutorialWidthViews.map((v) =>
`${v.size}\t${v.name}\tplateau ${v.board.toFixed(1)}\ttexte ${v.text.toFixed(1)}\tpage ${v.page}`)
.join("\n") + "\n");
const widthProblems = tutorialWidthProblems(tutorialWidthViews);
check(widthProblems.length === 0, `largeurs du tutoriel :\n ${widthProblems.join("\n ")}`);
const sizes = [...new Set(tutorialWidthViews.map((v) => v.size))];
log(`tutoriel : plateau de même largeur à chaque étape (${sizes.map((s) =>
`${s} : ${tutorialWidthViews.find((v) => v.size === s).board.toFixed(1)} px`).join(", ")}), ` +
"aucune page plus large que l'écran");
}
log(`tutoriel : ${screens} écrans, gestes refusés puis justes sur les 4 écrans « à vous », fin` +
(full ? ` ; recette sur ${tutorialViews} vues, numéros de ${tutorialMinNumber.toFixed(1)} px au moins, ` +
`texte défilant au plus de ${tutorialBodyScroll.px} px${tutorialBodyScroll.px > 0 ? ` (${tutorialBodyScroll.where})` : ""}` : ""));
+491
View File
@@ -0,0 +1,491 @@
// bilan.mjs -- le bilan de fin de partie et l'écran d'analyse (étape 1e)
// joués par l'interface, dans un vrai navigateur sans écran (Playwright),
// sur le site servi par l'image de production (charte,
// ecrans-etape-1.md, « 1e. Bilan et analyse »).
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// Usage : node bilan.mjs <adresse du site> <chromium|firefox> <dossier des captures>
// Lancé par tests/browser.sh. Une fin de course courte, partie depuis un
// lien de position avec des dés imposés : le joueur a 6-1 et deux pions,
// sur 6 et 1 ; 6/off 1/off gagne, 6/5/off perd (l'ordinateur sortira ses
// deux derniers pions au coup suivant : il double, et le joueur passe). Le
// joueur joue 6/5/off. Vérifie que le
// bilan remplace le panneau de fin de partie et nomme ce coup comme le coup
// à revoir, que l'analyse s'ouvre par son adresse (courbe, point touché,
// liste filtrée, visualiseur), que « Rejouer d'ici » crée une branche, la
// règle de la recette (rien d'interactif sous une barre d'action), et
// l'absence d'erreur et de violation de la politique de sécurité. Captures
// (Chromium) dans <dossier des captures>/bilan/, en 412×915, 915×412 et
// 844×320.
import { mkdirSync } from "node:fs";
import { chromium, firefox } from "playwright";
import { hiddenUnderActionBar, tallButtons } from "./recette.mjs";
const [base, browserName, shots] = process.argv.slice(2);
const browserType = { chromium, firefox }[browserName];
if (!base || !browserType || !shots) {
console.error("usage : node bilan.mjs <adresse> <chromium|firefox> <dossier des captures>");
process.exit(2);
}
const full = browserName === "chromium";
const dir = `${shots}/bilan`;
mkdirSync(dir, { recursive: true });
const PORTRAIT = { width: 412, height: 915 };
const LANDSCAPE = { width: 915, height: 412 };
const SMALL_LANDSCAPE = { width: 844, height: 320 };
const SIZES = [PORTRAIT, LANDSCAPE, SMALL_LANDSCAPE];
// Le joueur au trait : un pion sur 6, un sur 1 ; l'ordinateur : un sur 1,
// un sur 2 (positions de gnubg, chacun vu de lui-même).
const BEAROFF = "BQAACAIAAAAAAA";
const problems = [];
const log = (text) => console.log(`[${browserName}] ${text}`);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
let captures = 0;
function check(condition, message) {
if (!condition) {
throw new Error(message);
}
}
const browser = await browserType.launch();
const context = await browser.newContext({
viewport: PORTRAIT,
deviceScaleFactor: 1,
locale: "fr-FR",
// Sans animation : les captures montrent les coups posés, avec leurs
// traces.
reducedMotion: "reduce",
});
await context.addInitScript(() => {
// Les dés imposés d'abord (un dé par valeur), puis une graine fixe.
window.__dice = [];
let state = 5;
Math.random = () => {
const die = window.__dice.shift();
if (die !== undefined) {
return (die - 0.5) / 6;
}
state = (state * 1103515245 + 12345) % 2147483648;
return state / 2147483648;
};
window.__csp = [];
document.addEventListener("securitypolicyviolation", (e) =>
window.__csp.push(`${e.effectiveDirective} ${e.blockedURI}`),
);
});
const page = await context.newPage();
page.on("pageerror", (error) => problems.push(`erreur de la page : ${error.message}`));
page.on("console", (message) => {
if (message.type() === "error") {
problems.push(`console : ${message.text()}`);
}
});
/** Attend une condition dans la page (sans page.waitForFunction, qui passe
* par eval, interdit par la politique de sécurité du site). */
async function until(what, fn, arg, ms = 120_000) {
for (let waited = 0; waited < ms; waited += 100) {
if (await page.evaluate(fn, arg)) {
return;
}
await sleep(100);
}
await page.screenshot({ path: `${dir}/${browserName}-bloque.png` }).catch(() => {});
throw new Error(`attente trop longue : ${what}`);
}
const idle = () => until("écran libre", () => !document.body.classList.contains("busy"));
/** Une capture de la recette dans les trois tailles (Chromium seulement),
* après la règle commune : rien d'interactif sous une barre d'action. */
async function capture(name) {
if (!full) {
return;
}
await until("bandeau parti", () => document.getElementById("banner").hidden, null, 15_000);
for (const size of SIZES) {
await page.setViewportSize(size);
await sleep(300);
const hidden = await hiddenUnderActionBar(page);
check(
hidden.length === 0,
`${name} ${size.width}x${size.height} : caché sous la barre d'action : ${hidden.join(", ")}`,
);
const tall = await tallButtons(page);
check(tall.length === 0, `${name} ${size.width}x${size.height} : boutons étirés : ${tall.join(", ")}`);
await page.screenshot({ path: `${dir}/${name}-${size.width}x${size.height}.png` });
captures++;
}
await page.setViewportSize(PORTRAIT);
await sleep(300);
}
/** Une nouvelle partie à partir d'une position, joueur au trait. */
async function startFrom(position) {
await page.goto(`${base}#/position/${encodeURIComponent(position)}`);
await until("position lue", () => {
const play = document.getElementById("position-play");
return !play.hidden && !play.disabled;
});
await page.click("#position-play");
await until(
"partie commencée",
() =>
location.hash === "#/" &&
!document.body.classList.contains("busy") &&
!document.getElementById("roll").hidden,
);
}
/** Une case du plateau de jeu : « off » pour la sortie du joueur. */
const place = (point) => (point === 0 ? "off-player" : `p${point}`);
/** Joue un coup déjà lancé, demi-coup par demi-coup, puis le valide. */
async function playMove(halfMoves) {
for (const [from, to] of halfMoves) {
await page.click(`#board .hit[data-place="${place(from)}"]`);
await idle();
const land = page.locator(`#board .hit.can-land[data-place="${place(to)}"]`);
if ((await land.count()) > 0) {
await land.click();
await idle();
}
}
check(!(await page.locator("#confirm").isHidden()), `coup incomplet : ${JSON.stringify(halfMoves)}`);
await page.click("#confirm");
}
/** Lance les dés imposés et joue un coup. */
async function play(dice, halfMoves) {
await page.evaluate((d) => {
window.__dice.push(...d);
}, dice);
await page.click("#roll");
await idle();
await playMove(halfMoves);
}
// --------------------------------------------- Une partie, puis son bilan
await startFrom(BEAROFF);
await play([6, 1], [[6, 5], [5, 0]]);
// L'ordinateur, sûr de gagner, double. La ligne du maître commente le
// coup : sa feuille d'explication écrit le coup joué dans la notation du
// moteur, comme le bilan et l'analyse plus bas.
await until("double de l'ordinateur", () => !document.getElementById("drop").hidden);
await until("ligne du maître", () => !document.getElementById("advice-line").hidden);
await page.click("#advice-line");
await until("feuille du maître", () => document.getElementById("explain-mine") !== null);
await page.click("#explain-mine");
const sheetLegend = await page.textContent("#explain-legend");
check(sheetLegend.includes(" 6/off,"), `feuille du maître : ${sheetLegend}`);
// Le coup y est un lien vers la fiche « Notation des coups ».
const notationLink = await page.evaluate(() => {
const a = document.querySelector("#explain-legend a.notation");
return a === null ? null : { text: a.textContent, href: a.getAttribute("href") };
});
check(
notationLink?.text === "6/off" && notationLink.href === "#/glossaire/notation-des-coups",
`feuille du maître, lien de la notation : ${JSON.stringify(notationLink)}`,
);
await page.click("#explain-done");
await until("feuille fermée", () => document.getElementById("explain-veil").hidden);
// Le joueur passe.
await page.click("#drop");
// Le panneau de fin de partie, puis le bilan à sa place, à son adresse.
await until(
"bilan prêt",
() =>
/^#\/parties\/[a-z0-9-]+\/bilan$/.test(location.hash) &&
document.getElementById("summary")?.dataset.ready === "true",
);
await until("mini-plateau du coup à revoir", () =>
document.querySelector("#summary-board .board-frame") !== null,
);
const summary = await page.evaluate(() => ({
hash: location.hash,
panelHidden: document.getElementById("panel-veil").hidden,
title: document.getElementById("summary-title").textContent,
reading: document.getElementById("summary-reading").textContent,
counts: [...document.querySelectorAll(".summary-count .summary-number")].map(
(n) => n.textContent,
),
verdict: document.querySelector(".summary-verdict")?.textContent ?? "",
played: document.querySelector(".summary-played")?.textContent ?? "",
master: document.querySelector(".summary-master")?.textContent ?? "",
board: document.querySelector("#summary-board .board-frame") !== null,
play: document.querySelector("#gauge-play .gauge-value")?.textContent ?? "",
dice: document.querySelector("#gauge-dice .gauge-value")?.textContent ?? "",
slot: document.querySelector("#summary-review .ask-ai-slot") !== null,
}));
const id = summary.hash.split("/")[2];
check(summary.panelHidden, "le panneau de fin de partie reste sous le bilan");
check(summary.title === "L'ordinateur gagne la partie simple", `titre : ${summary.title}`);
check(
summary.reading.startsWith("Vous avez passé son double : 1 point pour lui. "),
`lecture : ${summary.reading}`,
);
check(summary.reading.includes("D'après mon analyse"), `lecture : ${summary.reading}`);
check(!summary.reading.includes("!"), `lecture : ${summary.reading}`);
// Le refus du double, juste ; le coup 6/5/off, grosse erreur ; le jet
// sans doubler, compté seulement s'il était une faute.
check(
summary.counts[0] === "1" && summary.counts[2] !== "0",
`décisions : ${summary.counts.join()}`,
);
check(summary.verdict.startsWith("Grosse erreur"), `coup à revoir : ${summary.verdict}`);
check(summary.played === "Votre coup : 6/off", `coup joué : ${summary.played}`);
check(summary.master === "J'aurais joué 6/off 1/off", `coup du maître : ${summary.master}`);
check(summary.board, "pas de mini-plateau dans le coup à revoir");
check(summary.play !== "" && summary.dice !== "", "jauges vides");
check(summary.slot, "pas d'emplacement pour « Demander à une IA »");
await capture("1-bilan");
log(`bilan : « ${summary.reading} » ; coup à revoir « ${summary.played} » contre « ${summary.master} »`);
// Le bilan se recharge par son adresse.
await page.reload();
await until(
"bilan rouvert",
() => document.getElementById("summary")?.dataset.ready === "true",
);
// ------------------------------------------------------- Écran d'analyse
await page.click("#summary-revisit");
await until(
"analyse ouverte sur le coup à revoir",
(game) =>
location.hash === `#/parties/${game}/analyse/1` &&
!document.getElementById("analysis").hidden &&
document.querySelector("#analysis-board .board-frame") !== null &&
document.querySelectorAll("#analysis-curve .curve-band").length === 2 &&
document.querySelector("#analysis-curve .curve-line") !== null,
id,
);
const viewer = await page.evaluate(() => ({
turn: document.getElementById("analysis-turn").textContent,
phrase: document.getElementById("analysis-phrase").textContent,
mine: document.getElementById("analysis-mine").getAttribute("aria-checked"),
choice: !document.getElementById("analysis-choice").hidden,
replay: !document.getElementById("analysis-replay").hidden,
slot: document.querySelector("#analysis-viewer .ask-ai-slot") !== null,
}));
check(viewer.turn === "Coup 1 sur 2 · 6-1", `visualiseur : ${viewer.turn}`);
check(viewer.phrase.startsWith("Grosse erreur."), `phrase : ${viewer.phrase}`);
check(viewer.choice && viewer.mine === "true", "votre coup n'est pas montré d'abord");
check(viewer.replay && viewer.slot, "« Rejouer d'ici » ou l'emplacement de l'IA manquent");
await capture("2-analyse-courbe");
// Toucher un point de la courbe : la bande du coup 2 (le double de
// l'ordinateur, que le joueur a passé).
const band = await page.locator('#analysis-curve .curve-band[data-turn="2"]').boundingBox();
await page.mouse.click(band.x + band.width / 2, band.y + band.height / 3);
await until(
"coup 2 choisi",
(game) =>
location.hash === `#/parties/${game}/analyse/2` &&
document.getElementById("analysis-turn").textContent.startsWith("Coup 2 sur 2"),
id,
);
const touched = await page.evaluate(() => ({
phrase: document.getElementById("analysis-phrase").textContent,
ring: document.querySelector("#analysis-curve .curve-ring") !== null,
replay: document.getElementById("analysis-replay").hidden,
}));
check(touched.phrase.startsWith("Bonne décision."), `coup 2 : ${touched.phrase}`);
check(touched.ring, "le point choisi n'est pas cerclé");
check(!touched.replay, "pas de « Rejouer d'ici » sur une décision du joueur");
await capture("3-point-touche");
// Au clavier, ← revient au coup 1.
await page.focus("#analysis-curve");
await page.keyboard.press("ArrowLeft");
await until("coup 1 au clavier", (game) => location.hash === `#/parties/${game}/analyse/1`, id);
// La liste, filtrée : une erreur, aucune imprécision.
await page.click('#analysis-filters .filter[data-filter="errors"]');
const errors = await page.evaluate(() => ({
rows: [...document.querySelectorAll("#analysis-list .analysis-row")].map((r) =>
r.getAttribute("aria-label"),
),
filters: [...document.querySelectorAll("#analysis-filters .filter")].map((f) => f.textContent),
}));
check(errors.rows.length === 1 && errors.rows[0].includes("Grosse erreur"), `liste : ${errors.rows}`);
check(errors.filters.join() === "Tout · 2,Erreurs · 1,Imprécisions · 0", `filtres : ${errors.filters}`);
await page.locator("#analysis-list").scrollIntoViewIfNeeded();
await capture("4-liste-filtree");
await page.click('#analysis-filters .filter[data-filter="doubtful"]');
check(
(await page.locator("#analysis-list .analysis-row").count()) === 0,
"une imprécision dans la liste",
);
await page.click('#analysis-filters .filter[data-filter="errors"]');
await page.click("#analysis-list .analysis-row");
// Le visualiseur : le coup du maître sur la position d'avant le coup.
await page.locator("#analysis-viewer").scrollIntoViewIfNeeded();
await page.click("#analysis-best");
const best = await page.evaluate(() => ({
legend: document.getElementById("analysis-legend").textContent,
move: document.getElementById("analysis-board").dataset.move,
}));
check(best.move === "best" && best.legend.includes("6/off 1/off"), `maître : ${best.legend}`);
// Une seule notation, celle du moteur : le même coup s'écrit pareil dans
// la feuille du maître, le bilan, la liste et le visualiseur.
await page.click("#analysis-mine");
const notations = await page.evaluate(() => ({
legend: document.getElementById("analysis-legend").textContent,
row: document.querySelector('#analysis-list .analysis-row[data-turn="1"] .row-move')
?.textContent,
}));
check(
notations.legend.includes(" 6/off,") && notations.row === "6/off",
`notation : visualiseur « ${notations.legend} », liste « ${notations.row} »`,
);
await page.click("#analysis-best");
await capture("5-visualiseur");
log("analyse : courbe, point touché, clavier, liste filtrée, visualiseur");
// L'analyse s'ouvre aussi par son adresse, dans un nouvel onglet.
const other = await context.newPage();
await other.goto(`${base}#/parties/${id}/analyse/2`);
for (let waited = 0; ; waited += 100) {
const ready = await other.evaluate(
() =>
!document.getElementById("analysis").hidden &&
document.getElementById("analysis-turn")?.textContent.startsWith("Coup 2 sur 2"),
);
if (ready) {
break;
}
check(waited < 60_000, "l'analyse ne s'ouvre pas par son adresse");
await sleep(100);
}
await other.close();
// ------------------------------------------------------- Rejouer d'ici
await page.click("#analysis-replay");
await until(
"partie reprise avant le coup",
() =>
location.hash === "#/" &&
!document.body.classList.contains("busy") &&
document.querySelector("#board .hit.can-move") !== null,
);
await capture("6-rejouer-d-ici");
// Le pion du point 1 d'abord : chacun n'a alors qu'une arrivée, la sortie.
await playMove([
[1, 0],
[6, 0],
]);
await until(
"partie gagnée, son bilan",
() =>
/\/bilan$/.test(location.hash) &&
document.getElementById("summary")?.dataset.ready === "true",
);
const won = await page.evaluate(() => ({
title: document.getElementById("summary-title").textContent,
none: document.querySelector(".summary-none")?.textContent ?? "",
}));
check(won.title === "Vous gagnez la partie simple", `branche : ${won.title}`);
check(won.none.startsWith("Aucun coup à revoir"), `branche : ${won.none}`);
// Deux branches dans « Mes parties », l'originale intacte.
await page.goto(`${base}#/parties/${id}`);
await until(
"branches dépliées",
() => document.querySelectorAll(".games-branch").length > 0,
);
const branches = await page.evaluate(() =>
[...document.querySelectorAll(".games-branch span")].map((s) => s.textContent),
);
check(branches.length === 2, `branches : ${branches.join(" | ")}`);
check(branches[0].startsWith("Partie d'origine : 1 coup, finie"), `origine : ${branches[0]}`);
log(`rejouer d'ici : ${branches.join(" | ")}`);
// ------------------------------------------- Une partie plus longue
// Pour juger la courbe en usage réel (Chromium seulement) : une longue
// course (tests/reference/positions.json, race-2) jouée jusqu'au bout,
// le joueur prenant à chaque fois le premier pion jouable et sa première
// arrivée, puis son analyse complète.
if (full) {
await startFrom("cLezAQBwN2cGAA");
for (let actions = 0; ; actions++) {
check(actions < 2000, "la longue partie ne finit pas");
const what = await page.evaluate(() => {
if (document.body.classList.contains("busy")) {
return null;
}
if (!document.getElementById("summary-veil").hidden) {
return "over";
}
if (!document.getElementById("panel-veil").hidden) {
return "panel";
}
const usable = (id) => {
const b = document.getElementById(id);
return !b.hidden && !b.disabled;
};
for (const id of ["take", "skip", "confirm", "roll"]) {
if (usable(id)) {
return id;
}
}
if (document.querySelector("#board .hit.can-land")) {
return "land";
}
return document.querySelector("#board .hit.can-move") ? "move" : null;
});
if (what === "over") {
break;
}
if (what === null || what === "panel") {
await sleep(100);
continue;
}
const target = {
take: "#take",
skip: "#skip",
confirm: "#confirm",
roll: "#roll",
land: "#board .hit.can-land",
move: "#board .hit.can-move",
}[what];
await page.locator(target).first().click();
await idle();
}
await until("bilan de la longue partie", () =>
document.getElementById("summary")?.dataset.ready === "true");
await page.click("#summary-analysis");
await until("analyse complète de la longue partie", () => {
const bands = document.querySelectorAll("#analysis-curve .curve-band").length;
return (
!document.getElementById("analysis").hidden &&
bands >= 20 &&
document.querySelectorAll("#analysis-curve .curve-dot").length === bands
);
}, null, 600_000);
const turns = await page.locator("#analysis-curve .curve-band").count();
await page.evaluate(() => window.scrollTo(0, 0));
await capture("7-analyse-partie-longue");
log(`longue partie : ${turns} coups, courbe complète`);
}
const csp = await page.evaluate(() => window.__csp);
for (const violation of csp) {
problems.push(`politique de sécurité : ${violation}`);
}
await browser.close();
if (problems.length > 0) {
for (const problem of problems) {
console.error(`[${browserName}] ${problem}`);
}
process.exit(1);
}
log(`bilan et analyse : tout est conforme (${captures} captures)`);
+22 -8
View File
@@ -117,6 +117,10 @@ async function todo() {
if (!panel.hidden) {
return panel.dataset.kind;
}
// Le bilan remplace le panneau de fin de partie (étape 1e).
if (!document.getElementById("summary-veil").hidden) {
return "over";
}
const usable = (id) => {
const b = document.getElementById(id);
return !b.hidden && !b.disabled;
@@ -190,7 +194,7 @@ await page.click("#new-game-match");
await page.click("#new-game-length-3");
await page.click("#new-game-level-beginner");
s = await screen();
check(s.match === "true" && s.lengthsShown && !s.jacobyShown && s.start === "Commencer le match en 3 points",
check(s.match === "true" && s.lengthsShown && !s.jacobyShown && s.start === "Commencer le match",
`match en 3 points : ${JSON.stringify(s)}`);
check(s.level === "beginner" && s.reached === 1 && s.name === "Débutant", `Débutant : ${JSON.stringify(s)}`);
check((await page.getAttribute("#new-game-crawford a", "href")) === "#/glossaire/regle-de-crawford",
@@ -250,7 +254,7 @@ await page.click("#menu-new-game");
await until("écran « Nouvelle partie »", () => location.hash === "#/nouvelle-partie" &&
!document.getElementById("new-game").hidden);
s = await screen();
check(s.match === "true" && s.level === "beginner" && s.start === "Commencer le match en 3 points",
check(s.match === "true" && s.level === "beginner" && s.start === "Commencer le match",
`choix retrouvés : ${JSON.stringify(s)}`);
await page.click("#new-game-start");
await until("match commencé", () => location.hash === "#/" && !document.body.classList.contains("busy"));
@@ -282,12 +286,17 @@ for (;;) {
check(now.cube === 0 && !now.double, `partie Crawford : videau visible ${JSON.stringify(now)}`);
}
if (what === "over") {
const title = await page.textContent("#panel-text");
const detail = await page.textContent("#panel-detail");
const primary = await page.textContent("#panel-primary");
// Le bilan, une fois l'analyse prête, à la place du panneau.
await until("bilan prêt", () =>
!document.getElementById("summary-veil").hidden &&
document.getElementById("summary")?.dataset.ready === "true", null, 120_000);
const title = await page.textContent("#summary-title");
const reading = await page.textContent("#summary-reading");
const detail = reading.split(" D'après mon analyse")[0];
const primary = await page.textContent("#summary-primary");
log(`partie ${games}${crawford ? " (Crawford)" : ""} : ${title} ; ${detail}`);
const settingsLink = await page.evaluate(() => {
const a = document.getElementById("panel-settings");
const a = document.getElementById("summary-settings");
return a.hidden ? null : { text: a.textContent, href: a.getAttribute("href") };
});
check(settingsLink?.text === "Changer les réglages" && settingsLink.href === "#/nouvelle-partie",
@@ -309,10 +318,15 @@ for (;;) {
// Après le match, « Changer les réglages » mène à l'écran des
// choix ; le fermer ramène au résultat, où « Rejouer » relance
// tout de suite un match de même longueur.
await page.click("#panel-settings");
await page.click("#summary-settings");
await until("écran « Nouvelle partie » après le match", () =>
location.hash === "#/nouvelle-partie" && document.getElementById("panel-veil").hidden);
await page.click("#new-game-close");
// Retour au bilan ; le fermer laisse le résultat sur le plateau.
await until("retour au bilan du match", () =>
/\/bilan$/.test(location.hash) &&
document.getElementById("summary")?.dataset.ready === "true");
await page.click("#summary-close");
await until("retour au résultat du match", () => location.hash === "#/" &&
!document.getElementById("again").hidden);
check((await page.textContent("#again")) === "Rejouer",
@@ -334,7 +348,7 @@ for (;;) {
}
check(primary === "Partie suivante" && /Match en 3 points : vous \d+, l'ordinateur \d+/.test(detail),
`fin de partie dans un match : ${primary} ; ${detail}`);
await page.click("#panel-primary");
await page.click("#summary-primary");
games++;
await until("partie suivante", () => !document.body.classList.contains("busy"));
const next = await shownMatch();
+321
View File
@@ -0,0 +1,321 @@
// nouvelle-partie.mjs -- après une partie finie et son bilan, « Nouvelle
// partie » mène tout droit à la nouvelle partie, sur le plateau, avec les
// réglages choisis, par chaque entrée vers #/nouvelle-partie : l'accueil
// (l'application rouverte), le menu, « Changer les réglages » du bilan.
// Dans un vrai navigateur sans écran (Playwright), sur le site servi par
// l'image de production.
//
// Copyright (C) 2026 les auteurs d'Ustagammon.
// Licence : GPLv3 ou ultérieure (voir LICENSE).
//
// Usage : node nouvelle-partie.mjs <adresse du site> <chromium|firefox> <dossier des captures>
// Lancé par tests/browser.sh. Défaut signalé par un joueur : « tu fais
// nouvelle partie […] tu te retrouves sur le résultat du match précédent et
// tu dois cliquer à nouveau sur nouvelle partie ». Chaque partie finie est
// une fin de course courte, partie d'un lien de position avec des dés
// imposés, comme dans bilan.mjs. Vérifie aussi le libellé du bouton
// (« Commencer la partie », « Commencer le match ») et que le coup de
// l'ordinateur, sur la ligne d'information, mène à la fiche « Notation des
// coups ». Captures (Chromium) dans <dossier des captures>/nouvelle-partie/,
// en 412×915 et 915×412.
import { mkdirSync } from "node:fs";
import { chromium, firefox } from "playwright";
import { hiddenUnderActionBar } from "./recette.mjs";
const [base, browserName, shots] = process.argv.slice(2);
const browserType = { chromium, firefox }[browserName];
if (!base || !browserType || !shots) {
console.error("usage : node nouvelle-partie.mjs <adresse> <chromium|firefox> <dossier des captures>");
process.exit(2);
}
const full = browserName === "chromium";
const dir = `${shots}/nouvelle-partie`;
mkdirSync(dir, { recursive: true });
const PORTRAIT = { width: 412, height: 915 };
const LANDSCAPE = { width: 915, height: 412 };
// Le joueur au trait : un pion sur 6, un sur 1 ; l'ordinateur : un sur 1,
// un sur 2. Le joueur joue 6/5/off, l'ordinateur double, le joueur passe.
const BEAROFF = "BQAACAIAAAAAAA";
const problems = [];
const log = (text) => console.log(`[${browserName}] ${text}`);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
let captures = 0;
function check(condition, message) {
if (!condition) {
throw new Error(message);
}
}
const browser = await browserType.launch();
const context = await browser.newContext({
viewport: PORTRAIT,
deviceScaleFactor: 1,
locale: "fr-FR",
reducedMotion: "reduce",
});
await context.addInitScript(() => {
// Les dés imposés d'abord (un dé par valeur), puis une graine fixe.
window.__dice = [];
let state = 7;
Math.random = () => {
const die = window.__dice.shift();
if (die !== undefined) {
return (die - 0.5) / 6;
}
state = (state * 1103515245 + 12345) % 2147483648;
return state / 2147483648;
};
window.__csp = [];
document.addEventListener("securitypolicyviolation", (e) =>
window.__csp.push(`${e.effectiveDirective} ${e.blockedURI}`),
);
});
const page = await context.newPage();
page.on("pageerror", (error) => problems.push(`erreur de la page : ${error.message}`));
page.on("console", (message) => {
if (message.type() === "error") {
problems.push(`console : ${message.text()}`);
}
});
/** Attend une condition dans la page (sans page.waitForFunction, qui passe
* par eval, interdit par la politique de sécurité du site). */
async function until(what, fn, arg, ms = 120_000) {
for (let waited = 0; waited < ms; waited += 100) {
if (await page.evaluate(fn, arg)) {
return;
}
await sleep(100);
}
await page.screenshot({ path: `${dir}/${browserName}-bloque.png` }).catch(() => {});
throw new Error(`attente trop longue : ${what} (adresse ${await page.evaluate(() => location.hash)})`);
}
const idle = () => until("écran libre", () => !document.body.classList.contains("busy"));
/** Une capture en portrait et en paysage (Chromium seulement), après la
* règle de la recette : rien d'interactif sous une barre d'action. */
async function capture(name) {
if (!full) {
return;
}
for (const size of [PORTRAIT, LANDSCAPE]) {
await page.setViewportSize(size);
await sleep(300);
const hidden = await hiddenUnderActionBar(page);
check(
hidden.length === 0,
`${name} ${size.width}x${size.height} : caché sous la barre d'action : ${hidden.join(", ")}`,
);
await page.screenshot({ path: `${dir}/${name}-${size.width}x${size.height}.png` });
captures++;
}
await page.setViewportSize(PORTRAIT);
await sleep(300);
}
/** Une partie finie et son bilan à l'écran : une fin de course depuis un
* lien de position, 6/5/off, puis le double de l'ordinateur passé. Renvoie
* l'identifiant de la partie. */
async function finishedGameWithSummary() {
await page.goto(`${base}#/position/${encodeURIComponent(BEAROFF)}`);
await until("position lue", () => {
const play = document.getElementById("position-play");
return !play.hidden && !play.disabled;
});
await page.click("#position-play");
await until(
"partie commencée",
() =>
location.hash === "#/" &&
!document.body.classList.contains("busy") &&
!document.getElementById("roll").hidden,
);
await page.evaluate(() => window.__dice.push(6, 1));
await page.click("#roll");
await idle();
for (const [from, to] of [
["p6", "p5"],
["p5", "off-player"],
]) {
await page.click(`#board .hit[data-place="${from}"]`);
await idle();
const land = page.locator(`#board .hit.can-land[data-place="${to}"]`);
if ((await land.count()) > 0) {
await land.click();
await idle();
}
}
await page.click("#confirm");
await until("double de l'ordinateur", () => !document.getElementById("drop").hidden);
await page.click("#drop");
await until(
"bilan de la partie finie",
() =>
/^#\/parties\/[a-z0-9-]+\/bilan$/.test(location.hash) &&
document.getElementById("summary")?.dataset.ready === "true",
);
return page.evaluate(() => location.hash.split("/")[2]);
}
/** Choisit les réglages sur l'écran « Nouvelle partie », vérifie le libellé
* du bouton, puis commence. */
async function chooseAndStart(choice, shot) {
await until(
"écran « Nouvelle partie »",
() =>
location.hash === "#/nouvelle-partie" &&
!document.getElementById("new-game").hidden &&
!document.getElementById("new-game-start").disabled,
);
await page.click(choice.match ? "#new-game-match" : "#new-game-free");
if (choice.match) {
await page.click(`#new-game-length-${choice.length}`);
}
await page.click(`#new-game-level-${choice.level}`);
const label = await page.textContent("#new-game-start");
const expected = choice.match ? "Commencer le match" : "Commencer la partie";
check(label === expected, `bouton : « ${label} », attendu « ${expected} »`);
if (shot) {
await capture("1-nouvelle-partie");
}
await page.click("#new-game-start");
}
/** La nouvelle partie est à l'écran, sur le plateau, avec les réglages
* choisis ; ni le bilan ni le panneau de fin de l'ancienne partie, même un
* peu plus tard. */
async function checkNewGame(entry, oldId, choice) {
await until(
`${entry} : partie commencée`,
() => location.hash === "#/" && !document.body.classList.contains("busy"),
);
// Le défaut apparaissait juste après : l'adresse passait au bilan de
// l'ancienne partie. On regarde pendant deux secondes.
for (let waited = 0; waited < 2000; waited += 100) {
const s = await page.evaluate(() => ({
hash: location.hash,
summary: !document.getElementById("summary-veil").hidden,
panel: !document.getElementById("panel-veil").hidden,
board: !document.getElementById("game").hidden,
newGame: !document.getElementById("new-game").hidden,
}));
check(
s.hash === "#/" && !s.summary && !s.panel && s.board && !s.newGame,
`${entry} : la nouvelle partie n'est pas à l'écran (ancienne partie ${oldId}) : ${JSON.stringify(s)}`,
);
await sleep(100);
}
await idle();
const shown = await page.evaluate(() => ({
line: document.getElementById("match-line").textContent,
lineShown: !document.getElementById("match-line").hidden,
level: JSON.parse(localStorage.getItem("ustagammon.settings") ?? "{}").level,
over: document.getElementById("again").hidden === false,
}));
check(!shown.over, `${entry} : la partie à l'écran est finie`);
check(shown.level === choice.level, `${entry} : niveau ${shown.level}`);
if (choice.match) {
check(
shown.lineShown && shown.line === `Match en ${choice.length} points`,
`${entry} : ligne du match « ${shown.line} »`,
);
} else {
check(!shown.lineShown, `${entry} : un match au lieu d'une partie libre`);
}
log(`${entry} : nouvelle partie directe (${choice.match ? `match en ${choice.length}` : "partie libre"}, ${choice.level})`);
}
// --------------------------- 1. L'application rouverte, puis l'accueil
let oldId = await finishedGameWithSummary();
// L'application rouverte : sans adresse, elle ouvre l'accueil.
await page.goto(base);
await until(
"accueil",
() =>
location.hash === "#/accueil" &&
!document.getElementById("home-new").hidden &&
!document.getElementById("home-new").disabled,
);
await page.click("#home-new");
let choice = { match: true, length: 3, level: "beginner" };
await chooseAndStart(choice, true);
await checkNewGame("accueil", oldId, choice);
await capture("2-partie-demarree");
// Le coup de l'ordinateur, sur la ligne d'information, mène à la fiche
// « Notation des coups ». On joue jusqu'à ce qu'il ait joué un coup.
for (let actions = 0; ; actions++) {
check(actions < 200, "l'ordinateur ne joue pas de coup");
const link = await page.evaluate(() => document.querySelector("#info a.notation")?.href ?? null);
if (link !== null) {
check(link.endsWith("#/glossaire/notation-des-coups"), `lien de la notation : ${link}`);
break;
}
const what = await page.evaluate(() => {
const usable = (id) => {
const b = document.getElementById(id);
return !b.hidden && !b.disabled;
};
for (const id of ["take", "skip", "confirm", "roll"]) {
if (usable(id)) {
return `#${id}`;
}
}
if (document.querySelector("#board .hit.can-land")) {
return "#board .hit.can-land";
}
return document.querySelector("#board .hit.can-move") ? "#board .hit.can-move" : null;
});
if (what === null) {
await sleep(100);
continue;
}
await page.locator(what).first().click();
await idle();
}
await page.click("#info a.notation");
await until(
"fiche « Notation des coups »",
() =>
location.hash === "#/glossaire/notation-des-coups" &&
document.getElementById("glossaire-notation-des-coups") !== null,
);
await page.goBack();
await until("retour à la partie", () => location.hash === "#/");
log("ligne de l'ordinateur : la notation mène à sa fiche");
// --------------------------------- 2. L'application rouverte sur le menu
oldId = await finishedGameWithSummary();
await page.goto(`${base}#/menu`);
await until("menu", () => !document.getElementById("menu-veil").hidden);
await page.click("#menu-new-game");
choice = { match: false, level: "amateur" };
await chooseAndStart(choice, false);
await checkNewGame("menu", oldId, choice);
// ------------------------------- 3. « Changer les réglages » du bilan
oldId = await finishedGameWithSummary();
await page.click("#summary-settings");
choice = { match: true, length: 5, level: "intermediate" };
await chooseAndStart(choice, false);
await checkNewGame("bilan, « Changer les réglages »", oldId, choice);
const csp = await page.evaluate(() => window.__csp);
for (const violation of csp) {
problems.push(`politique de sécurité : ${violation}`);
}
await browser.close();
if (problems.length > 0) {
for (const problem of problems) {
console.error(`[${browserName}] ${problem}`);
}
process.exit(1);
}
log(`nouvelle partie : tout est conforme (${captures} captures)`);

Some files were not shown because too many files have changed in this diff Show More