Phase 1 (1/3) : état par joueur — couche db/ et chaîne de rendu

Fil directeur du plan : chaque variable globale et chaque objet de
données gagne un player_id (sentinelle PLAYER_SHARED='__shared__' par
défaut partout — l'aperçu créateur et tous les tests existants
continuent de fonctionner À L'IDENTIQUE, aucune signature appelée sans
argument explicite ne change de comportement), plus un réglage
per_player choisi une fois à la création :
- per_player=1 (par défaut) : chaque joueur a sa propre valeur/ses
  propres lignes.
- per_player=0 : valeur/lignes partagées par tous les joueurs (ex. un
  compteur de visiteurs global, un catalogue commun).

db/global_vars/ : _global_variables passe de UNIQUE(name) à
UNIQUE(name, player_id) — SQLite ne permet pas de modifier une
contrainte UNIQUE via ALTER TABLE, reconstruction de la table détectée
et faite une seule fois (ensure_global_vars_schema.py) pour les jeux
créés avant cette phase. La ligne "modèle" (player_id=PLAYER_SHARED,
créée par le créateur) porte le réglage per_player et sert de valeur
PAR DÉFAUT : la première écriture d'un joueur sur une variable
per_player crée paresseusement SA propre ligne (copiée depuis le
modèle) ; une lecture sans ligne encore écrite retombe sur le modèle
(nouveau resolve_player_key.py). list_global_variables() (tableau de
bord) ne montre toujours que les lignes modèles ; nouveau
list_global_variables_for_player() expose la valeur EFFECTIVE d'un
joueur au runtime (full_game_payload.py).

db/definitions/ + db/rows/ : chaque table d'objet généré
(create_definition.py) gagne une colonne player_id (ADD COLUMN simple,
pas de contrainte UNIQUE en jeu ici) ; _definitions gagne per_player.
Contrairement aux variables, PAS de repli sur une ligne "modèle" pour
les lignes d'un objet per_player — une LISTE n'a pas de valeur par
défaut unique à copier comme un scalaire, un nouvel objet per_player
démarre VIDE pour chaque joueur (nouveau resolve_row_player_key.py).
get_row/update_row/update_row_field/delete_row filtrent aussi par
player_id (pas seulement id) : garde-fou contre un row_id d'un AUTRE
joueur, nécessaire dès qu'un objet per_player sera exposé sur la future
route publique /jouer/<slug>. Migration : nouveau
ensure_player_id_column(slug, table_name), appelé avant toute requête
sur une table d'objet créée avant cette phase.

Chaîne de rendu (screens/elements/list_elements.py ->
screens/rendering/render_element_html.py -> render_repeater.py/
render_jauge.py/resolve_bound_row.py/visibility_condition.py/
filter_repeater_rows.py) : player_id transite dans le ctx déjà utilisé
partout pour "champ en cours" (ctx["_forge_player_id"], même patron que
ctx["_forge_play_mode"], posé une seule fois par list_elements quand
enforce_visibility=True) — pas de nouveau paramètre positionnel à
threader dans chaque fonction, juste une clé de plus dans un mécanisme
déjà en place.

Nouveau tests/test_player_state.py : verrouille à la fois le nouveau
comportement (deux joueurs => valeurs/lignes indépendantes ; per_player=0
=> partagé ; nouveau joueur => valeur par défaut pour une variable, liste
VIDE pour un objet ; get_row ne fuite jamais vers un autre joueur) et la
non-régression de l'aperçu créateur (comportement historique inchangé).

Vérifié : 232 tests passent (9 nouveaux). Reste à faire (prochains
commits) : route publique /jouer/<slug>, identité visiteur (cookie),
bascule "Publier en ligne" dans le tableau de bord.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

db/global_vars/create_global_variable.py

@@ -1,27 +1,37 @@
 from ..connection import connect
-from .ensure_global_vars_schema import ensure_global_vars_schema
+from .ensure_global_vars_schema import ensure_global_vars_schema, PLAYER_SHARED
 from .coerce_structured_value import coerce_structured_value
 
 
-def create_global_variable(slug, name, var_type="texte", default_value=""):
-    """Crée une variable globale si son nom n'existe pas déjà (les noms sont
-    uniques — voir ensure_global_vars_schema.py) ; si elle existe déjà, ne
-    touche à rien et renvoie simplement son id existant, pour que "créer"
-    depuis le sélecteur de condition de visibilité (voir screen_edit.html)
-    reste sans risque même en cas de double clic/soumission."""
+def create_global_variable(slug, name, var_type="texte", default_value="", per_player=True):
+    """Crée la ligne "modèle" d'une variable globale (toujours
+    player_id=PLAYER_SHARED, quel que soit per_player — voir
+    ensure_global_vars_schema.py) si son nom n'existe pas déjà ; si elle
+    existe déjà, ne touche à rien et renvoie simplement son id existant,
+    pour que "créer" depuis le sélecteur de condition de visibilité (voir
+    screen_edit.html) reste sans risque même en cas de double clic/
+    soumission.
+
+    per_player (réglé une fois, à la création, coché par défaut) :
+    True = chaque joueur aura sa propre valeur (une ligne créée
+    paresseusement à sa première écriture, voir
+    update_global_variable_value.py) ; False = valeur unique partagée par
+    tous les joueurs (ex. un compteur de visiteurs global)."""
     name = (name or "").strip()
     if not name:
         return None
     default_value = coerce_structured_value(var_type, default_value)
     ensure_global_vars_schema(slug)
     conn = connect(slug)
-    existing = conn.execute("SELECT id FROM _global_variables WHERE name = ?", (name,)).fetchone()
+    existing = conn.execute(
+        "SELECT id FROM _global_variables WHERE name = ? AND player_id = ?", (name, PLAYER_SHARED)
+    ).fetchone()
     if existing:
         conn.close()
         return existing["id"]
     conn.execute(
-        "INSERT INTO _global_variables (name, type, value) VALUES (?, ?, ?)",
-        (name, var_type, default_value),
+        "INSERT INTO _global_variables (name, type, value, player_id, per_player) VALUES (?, ?, ?, ?, ?)",
+        (name, var_type, default_value, PLAYER_SHARED, 1 if per_player else 0),
     )
     new_id = conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"]
     conn.commit()

db/global_vars/delete_global_variable.py

@@ -3,6 +3,9 @@ from .ensure_global_vars_schema import ensure_global_vars_schema
 
 
 def delete_global_variable(slug, name):
+    """Supprime TOUTES les lignes de ce nom, pas seulement la ligne modèle
+    PLAYER_SHARED — une variable per_player peut avoir une ligne par joueur
+    ayant déjà écrit dessus (voir update_global_variable_value.py)."""
     ensure_global_vars_schema(slug)
     conn = connect(slug)
     conn.execute("DELETE FROM _global_variables WHERE name = ?", (name,))

db/global_vars/delete_global_variable_by_id.py

@@ -6,9 +6,15 @@ def delete_global_variable_by_id(slug, var_id):
     """Version par id de delete_global_variable — utilisée par la page de
     gestion des variables (game_variables.html), où chaque ligne connaît son
     id technique mais pas nécessairement un nom encore garanti unique côté
-    formulaire d'URL (espaces, accents...)."""
+    formulaire d'URL (espaces, accents...). Supprime aussi TOUTES les
+    lignes des autres joueurs pour ce même nom (une variable per_player en
+    a une par joueur qui a déjà écrit dessus, voir
+    update_global_variable_value.py) — sans ça, supprimer une variable
+    depuis le tableau de bord laisserait des lignes orphelines."""
     ensure_global_vars_schema(slug)
     conn = connect(slug)
-    conn.execute("DELETE FROM _global_variables WHERE id = ?", (var_id,))
+    row = conn.execute("SELECT name FROM _global_variables WHERE id = ?", (var_id,)).fetchone()
+    if row:
+        conn.execute("DELETE FROM _global_variables WHERE name = ?", (row["name"],))
     conn.commit()
     conn.close()

db/global_vars/ensure_global_vars_schema.py

@@ -1,23 +1,59 @@
 from ..connection import connect
 
+PLAYER_SHARED = "__shared__"
+
 
 def ensure_global_vars_schema(slug):
     """Migration légère (même principe que ensure_field_bounds_schema.py) :
-    crée _global_variables si absente — aucune migration manuelle nécessaire
-    pour les jeux créés avant cette fonctionnalité, la prochaine lecture
-    suffit. Une variable globale vit pour TOUT le jeu (pas par écran, pas
-    par ligne) : "nom" est donc UNIQUE, une seule valeur actuelle par nom."""
+    crée _global_variables si absente. Depuis l'état par joueur (Phase 1),
+    une variable a une ligne "modèle" créée par le créateur du jeu
+    (player_id=PLAYER_SHARED, voir PLAYER_SHARED ci-dessus), qui porte son
+    réglage per_player (1 = chaque joueur a sa propre valeur, une ligne
+    créée paresseusement à sa première écriture — voir
+    update_global_variable_value.py ; 0 = valeur unique partagée par tous
+    les joueurs, toujours la ligne PLAYER_SHARED elle-même) — "nom" n'est
+    donc plus unique à lui seul, seulement (nom, player_id)."""
     conn = connect(slug)
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS _global_variables (
             id INTEGER PRIMARY KEY AUTOINCREMENT,
-            name TEXT NOT NULL UNIQUE,
+            name TEXT NOT NULL,
             type TEXT NOT NULL DEFAULT 'texte',
             value TEXT,
-            created_at TEXT DEFAULT CURRENT_TIMESTAMP
+            player_id TEXT NOT NULL DEFAULT '__shared__',
+            per_player INTEGER NOT NULL DEFAULT 1,
+            created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+            UNIQUE(name, player_id)
         );
         """
     )
+    # SQLite ne permet pas de modifier une contrainte UNIQUE existante via
+    # ALTER TABLE ADD COLUMN — un jeu créé avant la Phase 1 a déjà cette
+    # table, sous l'ancien schéma (UNIQUE(name) seul, sans player_id/
+    # per_player) : reconstruction complète si détecté, chaque variable
+    # existante devenant la ligne "modèle" PLAYER_SHARED, per_player=1 par
+    # défaut (comportement le plus proche de l'ancien : une seule valeur
+    # jusqu'ici, qui devient réellement par-joueur dès la Phase 1 en place).
+    cols = {r["name"] for r in conn.execute("PRAGMA table_info(_global_variables)").fetchall()}
+    if "player_id" not in cols:
+        conn.executescript(
+            """
+            ALTER TABLE _global_variables RENAME TO _global_variables_old;
+            CREATE TABLE _global_variables (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                name TEXT NOT NULL,
+                type TEXT NOT NULL DEFAULT 'texte',
+                value TEXT,
+                player_id TEXT NOT NULL DEFAULT '__shared__',
+                per_player INTEGER NOT NULL DEFAULT 1,
+                created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+                UNIQUE(name, player_id)
+            );
+            INSERT INTO _global_variables (id, name, type, value, created_at)
+                SELECT id, name, type, value, created_at FROM _global_variables_old;
+            DROP TABLE _global_variables_old;
+            """
+        )
     conn.commit()
     conn.close()

db/global_vars/get_global_variable.py

@@ -1,16 +1,24 @@
 from ..connection import connect
-from .ensure_global_vars_schema import ensure_global_vars_schema
+from .ensure_global_vars_schema import ensure_global_vars_schema, PLAYER_SHARED
+from .resolve_player_key import resolve_player_key
 
 
-def get_global_variable(slug, name):
-    """Par NOM (unique), pas par id — c'est comme ça qu'une variable est
-    référencée partout ailleurs (condition de visibilité, action "Modifier
-    une variable"), jamais par un id technique que l'utilisateur ne voit
-    pas."""
+def get_global_variable(slug, name, player_id=PLAYER_SHARED):
+    """Par NOM (pas par id — c'est comme ça qu'une variable est référencée
+    partout ailleurs, condition de visibilité, action "Modifier une
+    variable") et par joueur (voir resolve_player_key.py) : une variable
+    per_player renvoie la ligne propre à `player_id`, ou à défaut (ce
+    joueur n'a encore rien écrit) la ligne modèle PLAYER_SHARED, qui porte
+    la valeur par défaut définie à la création."""
     if not name:
         return None
     ensure_global_vars_schema(slug)
     conn = connect(slug)
-    row = conn.execute("SELECT * FROM _global_variables WHERE name = ?", (name,)).fetchone()
+    key = resolve_player_key(conn, name, player_id)
+    row = conn.execute("SELECT * FROM _global_variables WHERE name = ? AND player_id = ?", (name, key)).fetchone()
+    if not row and key != PLAYER_SHARED:
+        row = conn.execute(
+            "SELECT * FROM _global_variables WHERE name = ? AND player_id = ?", (name, PLAYER_SHARED)
+        ).fetchone()
     conn.close()
     return dict(row) if row else None

db/global_vars/list_global_variables.py

@@ -1,10 +1,17 @@
 from ..connection import connect
-from .ensure_global_vars_schema import ensure_global_vars_schema
+from .ensure_global_vars_schema import ensure_global_vars_schema, PLAYER_SHARED
 
 
 def list_global_variables(slug):
+    """Toujours les lignes MODÈLES (PLAYER_SHARED) — c'est la liste des
+    variables telle que le créateur les a définies dans le tableau de
+    bord, jamais influencée par le nombre de joueurs ayant déjà leur
+    propre valeur pour une variable per_player (voir
+    ensure_global_vars_schema.py)."""
     ensure_global_vars_schema(slug)
     conn = connect(slug)
-    rows = conn.execute("SELECT * FROM _global_variables ORDER BY name").fetchall()
+    rows = conn.execute(
+        "SELECT * FROM _global_variables WHERE player_id = ? ORDER BY name", (PLAYER_SHARED,)
+    ).fetchall()
     conn.close()
     return [dict(r) for r in rows]

db/global_vars/list_global_variables_for_player.py

@@ -0,0 +1,18 @@
+from .ensure_global_vars_schema import PLAYER_SHARED
+from .list_global_variables import list_global_variables
+from .get_global_variable import get_global_variable
+
+
+def list_global_variables_for_player(slug, player_id=PLAYER_SHARED):
+    """Valeur EFFECTIVE de chaque variable pour ce joueur (voir
+    get_global_variable.py : la ligne propre à ce joueur si elle existe
+    déjà, sinon la valeur par défaut de la ligne modèle) — à la différence
+    de list_global_variables() (toujours les lignes modèles, pour le
+    tableau de bord), c'est cette version qu'il faut exposer au runtime
+    jouable (full_game_payload.py), pour qu'une condition évaluée côté
+    client reflète bien l'état RÉEL de CE joueur."""
+    result = []
+    for template in list_global_variables(slug):
+        value = get_global_variable(slug, template["name"], player_id)
+        result.append(value if value else template)
+    return result

db/global_vars/resolve_player_key.py

@@ -0,0 +1,17 @@
+from .ensure_global_vars_schema import PLAYER_SHARED
+
+
+def resolve_player_key(conn, name, player_id):
+    """Détermine le player_id à utiliser RÉELLEMENT pour lire/écrire cette
+    variable : celui du joueur (variable per_player=1, le cas par défaut),
+    ou toujours PLAYER_SHARED (variable explicitement partagée entre tous
+    les joueurs, per_player=0) — décidé par le réglage de la ligne
+    "modèle" créée par le créateur du jeu (voir create_global_variable.py).
+    Une variable encore inconnue (aucune ligne modèle) est traitée comme
+    per_player=1 par défaut."""
+    row = conn.execute(
+        "SELECT per_player FROM _global_variables WHERE name = ? AND player_id = ?",
+        (name, PLAYER_SHARED),
+    ).fetchone()
+    per_player = row["per_player"] if row else 1
+    return player_id if per_player else PLAYER_SHARED

db/global_vars/update_global_variable_value.py

@@ -1,18 +1,38 @@
 from ..connection import connect
-from .ensure_global_vars_schema import ensure_global_vars_schema
-from .get_global_variable import get_global_variable
+from .ensure_global_vars_schema import ensure_global_vars_schema, PLAYER_SHARED
+from .resolve_player_key import resolve_player_key
 
 
-def update_global_variable_value(slug, name, new_value):
+def update_global_variable_value(slug, name, new_value, player_id=PLAYER_SHARED):
     """Écrit une nouvelle valeur BRUTE (déjà calculée par l'appelant) sur la
     variable — utilisé aussi bien par l'action "Modifier une variable" (voir
-    screens/global_vars/apply_variable_action.py) que par une éventuelle
-    modification directe (page de gestion des variables)."""
-    if not get_global_variable(slug, name):
-        return False
+    screens/data_actions/apply_variable_action.py) que par une éventuelle
+    modification directe (page de gestion des variables).
+
+    Pour une variable per_player, la PREMIÈRE écriture de ce joueur crée sa
+    propre ligne (copiée depuis la ligne modèle PLAYER_SHARED — même type/
+    per_player) ; les écritures suivantes mettent juste à jour cette ligne.
+    Une variable per_player=0 écrit toujours la ligne PLAYER_SHARED elle-même
+    (voir resolve_player_key.py)."""
     ensure_global_vars_schema(slug)
     conn = connect(slug)
-    conn.execute("UPDATE _global_variables SET value = ? WHERE name = ?", (str(new_value), name))
+    key = resolve_player_key(conn, name, player_id)
+    existing = conn.execute(
+        "SELECT id FROM _global_variables WHERE name = ? AND player_id = ?", (name, key)
+    ).fetchone()
+    if existing:
+        conn.execute("UPDATE _global_variables SET value = ? WHERE id = ?", (str(new_value), existing["id"]))
+    else:
+        template = conn.execute(
+            "SELECT type, per_player FROM _global_variables WHERE name = ? AND player_id = ?", (name, PLAYER_SHARED)
+        ).fetchone()
+        if not template:
+            conn.close()
+            return False
+        conn.execute(
+            "INSERT INTO _global_variables (name, type, value, player_id, per_player) VALUES (?, ?, ?, ?, ?)",
+            (name, template["type"], str(new_value), key, template["per_player"]),
+        )
     conn.commit()
     conn.close()
     return True