Ustagammon/docs/adr/0013-position-dans-l-adresse.md

0013. Une position du plateau dans l'adresse de la page

• Statut : accepté
• Date : 2026-11-03
• Décideurs : Pierre (besoin), Claude Code (format)

Contexte

Pierre a demandé, au premier test sur le téléphone (2026-11-03), qu'avec la seule adresse on arrive à une position du plateau : chaque position devient un lien direct, à partager, à mettre dans une leçon ou dans un prompt pour une IA. GNU Backgammon décrit déjà toute position par deux identifiants publics et documentés : le Position ID (14 caractères, les pions) et le Match ID (12 caractères : videau, score, longueur du match, joueur au trait, dés). Le moteur sait les lire et les écrire (engine.h).

Décision

• L'adresse porte la position dans le fragment (après #) : https://ustagammon.sans.pub/#position=<Position ID>&match=<Match ID>, chaque identifiant encodé avec encodeURIComponent (le base64 de gnubg contient + et /). match est facultatif : sans lui, partie libre, videau au centre, joueur du bas au trait, sans dés.
• Ouvrir un tel lien affiche la position, non jouable, avec deux actions : « Jouer à partir d'ici » (nouvelle partie contre l'ordinateur depuis cette position, sans toucher à la partie en cours) et « Retour à ma partie ».
• Toute position affichée (partie, coup de l'ordinateur, analyse, leçon) peut être copiée en lien (« Copier le lien de la position »).
• Un identifiant illisible pour le moteur donne un message clair et le retour à la partie, jamais une page cassée.

Alternatives écartées

• Paramètres de requête (?position=) : ils changent l'adresse demandée au serveur et au service worker ; hors ligne, la page en cache ne correspondrait plus. Le fragment ne quitte jamais le navigateur.
• XGID (format d'eXtreme Gammon) : répandu, mais un seul identifiant de plus à décoder ; gnubg l'importe, son import pourra s'ajouter plus tard (outil « import d'un identifiant GNU ou XGID » du cadrage).
• Format maison plus lisible : il faudrait le décoder sans le moteur, donc réimplémenter une règle de représentation (ADR 0007).

Conséquences

• Le fragment est lu au chargement et à chaque changement (hashchange) ; le domaine reçoit une position et un Match ID, le moteur les valide.
• Les liens restent valables tant que GNU Backgammon garde ces formats, stables depuis des années.
• Les liens contiennent la position, rien d'autre : pas de donnée personnelle.

Amendements

2026-11-03 — Une adresse pour chaque écran, des liens plutôt que des états

Demandé par Pierre : « il faudra vraiment que chaque page (l'aide, etc.) ait une URL. Utilise des liens accessibles, pas des états. » Aucun lien de position n'a encore circulé : le format ci-dessus est remplacé par un schéma unique pour tous les écrans, avant sa première mise en œuvre.

• Chaque écran a son adresse, dans le fragment (pour les mêmes raisons qu'au-dessus : hors ligne, service worker, aucune configuration serveur) :

  Écran	Adresse
  Partie en cours	#/
  Accueil	#/accueil
  Aide (onglet Jouer)	#/aide, une question : #/aide/<identifiant>
  Les mots du jeu	#/glossaire, un terme : #/glossaire/<fichier sans .md>
  À propos	#/a-propos
  Tutoriel	#/tutoriel, une étape : #/tutoriel/<n>
  Mes parties	#/parties, une partie : #/parties/<id>
  Réglages / menu	#/menu
  Une position	#/position/<Position ID>/<Match ID> (Match ID facultatif)

  Les identifiants de gnubg sont encodés avec encodeURIComponent. Les écrans à venir (analyse, leçons, progression) suivront le même schéma.

• On change d'écran par de vrais liens (<a href="#/aide">), pas par des boutons qui modifient un état caché : le lien se partage, s'ouvre dans un nouvel onglet, se lit aux lecteurs d'écran comme un lien, et le bouton « retour » du téléphone ramène à l'écran précédent. Les actions de jeu (lancer, jouer, doubler) restent des boutons : elles ne sont pas des écrans.

• Les feuilles (menu, explication) et panneaux qui sont des écrans à part entière ont aussi leur adresse ; une confirmation ou un bandeau éphémère n'en a pas.

• Une adresse inconnue mène à la partie en cours avec un message clair.

• L'adresse de l'écran courant est la source de vérité de la navigation : l'application l'écoute (hashchange) et dessine l'écran correspondant.

2026-11-09 — Adresses du tutoriel et de l'installation

Ajoutées avec l'accueil et le tutoriel (étape 0e.5), dans le même schéma :

Écran	Adresse
Écran « à vous » d'une étape du tutoriel	#/tutoriel/<n>/a-vous
Fin du tutoriel	#/tutoriel/fin
Marche à suivre pour installer l'application	#/installer

Lancée sans adresse, l'application ouvre l'accueil (#/accueil) ; #/ reste la partie en cours, pour que les liens existants ne changent pas.

2026-11-09 — Adresse de l'écran « Nouvelle partie »

Ajoutée avec le choix de la partie et le match (étape 1c), dans le même schéma :

Écran	Adresse
Nouvelle partie : type de partie, niveau, conseil du maître	#/nouvelle-partie

Le menu, l'accueil et « Nouvelle partie » en fin de partie y mènent. « Commencer » remplace cette adresse par celle de la partie (#/) : le retour du téléphone ne rouvre pas l'écran. Le lien d'une position d'une partie de match porte le Match ID du match (longueur, score, partie Crawford), écrit par le moteur.

2026-11-10 — Adresse de la feuille d'explication du maître

Ajoutée avec le conseil du maître (étape 1d), dans le même schéma :

Écran	Adresse
Feuille d'explication du maître sur une décision de la partie en cours	#/explication/<événement>

<événement> est l'identifiant, dans le journal de la partie en cours, de l'événement de la décision commentée (le coup, le double, la prise…). La ligne du maître est un lien vers cette adresse ; la feuille monte au-dessus de la partie, comme le menu, et « Fermer » (ou le retour du téléphone) revient à la partie. Rechargée, l'adresse rouvre la même explication : le 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.