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.