# 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.