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.