Parties enregistrées : IndexedDB, branches, export SGF relu par gnubg

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app/src/domain/game/branches.ts

@@ -0,0 +1,91 @@
+// Les branches d'une partie : les lignes de jeu de son journal.
+//
+// Copyright (C) 2026 les auteurs d'Ustagammon.
+// Licence : GPLv3 ou ultérieure (voir LICENSE).
+//
+// Le journal est un arbre (events.ts) : chaque événement pointe vers son
+// parent, et « Rejouer d'ici » accroche un nouvel événement à un ancien. Une
+// branche est le chemin du premier événement jusqu'à une feuille de l'arbre.
+// Les identifiants des événements sont attribués dans l'ordre d'ajout : de
+// deux enfants d'un même événement, le plus ancien a le plus petit indice
+// dans le journal, et c'est lui qui continue la ligne d'origine.
+
+import { currentLine, type GameEvent, type GameJournal, goBackTo } from "./events.js";
+import { replay } from "./state.js";
+
+/**
+ * Une branche de la partie : la suite d'événements du début jusqu'à head.
+ *
+ * Glossaire : docs/glossaire/branche.md
+ */
+export interface Branch {
+    /** Le dernier événement de la branche (une feuille de l'arbre). */
+    readonly head: string;
+    /** L'événement à partir duquel elle a été rejouée (« Rejouer d'ici ») ;
+     * null pour la ligne d'origine de la partie. */
+    readonly forkedFrom: string | null;
+    /** Les coups joués avant de rejouer (0 : depuis le début) ; 0 aussi pour
+     * la ligne d'origine. */
+    readonly forkMoveCount: number;
+    /** Les coups joués sur toute la branche, depuis le début. */
+    readonly moveCount: number;
+    /** La partie est finie au bout de cette branche. */
+    readonly over: boolean;
+    /** L'événement courant de la partie est sur cette branche. */
+    readonly containsHead: boolean;
+}
+
+/**
+ * Les branches de la partie, dans l'ordre de leur création (celui de leur
+ * premier événement propre) : la ligne d'origine d'abord. Liste vide pour un
+ * journal vide.
+ */
+export function branches(journal: GameJournal): Branch[] {
+    const order = new Map(journal.events.map((event, index) => [event.id, index]));
+    const children = new Map<string, GameEvent[]>();
+    for (const event of journal.events) {
+        if (event.parent !== null) {
+            children.set(event.parent, [...(children.get(event.parent) ?? []), event]);
+        }
+    }
+    const leaves = journal.events.filter((event) => !children.has(event.id));
+    return leaves
+        .map((leaf) => {
+            const line = currentLine({ events: journal.events, head: leaf.id });
+            // Le point de départ de la branche : le parent de l'événement le
+            // plus récent du chemin qui n'est pas le premier enfant de son
+            // parent (la ligne d'origine n'en a aucun).
+            let forkIndex = -1;
+            for (let i = line.length - 1; i > 0; i--) {
+                const event = line[i] as GameEvent;
+                const first = children.get(event.parent as string)?.[0];
+                if (first !== undefined && first.id !== event.id) {
+                    forkIndex = i - 1;
+                    break;
+                }
+            }
+            const moves = (events: readonly GameEvent[]) =>
+                events.filter((event) => event.type === "MovePlayed").length;
+            const fork = forkIndex >= 0 ? (line[forkIndex] as GameEvent) : null;
+            const start = line[forkIndex + 1] as GameEvent;
+            return {
+                created: order.get(start.id) ?? 0,
+                head: leaf.id,
+                forkedFrom: fork?.id ?? null,
+                forkMoveCount: fork === null ? 0 : moves(line.slice(0, forkIndex + 1)),
+                moveCount: moves(line),
+                over: replay(line).phase === "over",
+                containsHead: line.some((event) => event.id === journal.head),
+            };
+        })
+        .sort((a, b) => a.created - b.created)
+        .map(({ created: _, ...branch }) => branch);
+}
+
+/** Passe à une autre branche : la partie reprend au bout de celle-ci. */
+export function switchToBranch(journal: GameJournal, head: string): GameJournal {
+    if (!branches(journal).some((branch) => branch.head === head)) {
+        throw new Error(`branche introuvable : ${head}`);
+    }
+    return goBackTo(journal, head);
+}

app/src/domain/game/game.ts

@@ -8,6 +8,7 @@
 // (state.ts). Les règles viennent toutes du moteur : coups légaux, coup de
 // l'ordinateur, videau, fin de partie et points.
 
+import { type Branch, branches, switchToBranch } from "./branches.js";
 import { CENTERED_CUBE, type Cube } from "./cube.js";
 import type { BoardSide, Engine, EngineCube, Ply } from "./engine.js";
 import {
@@ -415,6 +416,19 @@ export class Game {
         this.#journal = goBackTo(this.#journal, eventId);
     }
 
+    /** Les branches de la partie (voir branches.ts), la ligne d'origine
+     * d'abord. */
+    get branches(): Branch[] {
+        return branches(this.#journal);
+    }
+
+    /** Passe à une autre branche, désignée par son dernier événement : la
+     * partie reprend au bout de celle-ci ; les autres restent intactes. */
+    switchBranch(head: string): void {
+        this.cancelHalfMoves();
+        this.#journal = switchToBranch(this.#journal, head);
+    }
+
     /** Annule le dernier événement : la partie repart de son parent. */
     undo(): void {
         const last = this.events.at(-1);

app/src/domain/game/saved-game.ts

@@ -0,0 +1,64 @@
+// Une partie enregistrée, telle que la liste « Mes parties » la présente.
+//
+// Copyright (C) 2026 les auteurs d'Ustagammon.
+// Licence : GPLv3 ou ultérieure (voir LICENSE).
+//
+// Le journal reste la source (ADR 0007, point 3) : le résumé n'en est qu'une
+// lecture, recalculée à chaque enregistrement, pour afficher la liste sans
+// relire tous les journaux.
+
+import { branches } from "./branches.js";
+import type { Level } from "./engine.js";
+import { currentLine, type GameJournal } from "./events.js";
+import { type GameResult, replay } from "./state.js";
+
+/**
+ * Le résumé d'une partie enregistrée.
+ *
+ * Glossaire : docs/glossaire/partie-enregistree.md
+ */
+export interface SavedGameSummary {
+    /** Identifiant de la partie, unique sur l'appareil. */
+    readonly id: string;
+    /** Début de la partie et dernière action, en millisecondes depuis 1970. */
+    readonly startedAt: number;
+    readonly updatedAt: number;
+    /** Niveau de l'ordinateur, l'adversaire. */
+    readonly level: Level;
+    /** En cours ou finie, sur la branche courante. */
+    readonly status: "playing" | "over";
+    /** Le résultat sur la branche courante (null si elle n'est pas finie). */
+    readonly result: GameResult | null;
+    /** Coups joués sur la branche courante. */
+    readonly moveCount: number;
+    /** Nombre de branches (1 : jamais rejouée). */
+    readonly branchCount: number;
+}
+
+/** Ce qu'il faut savoir d'une partie pour l'enregistrer, en plus de son
+ * journal. */
+export interface SavedGameDetails {
+    readonly level: Level;
+}
+
+/** Le résumé d'un journal ; startedAt et updatedAt viennent de l'appelant
+ * (le domaine ne lit pas l'horloge). */
+export function summarizeGame(
+    id: string,
+    journal: GameJournal,
+    details: SavedGameDetails,
+    times: { readonly startedAt: number; readonly updatedAt: number },
+): SavedGameSummary {
+    const line = currentLine(journal);
+    const state = replay(line);
+    return {
+        id,
+        startedAt: times.startedAt,
+        updatedAt: times.updatedAt,
+        level: details.level,
+        status: state.phase === "over" ? "over" : "playing",
+        result: state.result,
+        moveCount: line.filter((event) => event.type === "MovePlayed").length,
+        branchCount: branches(journal).length,
+    };
+}

app/src/domain/game/sgf.ts

@@ -0,0 +1,228 @@
+// Export d'une partie au format SGF de GNU Backgammon.
+//
+// Copyright (C) 2026 les auteurs d'Ustagammon.
+// Licence : GPLv3 ou ultérieure (voir LICENSE).
+//
+// Le SGF (Smart Game Format, FF[4], GM[6] pour le backgammon) est le format
+// de fichier de GNU Backgammon : une suite de nœuds, un par coup ou décision
+// de videau, et des variantes entre parenthèses. Le journal étant un arbre,
+// l'export en est un simple parcours (ADR 0007, point 3) : chaque branche
+// devient une variante. GNU Backgammon ne lit que la première variante de
+// chaque embranchement ; la branche courante de la partie vient donc en
+// premier, pour que gnubg ouvre la partie telle que le joueur la voit.
+//
+// Conventions de gnubg (sgf.c, au commit figé par l'ADR 0005) :
+// - le joueur est « B » (le joueur 1 de gnubg, l'humain), l'ordinateur « W » ;
+// - un coup s'écrit [dés][départ arrivée]… ; une case c (1 à 24, vue de celui
+//   qui joue) s'écrit 'x' - (c - 1) pour B et 'a' + (c - 1) pour W ; la barre
+//   s'écrit 'y', la sortie 'z' ; un coup impossible n'a que ses dés ;
+// - [double], [take], [drop] pour le videau ;
+// - une position de départ autre que l'habituelle se pose par AE, AW, AB et
+//   PL, le videau par CV et CP.
+// Aucune règle n'est jugée ici : les coups et positions viennent du journal,
+// et une position de départ particulière est décodée par le moteur.
+
+import type { Engine } from "./engine.js";
+import { currentLine, type GameEvent, type GameJournal } from "./events.js";
+import { BAR, type HalfMove, OFF, START_POSITION } from "./position.js";
+import type { Side } from "./side.js";
+import { replay } from "./state.js";
+
+export interface SgfOptions {
+    /** Nom du joueur (PB). */
+    readonly playerName: string;
+    /** Nom de l'ordinateur (PW). */
+    readonly computerName: string;
+    /** Date de la partie, AAAA-MM-JJ (DT) ; absente si non fournie. */
+    readonly date?: string;
+}
+
+/** Un nœud SGF et les variantes qui le suivent. */
+interface SgfNode {
+    readonly properties: string;
+    readonly children: SgfNode[];
+}
+
+/**
+ * La partie au format SGF de GNU Backgammon, branches comprises (en
+ * variantes, la branche courante d'abord). Le moteur ne sert qu'à décoder
+ * une position de départ particulière.
+ *
+ * Glossaire : docs/glossaire/sgf.md
+ */
+export async function exportSgf(
+    engine: Engine,
+    journal: GameJournal,
+    options: SgfOptions,
+): Promise<string> {
+    const start = journal.events[0];
+    if (start?.type !== "GameStarted") {
+        throw new Error("journal de partie vide ou mal formé");
+    }
+    const byId = new Map(journal.events.map((event) => [event.id, event]));
+    const onHeadLine = new Set(currentLine(journal).map((event) => event.id));
+    const children = new Map<string, GameEvent[]>();
+    for (const event of journal.events) {
+        if (event.parent !== null) {
+            children.set(event.parent, [...(children.get(event.parent) ?? []), event]);
+        }
+    }
+    // La branche courante d'abord, puis les autres dans l'ordre du journal.
+    for (const list of children.values()) {
+        list.sort((a, b) => Number(onHeadLine.has(b.id)) - Number(onHeadLine.has(a.id)));
+    }
+
+    /** Les variantes qui suivent un événement. */
+    const variations = (id: string): SgfNode[] =>
+        (children.get(id) ?? []).flatMap((child) => {
+            const properties = nodeProperties(child, byId, children.has(child.id));
+            const below = variations(child.id);
+            return properties === null ? below : [{ properties, children: below }];
+        });
+
+    // La partie telle que la voit gnubg : la ligne courante.
+    const result = replay(currentLine(journal)).result;
+    const root = [
+        "FF[4]GM[6]CA[UTF-8]AP[Ustagammon]",
+        "MI[length:0][game:0][ws:0][bs:0]",
+        `PW[${escapeText(options.computerName)}]PB[${escapeText(options.playerName)}]`,
+        options.date === undefined ? "" : `DT[${escapeText(options.date)}]`,
+        result === null ? "" : `RE[${letter(result.winner)}+${result.points}]`,
+    ].join("");
+    // Les nœuds d'installation, à la suite l'un de l'autre, puis la partie.
+    const setup = await setupProperties(engine, start);
+    const tree = setup.reduceRight<SgfNode[]>(
+        (below, properties) => [{ properties, children: below }],
+        variations(start.id),
+    );
+    return `(;${root}${sequence(tree)})\n`;
+}
+
+/** Écrit des nœuds : une suite tant qu'il n'y a qu'une variante, puis
+ * chaque variante entre parenthèses. */
+function sequence(nodes: readonly SgfNode[]): string {
+    if (nodes.length === 1) {
+        const [node] = nodes as [SgfNode];
+        return `\n;${node.properties}${sequence(node.children)}`;
+    }
+    return nodes.map((node) => `(\n;${node.properties}${sequence(node.children)})`).join("");
+}
+
+/** Les propriétés du nœud d'un événement, ou null s'il n'en fait pas
+ * (début, dés suivis d'un coup, fin de partie). */
+function nodeProperties(
+    event: GameEvent,
+    byId: ReadonlyMap<string, GameEvent>,
+    hasChildren: boolean,
+): string | null {
+    switch (event.type) {
+        case "MovePlayed": {
+            const rolled = event.parent === null ? undefined : byId.get(event.parent);
+            if (rolled?.type !== "DiceRolled") {
+                throw new Error(`coup sans jet de dés : ${event.id}`);
+            }
+            const moves = event.halfMoves.map((h) => halfMove(h, event.side)).join("");
+            return `${letter(event.side)}[${rolled.roll[0]}${rolled.roll[1]}${moves}]`;
+        }
+        case "CubeOffered":
+            return `${letter(event.side)}[double]`;
+        case "CubeTaken":
+            return `${letter(event.side)}[take]`;
+        case "CubeDropped":
+            return `${letter(event.side)}[drop]`;
+        case "DiceRolled": {
+            // Des dés pas encore joués, au bout d'une branche.
+            if (hasChildren) {
+                return null;
+            }
+            const [a, b] = event.roll;
+            const side = event.side ?? (a > b ? "player" : a < b ? "computer" : null);
+            return side === null ? null : `PL[${letter(side)}]DI[${a}${b}]`;
+        }
+        case "GameStarted":
+        case "GameEnded":
+            return null;
+    }
+}
+
+/** Les propriétés des nœuds qui posent une position de départ particulière
+ * (aucun pour la position habituelle, videau au centre, jet d'ouverture à
+ * faire). */
+async function setupProperties(
+    engine: Engine,
+    start: Extract<GameEvent, { type: "GameStarted" }>,
+): Promise<string[]> {
+    const usual =
+        start.position === START_POSITION &&
+        start.firstTurn === null &&
+        start.cube.value === 1 &&
+        start.cube.owner === null;
+    if (usual) {
+        return [];
+    }
+    const onRoll: Side = start.firstTurn ?? "player";
+    const owner =
+        start.cube.owner === null
+            ? "centered"
+            : start.cube.owner === onRoll
+              ? "onRoll"
+              : "opponent";
+    const board = await engine.board(start.position, { value: start.cube.value, owner });
+    // Chaque camp avec sa propre numérotation : W en 'a' + (c - 1), B en
+    // 'x' - (c - 1), la barre en 'y' (comme les coups).
+    const stones = (side: Side, points: readonly number[], bar: number) => {
+        const out: string[] = [];
+        points.forEach((count, i) => {
+            for (let k = 0; k < count; k++) {
+                out.push(`[${pointLetter(i + 1, side)}]`);
+            }
+        });
+        for (let k = 0; k < bar; k++) {
+            out.push("[y]");
+        }
+        return out.join("");
+    };
+    const other: Side = onRoll === "player" ? "computer" : "player";
+    const sides = { [onRoll]: board.onRoll, [other]: board.opponent } as Record<
+        Side,
+        typeof board.onRoll
+    >;
+    const white = stones("computer", sides.computer.points, sides.computer.bar);
+    const black = stones("player", sides.player.points, sides.player.bar);
+    const nodes = [
+        `PL[${letter(onRoll)}]AE[a:y]${white === "" ? "" : `AW${white}`}${black === "" ? "" : `AB${black}`}`,
+    ];
+    if (start.cube.value !== 1) {
+        nodes.push(`CV[${start.cube.value}]`);
+    }
+    if (start.cube.owner !== null) {
+        nodes.push(`CP[${start.cube.owner === "player" ? "b" : "w"}]`);
+    }
+    return nodes;
+}
+
+function letter(side: Side): "B" | "W" {
+    return side === "player" ? "B" : "W";
+}
+
+function halfMove(h: HalfMove, side: Side): string {
+    return pointLetter(h.from, side) + pointLetter(h.to, side);
+}
+
+/** Une case vue du camp side : 1 à 24, BAR ou OFF. */
+function pointLetter(point: number, side: Side): string {
+    if (point === BAR) {
+        return "y";
+    }
+    if (point === OFF) {
+        return "z";
+    }
+    const code =
+        side === "player" ? "x".charCodeAt(0) - (point - 1) : "a".charCodeAt(0) + point - 1;
+    return String.fromCharCode(code);
+}
+
+/** Échappe un texte libre dans une valeur SGF. */
+function escapeText(text: string): string {
+    return text.replace(/[\\\]]/g, (c) => `\\${c}`);
+}