Merge pull request 'Dev' (#17) from dev into main

Reviewed-on: #17

.env.example

@@ -1,7 +1,13 @@
-# Ce fichier ne configure PAS l'application (elle ne lit aucune variable
+# Deux usages distincts pour ce fichier, jamais mélangés :
-# d'environnement) — il configure uniquement docker-compose.prod.yml sur le
+#  - En LOCAL (poste de dev) : copier en ".env" à la racine du dépôt et
-# serveur de production. Copier en ".env" à côté de docker-compose.prod.yml
+#    renseigner les clés IA ci-dessous — core/flask_app.py les charge lui-
-# sur le serveur et adapter les valeurs ; ne jamais committer ce ".env".
+#    même (python-dotenv), rien d'autre à faire. Jamais committer ce ".env"
+#    (déjà dans .gitignore).
+#  - En PRODUCTION : ce fichier configure docker-compose.prod.yml (image,
+#    port) — copier en ".env" à côté de docker-compose.prod.yml sur le
+#    serveur. L'app elle-même n'y lit AUCUN fichier .env en production
+#    (aucun n'y est déployé) : les variables y sont posées directement sur
+#    l'hôte/le conteneur, docker-compose.prod.yml les lui transmettant.
 
 # Adresse complète de l'image dans le registre Gitea, ex :
 # gitea.exemple.com/mon-compte/forge-engine
@@ -23,3 +29,25 @@ SMTP_PORT=587
 SMTP_USER=
 SMTP_PASSWORD=
 SMTP_FROM=
+
+# Onglet "IA" (voir ai/client.py) — clé du compte Anthropic Console
+# (console.anthropic.com), PAS l'abonnement claude.ai Entreprise (deux
+# systèmes de facturation séparés). Laisser vide désactive le chat IA
+# (message d'erreur clair affiché au créateur, jamais une 500).
+ANTHROPIC_API_KEY=
+
+# Génération d'images (voir ai/scenario_client.py) — compte Scenario
+# (scenario.com), clé + secret (authentification Basic), et l'id du
+# modèle entraîné sur le style graphique unique de Forge Engine (voir
+# l'étude préalable : un seul style pour tout le moteur, pas par projet).
+# Laisser vide désactive juste la génération d'images (le reste du chat
+# IA continue de fonctionner).
+SCENARIO_API_KEY=
+SCENARIO_API_SECRET=
+SCENARIO_MODEL_ID=
+
+# Debogueur Werkzeug (traceback interactif + auto-reload) pour le
+# developpement local uniquement — ne jamais activer ailleurs qu'en local
+# (app.py, python app.py direct ; sans effet en production, qui utilise
+# gunicorn). Laisser vide/0 = desactive par defaut.
+FORGE_DEBUG=0

.eslintrc.json

@@ -0,0 +1,191 @@
+{
+  "root": true,
+  "env": {
+    "browser": true,
+    "es2021": true
+  },
+  "extends": ["airbnb-base"],
+  "plugins": ["unused-imports"],
+  "parserOptions": {
+    "ecmaVersion": 2021,
+    "sourceType": "script"
+  },
+  "rules": {
+    "max-len": ["error", 120, 2, {
+      "ignoreUrls": true,
+      "ignoreComments": false,
+      "ignoreRegExpLiterals": true,
+      "ignoreStrings": true,
+      "ignoreTemplateLiterals": true
+    }],
+    "unused-imports/no-unused-imports": "error",
+    "unused-imports/no-unused-vars": [
+      "error",
+      {
+        "vars": "all",
+        "args": "after-used",
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^(_|addClauseRow|addPersonnageCommandExtraRow|applyCameraSize|bindClicks|bindHeldKeyTriggers|bindHoverTexts|bindHoverTriggers|bindKeyboardTriggers|bindPropsAutosave|closeLeftPanel|closePropsPanel|collisionWizardAssetNext|collisionWizardAttendreNext|collisionWizardChainDone|collisionWizardChooseAction|collisionWizardChooseBranch|collisionWizardChooseTrigger|collisionWizardConditionNext|collisionWizardIndicationNext|collisionWizardObjectTargetChosen|collisionWizardValeurChosen|collisionWizardVariableNext|collisionWizardVideoModeChosen|confirmDeleteElement|createGlobalVariable|deleteGlobalVariable|deleteSceneObject|deleteUserAsset|forgeShowTab|iaChatDeleteConversation|iaChatInputKeydown|iaChatSelectConversation|initSceneBuilderPanel|injectCustomKeyframes|onCanvasDragOver|onCanvasDrop|onCollisionBoxMouseDown|onCollisionBoxResizeMouseDown|onElementMouseDown|onFilterValueFieldChange|onFilterValueModeChange|onFilterValueObjChange|onFilterValueVarChange|onGalleryTileDragStart|onResizeMouseDown|onSceneObjectMouseDown|onSceneObjectResizeMouseDown|openAddTriggerModal|openLeftPanel|openPropsPanel|openScreenAddTriggerModal|openScreenTriggerWizard|openTriggerWizard|reclassifyUserAsset|refreshRuntimeData|restartPersonnageIdlePreview|restoreFloatPanelState|runScreenHeldKeyTriggers|runScreenShowTriggers|runScreenTimerTriggers|saveDialogueBoxStyle|saveGlobalVariable|saveSceneObjectName|saveSceneObjectRole|screenIndexById|screenTriggerAppendLeaf|screenTriggerDeleteAt|screenTriggerOpenAppendActionModal|selectQuizBoxDialogTemplate|selectQuizBoxPageTemplate|showScreen|swapPersonnageCharacter|swapSceneObjectCharacter|switchBuilderTab|syncAlign|toggleDashCreate|triggerAppendLeaf|triggerClickObjectCard|triggerDeleteTrigger|triggerInlineAddBubble|triggerInlineAddQuestion|triggerInlineDeleteBubble|triggerInlineSetBubbleAudio|triggerInlineSetBubbleSpeaker|triggerInlineSetQuestionChoiceCount|triggerInlineSetQuestionChoiceText|triggerInlineSetQuestionCorrectIndex|triggerInlineSetQuestionRewardAmount|triggerInlineUpdateBubbleText|triggerInlineUpdateQuestionText|triggerMoveChainAction|triggerOpenAppendActionModal|triggerRemoveChainAction|triggerSelectObject|uploadUserAsset)$"
+      }
+    ],
+    "no-unused-vars": "off",
+    "no-underscore-dangle": "off",
+    "func-names": "off",
+    "no-param-reassign": "off",
+    "no-cond-assign": ["error", "except-parens"],
+    "no-empty": ["error", { "allowEmptyCatch": true }],
+    "guard-for-in": "off",
+    "no-unused-expressions": "off",
+    "no-return-assign": "off",
+    "consistent-return": "off",
+    "no-bitwise": "off",
+    "no-plusplus": "off",
+    "no-restricted-syntax": "off",
+    "prefer-destructuring": "off",
+    "no-useless-concat": "off",
+    "no-console": "off",
+    "no-nested-ternary": "off",
+    "no-void": "off",
+    "no-continue": "off",
+    "implicit-arrow-linebreak": "off",
+    "no-use-before-define": ["error", { "functions": false, "classes": true, "variables": true }]
+  },
+  "overrides": [
+    {
+      "files": ["static/js/**/__tests__/**/*.test.js"],
+      "env": { "node": true, "browser": true },
+      "parserOptions": { "sourceType": "script" }
+    },
+    {
+      "files": ["static/js/play/**/*.js"],
+      "rules": {
+        "import/extensions": "off",
+        "global-require": "off"
+      }
+    }
+  ],
+  "globals": {
+    "COLLISION_ACTION_LABELS": "readonly",
+    "COLLISION_CHAIN_CHOICES": "readonly",
+    "COLLISION_TRIGGER_LABELS": "readonly",
+    "CONDITION_OPERATOR_LABELS_MAP": "readonly",
+    "CURRENT_SCREEN_ID": "readonly",
+    "CURRENT_SELECTED_ID": "writable",
+    "DATA_OPERATION_LABELS_MAP": "readonly",
+    "DEFINITIONS_DATA": "readonly",
+    "ELEMENT_ADD_URL": "readonly",
+    "ELEMENT_ANIMATIONS_MAP": "readonly",
+    "ELEMENT_VISIBILITY_LABELS_MAP": "readonly",
+    "FORGE_PLAY_URLS": "readonly",
+    "GAME_SLUG": "readonly",
+    "GLOBAL_VARIABLE_NAMES": "readonly",
+    "SCENE_HEIGHT": "readonly",
+    "SCENE_OBJECT_NAMES": "writable",
+    "SCENE_OBJECT_NAMES_JSON": "readonly",
+    "SCENE_WIDTH": "readonly",
+    "SCREEN_EDIT_URL": "readonly",
+    "SCREEN_ID": "readonly",
+    "SURBRILLANCE_LABELS_MAP": "readonly",
+    "USER_ASSETS_OPTIONS": "readonly",
+    "VIDEO_MODE_LABELS_MAP": "readonly",
+    "_collisionWizard": "writable",
+    "_stopPersonnageIdlePreview": "readonly",
+    "applyObjectProperty": "readonly",
+    "applyOpenRowBindings": "readonly",
+    "applySelectionHighlight": "readonly",
+    "bindClicks": "readonly",
+    "bindHoverTexts": "readonly",
+    "bindHoverTriggers": "readonly",
+    "bindPropsAutosave": "readonly",
+    "clampSceneObjectPosition": "readonly",
+    "closeTriggerModal": "readonly",
+    "collisionRuleThumbHtml": "readonly",
+    "collisionWizardBuildLeafAction": "readonly",
+    "compareValues": "readonly",
+    "debouncedSubmitPropsForm": "readonly",
+    "evaluateConditionClause": "readonly",
+    "evaluateConditionNode": "readonly",
+    "forgeApplyAddRowActionOffline": "readonly",
+    "forgeApplyCtx": "readonly",
+    "forgeApplyDataActionOffline": "readonly",
+    "forgeApplyScoreActionOffline": "readonly",
+    "forgeApplyStatusActionOffline": "readonly",
+    "forgeApplyVariableActionOffline": "readonly",
+    "forgeAttrString": "readonly",
+    "forgeAutoId": "readonly",
+    "forgeCollisionRectFromBox": "readonly",
+    "forgeComputeNewValue": "readonly",
+    "forgeDecodeClauses": "readonly",
+    "forgeDialogueBoxState": "readonly",
+    "forgeEscapeHtml": "readonly",
+    "forgeFilterRepeaterRows": "readonly",
+    "forgeFilterRowsByClauses": "readonly",
+    "forgeHtmlEscape": "readonly",
+    "forgeIsElementVisibleOffline": "readonly",
+    "forgeParentFlexDirection": "readonly",
+    "forgeQuizBoxState": "readonly",
+    "forgeQuizTemplateEffects": "readonly",
+    "forgeRecomputeFullPayloadOffline": "readonly",
+    "forgeRenderCheckboxOrRadio": "readonly",
+    "forgeRenderChildren": "readonly",
+    "forgeRenderElementHtml": "readonly",
+    "forgeRenderFieldset": "readonly",
+    "forgeRenderIcone": "readonly",
+    "forgeRenderJauge": "readonly",
+    "forgeRenderOnglets": "readonly",
+    "forgeRenderOverlay": "readonly",
+    "forgeRenderPersonnage": "readonly",
+    "forgeRenderRepeater": "readonly",
+    "forgeRenderSelect": "readonly",
+    "forgeRenderTable": "readonly",
+    "forgeResolveFilterValue": "readonly",
+    "forgeResolveVariablePath": "readonly",
+    "forgeRunCollisionRuleAction": "readonly",
+    "forgeRunScreenTriggers": "readonly",
+    "forgeScorm2004NotifyQuestionAnswered": "readonly",
+    "forgeScormApi": "readonly",
+    "forgeShapesOverlap": "readonly",
+    "forgeShowDialogueBox": "readonly",
+    "forgeShowVideoOverlay": "readonly",
+    "forgeStartCollisionRuleControllers": "readonly",
+    "forgeStartPersonnageControllers": "readonly",
+    "forgeStyleString": "readonly",
+    "forgeUpdateAllScoreWidgets": "readonly",
+    "forgeVisibleAttrs": "readonly",
+    "forgeXapiNotifyDialogueCompleted": "readonly",
+    "forgeXapiNotifyQuestionAnswered": "readonly",
+    "forgeXapiNotifyScoreChanged": "readonly",
+    "forgeXapiNotifyStatusChanged": "readonly",
+    "gameData": "writable",
+    "goToSelected": "readonly",
+    "heldKeys": "readonly",
+    "initBuilderPanel": "readonly",
+    "initIaTab": "readonly",
+    "initSceneBuilderPanel": "readonly",
+    "initTriggersTab": "readonly",
+    "openPropsPanel": "readonly",
+    "openScreenTriggerWizard": "readonly",
+    "openTriggerWizard": "readonly",
+    "refreshRuntimeData": "readonly",
+    "renderCollisionWizardChainStep": "readonly",
+    "resolveSpriteFrames": "readonly",
+    "restartPersonnageIdlePreview": "readonly",
+    "restoreFloatPanelState": "readonly",
+    "restoreTreeCollapsedState": "readonly",
+    "runActionNode": "readonly",
+    "runFlowFrom": "readonly",
+    "runScreenHeldKeyTriggers": "readonly",
+    "runScreenShowTriggers": "readonly",
+    "runScreenTimerTriggers": "readonly",
+    "runSpriteAnimation": "readonly",
+    "saveGeometry": "readonly",
+    "screenIndexById": "readonly",
+    "screenTriggerLoadAll": "readonly",
+    "screensData": "writable",
+    "showScreen": "readonly",
+    "startAllPersonnagePreviews": "readonly",
+    "stopAllSpriteAnimations": "readonly",
+    "submitPropsForm": "readonly",
+    "triggerLoadAll": "readonly"
+  }
+}

.gitattributes

@@ -0,0 +1,8 @@
+# Force LF partout, quel que soit le core.autocrlf de la machine locale
+# (Windows le met souvent a true par defaut) — sans ca, un `git stash`/
+# checkout (declenche par exemple par les hooks pre-commit avant de tester
+# le diff stage) reconvertit les fichiers en CRLF, ce qu'ESLint refuse
+# ensuite (regle linebreak-style: LF, voir .eslintrc.json) alors que le
+# fichier sur disque, lui, est deja en LF — decouvert en committant la
+# Phase 3 du plan qualite.
+* text=auto eol=lf

.gitea/workflows/deploy.yml

@@ -4,12 +4,25 @@ on:
   push:
     branches: [main, dev]
 
-# Le job "test" tourne sur CHAQUE push (main et dev) : jusqu'ici aucune
+# Les jobs "test-*"/"lint-*"/"sonarqube" tournent sur CHAQUE push (main et
-# étape de CI n'exécutait la suite de tests, rien n'empêchait un commit
+# dev) : jusqu'ici aucune étape de CI n'exécutait la suite de tests ni les
-# cassé d'atteindre la production (voir l'audit qualité de la Phase 0 du
+# outils qualité, rien n'empêchait un commit cassé d'atteindre la
-# plan). "build-and-push"/"deploy", eux, restent réservés à main (via le
+# production (voir l'audit qualité de la Phase 0 du plan). "build-and-
-# filtre "if" sur gitea.ref) — un push sur dev ne doit jamais redéployer
+# push"/"deploy", eux, restent réservés à main (via le filtre "if" sur
-# la prod, seulement faire tourner les tests.
+# gitea.ref) — un push sur dev ne doit jamais redéployer la prod, seulement
+# faire tourner tests/lint/sonar.
+#
+# lint-python/lint-js rejouent EXACTEMENT les hooks pre-commit locaux
+# (.pre-commit-config.yaml) mais bloquants ici dès le départ (déjà tous
+# verts en local, voir le commit "Phase 3 : hardening qualite de code") —
+# les hooks pre-commit ne protègent que la machine du committeur, jamais
+# un push direct ou une PR mergée depuis ailleurs. djlint EXCLU
+# volontairement (49 H021 "styles inline" déjà en backlog assumé, voir
+# CODE_QUALITY.md) — à ajouter ici quand ce lot sera traité. sonarqube,
+# lui, reste NON-BLOQUANT (continue-on-error) — remis en place le
+# 18/09/2026 une fois l'instance prod opérationnelle (voir CODE_QUALITY.md
+# pour l'historique du retrait temporaire), le temps que le rapport de
+# code smells soit entièrement trié.
 
 # Secrets à configurer dans Gitea (Paramètres du dépôt > Actions > Secrets) :
 #   REGISTRY_HOST   adresse du registre d'images (ex: gitea.exemple.com)
@@ -20,6 +33,8 @@ on:
 #   DEPLOY_USER     utilisateur SSH sur ce serveur
 #   DEPLOY_SSH_KEY  clé privée SSH (au format PEM) autorisée sur ce serveur
 #   DEPLOY_PATH     dossier sur le serveur où vit docker-compose.prod.yml (ex: /home/deploy/forge-engine)
+#   SONAR_TOKEN     jeton d'analyse SonarQube (Mon compte > Security > Generate Token
+#                   sur sonar.forgebase.fr) — jamais le mot de passe admin.
 #
 # Utilise directement docker/ssh/scp en ligne de commande plutôt que des
 # actions du marketplace, pour ne pas dépendre de la disponibilité de
@@ -68,17 +83,81 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Tests JS (node:test — logique pure de static/js/play/, voir le plan de modularisation)
+      - name: Tests JS (node:test — logique pure de static/js/play/, et l'assistant déclencheurs de static/js/scenes/+static/js/triggers/, voir le plan de modularisation)
         run: |
           docker build -f - -t forge-test-js:${{ gitea.sha }} . <<'DOCKERFILE'
           FROM node:20-slim
           WORKDIR /app
           COPY static/js/play/ static/js/play/
-          RUN node --test static/js/play/__tests__/*.test.js
+          COPY static/js/scenes/ static/js/scenes/
+          COPY static/js/triggers/ static/js/triggers/
+          RUN node --test static/js/play/__tests__/*.test.js static/js/play/offline/__tests__/*.test.js static/js/scenes/__tests__/*.test.js
           DOCKERFILE
 
+  lint-python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Qualite Python (ruff/mypy/vulture/bandit/import-linter — memes commandes que .pre-commit-config.yaml)
+        run: |
+          # Meme neutralisation de .dockerignore que test-python ci-dessus :
+          # ruff/mypy typent aussi tests/ (voir le plan de typage strict),
+          # exclu par defaut de l'image de PROD.
+          mv .dockerignore .dockerignore.disabled-for-ci
+          docker build -f - -t forge-lint-python:${{ gitea.sha }} . <<'DOCKERFILE'
+          FROM python:3.13-slim
+          WORKDIR /app
+          COPY requirements.txt requirements-dev.txt ./
+          RUN pip install --no-cache-dir -r requirements-dev.txt
+          COPY . .
+          RUN ruff check .
+          RUN ruff format --check .
+          RUN mypy .
+          RUN vulture
+          RUN bandit -c pyproject.toml -r ai auth core db filters publish routes screens scripts app.py build_css.py
+          RUN lint-imports
+          DOCKERFILE
+
+  lint-js:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Qualite JS/CSS (eslint/stylelint — memes commandes que .pre-commit-config.yaml, via les scripts npm de package.json)
+        run: |
+          docker build -f - -t forge-lint-js:${{ gitea.sha }} . <<'DOCKERFILE'
+          FROM node:20-slim
+          WORKDIR /app
+          COPY package.json package-lock.json ./
+          RUN npm ci
+          COPY . .
+          RUN npm run lint:js
+          RUN npm run lint:css
+          DOCKERFILE
+
+  sonarqube:
+    runs-on: ubuntu-latest
+    # Non-bloquant pendant cette premiere periode (voir le bloc de
+    # commentaires en tete de fichier) — un echec ici n'empeche jamais
+    # build-and-push/deploy, contrairement a lint-python/lint-js.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Analyse SonarQube (rapport seul, non-bloquant)
+        run: |
+          # Meme neutralisation de .dockerignore que test-python : sonar-
+          # project.properties couvre aussi tests/ (sonar.tests).
+          mv .dockerignore .dockerignore.disabled-for-ci
+          docker build -f - -t forge-sonar:${{ gitea.sha }} . <<'DOCKERFILE'
+          FROM sonarsource/sonar-scanner-cli:latest
+          WORKDIR /usr/src
+          COPY . .
+          DOCKERFILE
+          docker run --rm forge-sonar:${{ gitea.sha }} \
+            -Dsonar.host.url=https://sonar.forgebase.fr \
+            -Dsonar.token=${{ secrets.SONAR_TOKEN }}
+
   build-and-push:
-    needs: [test-python, test-js]
+    needs: [test-python, test-js, lint-python, lint-js]
     if: gitea.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     steps:
@@ -125,8 +204,19 @@ jobs:
             cd "${{ secrets.DEPLOY_PATH }}"
             echo "REGISTRY_IMAGE=${{ secrets.REGISTRY_IMAGE }}" > .env
             echo "IMAGE_TAG=${{ gitea.sha }}" >> .env
-            docker login "${{ secrets.REGISTRY_HOST }}" -u "${{ secrets.REGISTRY_USER }}" -p "${{ secrets.REGISTRY_TOKEN }}"
+            echo "${{ secrets.REGISTRY_TOKEN }}" | docker login "${{ secrets.REGISTRY_HOST }}" -u "${{ secrets.REGISTRY_USER }}" --password-stdin
             docker compose -f docker-compose.prod.yml pull
             docker compose -f docker-compose.prod.yml up -d
             docker image prune -f
           '
+
+      - name: Nettoyage de la cle SSH
+        # if: always() - meme si les etapes precedentes ont echoue, la cle
+        # privee posee ci-dessus (~/.ssh/deploy_key) ne doit jamais rester
+        # sur le disque du job. Le runner semble deja jetable (voir
+        # "docker volume rm .../JOB-<id>-..." dans les logs des autres
+        # jobs de ce meme workflow), mais jamais verifie directement pour
+        # CE job (jamais execute sur dev, reserve a main) - ne pas se fier
+        # uniquement a une inference par analogie pour une cle privee.
+        if: always()
+        run: rm -f ~/.ssh/deploy_key

.gitignore

@@ -4,6 +4,16 @@ __pycache__/
 *.egg-info/
 .pytest_cache/
 
+# JS (voir package.json) — installe via `npm install`, jamais committé.
+node_modules/
+
+# Rapports d'outils qualité (ruff/bandit/eslint/stylelint/mypy/vulture/
+# import-linter/djlint — voir sonar-project.properties, CODE_QUALITY.md) :
+# sortie regenerée à la demande avant chaque scan Sonar, jamais figée dans
+# l'historique (un rapport committé devient vite mensonger — vécu : ceux du
+# 14 sept re-signalaient des centaines de problèmes déjà corrigés).
+reports/
+
 # Environnements virtuels
 .venv/
 venv/
@@ -18,6 +28,10 @@ regles/
 # Jeux créés par les utilisateurs (données runtime, pas du code)
 projects/
 
+# "Mes assets" — images par compte (données runtime, voir
+# auth/user_assets_dir.py, db/constants.py::USER_ASSETS_DIR)
+user_assets/
+
 # Comptes utilisateurs (base SQLite + clé de session) — données runtime,
 # jamais du code, et sensibles (mots de passe hachés, secrets 2FA).
 data/
@@ -38,6 +52,15 @@ Thumbs.db
 .vscode/
 .idea/
 
+# Journaux de diagnostic ad-hoc (redirection stdout/stderr d'un serveur
+# de dev lancé pour déboguer) — jamais du code.
+_srv_out.txt
+_srv_err.txt
+_diag_out.txt
+_diag_err.txt
+server_out.log
+server_err.log
+
 # Documents internes/business (cadrage produit...) et état local de
 # session Claude Code — jamais du code, pas destiné à l'historique partagé.
 .claude/

.pre-commit-config.yaml

@@ -0,0 +1,80 @@
+# Hooks locaux (language: system) plutot que les miroirs pre-commit
+# habituels (astral-sh/ruff-pre-commit, pre-commit/mirrors-mypy,
+# pre-commit/mirrors-eslint...) : ce projet a deja un environnement
+# Python (requirements-dev.txt) et un node_modules/ (package.json) bien
+# a lui — repartir sur un environnement ISOLE et RE-TELECHARGE par
+# pre-commit dupliquerait exactement les memes outils/versions pour rien
+# (et serait plus lent, plus fragile hors ligne). Voir CODE_QUALITY.md
+# pour l'installation prealable (`pip install -r requirements-dev.txt`
+# + `npm install`), necessaire pour que ces hooks trouvent les
+# executables.
+#
+# Chaque hook est bloquant (aucune regle desactivee "pour ne pas casser
+# le build", demande explicite) — un commit est refuse si un outil
+# trouve un probleme, jusqu'a ce que la Phase 3 du plan qualite ait
+# nettoye l'existant.
+#
+# eslint/stylelint : entry appelle `node <script.js>` directement plutot
+# que `npx eslint` ou le shim node_modules/.bin/eslint(.cmd) — ces deux
+# dernieres formes font passer pre-commit par cmd.exe pour lancer un
+# executable Windows (.cmd) ou un script a shebang POSIX (#!/bin/sh),
+# et pre-commit resout mal cmd.exe/sh depuis ce contexte (bug constate
+# sous Windows). Appeler `node` directement sur le fichier JS du package
+# evite tout intermediaire shell.
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: Ruff (lint Python)
+        entry: ruff check
+        language: system
+        types: [python]
+
+      - id: ruff-format
+        name: Ruff (formatage Python)
+        entry: ruff format --check
+        language: system
+        types: [python]
+
+      - id: mypy
+        name: Mypy (typage strict Python)
+        entry: mypy .
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: vulture
+        name: Vulture (code mort Python)
+        entry: vulture
+        language: system
+        pass_filenames: false
+
+      - id: bandit
+        name: Bandit (securite Python)
+        entry: bandit -c pyproject.toml -r ai auth core db filters publish routes screens scripts app.py build_css.py
+        language: system
+        pass_filenames: false
+
+      - id: import-linter
+        name: import-linter (contrats d'architecture Python)
+        entry: lint-imports
+        language: system
+        pass_filenames: false
+
+      - id: djlint
+        name: djLint (templates Jinja)
+        entry: djlint templates
+        language: system
+        pass_filenames: false
+
+      - id: eslint
+        name: ESLint (JS)
+        entry: node node_modules/eslint/bin/eslint.js
+        language: system
+        files: ^static/js/.*\.js$
+
+      - id: stylelint
+        name: Stylelint (CSS)
+        entry: node node_modules/stylelint/bin/stylelint.mjs
+        language: system
+        files: \.css$

.stylelintrc.json

@@ -0,0 +1,12 @@
+{
+  "extends": ["stylelint-config-standard"],
+  "ignoreFiles": [
+    "static/vendor/**/*.css",
+    "static/style.css"
+  ],
+  "rules": {
+    "selector-class-pattern": null,
+    "selector-id-pattern": null,
+    "no-descending-specificity": null
+  }
+}

CLAUDE.md

@@ -0,0 +1,62 @@
+## Stack et structure
+Bref rappel : Python/Flask/Jinja backend, JS/HTML/CSS frontend, architecture en couches (routes → services/screens → db, voir contrat import-linter dans pyproject.toml).
+
+## Règle absolue : qualité de code non négociable
+- Tout code Python doit passer mypy --strict sans erreur. Jamais de # type: ignore sans commentaire justifiant précisément pourquoi (pas de vague, une vraie raison technique).
+- Tout code doit passer Ruff, Bandit, Vulture, import-linter, ESLint, Stylelint sans nouvelle erreur avant d'être considéré terminé.
+- Avant de committer, lance systématiquement pre-commit run --all-files et corrige tout ce qui échoue — jamais de --no-verify ou de SKIP= sans me le signaler et justifier explicitement pourquoi.
+- Aucune règle de lint/typage ne doit être désactivée globalement dans un fichier de config sans ma validation explicite. Une exception ponctuelle (# noqa, # nosec, // NOSONAR, ts-ignore) doit toujours être sur la ligne concernée avec un commentaire expliquant précisément pourquoi, jamais un ignore de fichier entier ou de règle globale.
+
+## Distinguer bug réel vs faux positif
+Avant de corriger un finding d'un outil (Mypy, Bandit, Sonar, etc.), détermine s'il s'agit d'un vrai problème ou d'un faux positif dû au contexte du projet (ex. injection de fixture pytest, dispatch dynamique JS/Jinja, whitelist codée en dur). Ne corrige jamais mécaniquement sans comprendre la cause. Si un correctif change un comportement (pas juste une annotation/un style), signale-le explicitement avant de l'appliquer et explique pourquoi.
+
+## Tests unitaires — non-régression
+- Toute nouvelle fonctionnalité ou tout correctif de bug doit être accompagné d'un test qui aurait échoué avant le fix et passe après.
+- Ne jamais me dire "les tests passent" comme preuve suffisante pour un changement de sécurité ou de comportement sensible (ex. échappement de données, gestion de permissions) — écris un test ou un script de vérification dédié qui prouve concrètement le comportement attendu (voir l'exemple du fix XSS json_for_script : test avec une charge malveillante réelle, pas juste "aucune régression").
+- Ne réduis jamais la portée d'une assertion de test pour la faire passer sans discussion préalable avec moi.
+- Signale immédiatement toute fuite d'état entre tests (fixtures partagées, données non nettoyées) même si elle n'est pas dans le scope de la tâche en cours.
+
+## Code mort
+Avant de supprimer une fonction jugée "morte" par un outil (Vulture, ESLint no-unused-vars), vérifie par grep exhaustif (imports directs, dispatch dynamique par nom de chaîne, référencé depuis un template Jinja ou un script JS, appel getattr/introspection) avant de conclure qu'elle est vraiment inutilisée.
+
+## SonarQube local (développement continu)
+En plus de l'instance CI (sonar.forgebase.fr, non-bloquante), une instance SonarQube locale doit tourner via Docker pour un usage rapide pendant le développement, séparée de la CI.
+
+### Mise en place (à faire une fois si l'instance n'existe pas encore)
+Si aucune instance locale n'est déjà en place : lance une instance SonarQube Community via Docker (image officielle, avec une base PostgreSQL plutôt que la H2 embarquée par défaut — voir la mise en place déjà documentée pour sonar.forgebase.fr comme référence). Communique-moi clairement l'adresse locale (ex. http://localhost:9000) une fois lancée, et le port utilisé, pour que je puisse ouvrir le dashboard moi-même à tout moment.
+
+### Utilisation continue pendant le développement
+- Avant de considérer une tâche terminée (nouvelle fonctionnalité, gros refactor, fix de bug), lance une analyse sonar-scanner contre cette instance locale.
+- Si des erreurs ou vulnérabilités sont détectées sur du code NOUVEAU (écrit dans la session en cours) : corrige-les toi-même directement, comme pour Ruff/Mypy/Bandit — pas besoin de me demander la permission pour un vrai bug évident sur du code que tu viens d'écrire.
+- Si l'analyse détecte quelque chose sur du code existant (pas modifié dans la session en cours) : signale-le-moi, n'y touche pas sans validation, même logique que pour le rapport SonarQube de la Phase 3 (analyse d'abord, décision ensemble avant correction).
+- Distingue toujours dans ton compte-rendu : ce qui a été corrigé automatiquement (code neuf, évident) vs ce qui est signalé en attente de décision (code existant, ou correction ambiguë).
+- Donne-moi régulièrement l'adresse du dashboard local si je veux consulter moi-même le détail visuellement.
+
+## Convention vs bug de config
+Si un preset de lint (ex. airbnb-base, stylelint-config-standard) contredit une convention cohérente déjà établie dans le code (ex. camelCase CSS, var au lieu de let/const), n'impose pas de réécriture mécanique du code : propose d'adapter la config, documente pourquoi, et attends ma validation.
+
+## Discipline de communication
+- Pour tout lot de travail dépassant quelques fichiers, découpe en étapes vérifiables (diff + tests à chaque étape), jamais un correctif massif d'un coup.
+- Signale tout changement de comportement réel séparément du reste (pas noyé dans un rapport de style).
+- Si un choix a plusieurs options légitimes (garder/typer/supprimer, corriger/documenter une exception), présente les options avec leurs compromis plutôt que de trancher seul.
+
+## Documentation
+Toute règle désactivée, tout # nosec/NOSONAR, toute adaptation de config doit être répercutée dans CODE_QUALITY.md.
+
+## Organisation des fichiers (applicable à partir de maintenant, pas de refactor rétroactif)
+
+- 1 fichier = 1 fonction publique. Les fonctions privées d'appui (préfixées _) utilisées uniquement par cette fonction restent dans le même fichier.
+- 1 dossier = 1 responsabilité claire.
+- Chaque dossier a un fichier barrel (__init__.py) qui importe/exporte toutes les fonctions publiques du dossier (pattern déjà en place dans db/__init__.py et screens/__init__.py — garde __all__ explicite à jour à chaque ajout).
+- Chaque dossier a un fichier .md qui documente chaque fonction publique qu'il contient : signature, rôle, paramètres, valeur de retour, exceptions possibles. Mets-le à jour à chaque fonction ajoutée/modifiée/supprimée.
+
+### Exceptions à cette règle (ne pas séparer)
+- Le pattern sanitize_X / resolve_X (validation + résolution avec repli sur valeur par défaut) : ces deux fonctions restent dans le même fichier quand resolve_X appelle directement sanitize_X et qu'elles partagent des constantes de configuration. Ce sont deux étapes d'un même contrat, pas deux responsabilités séparées.
+- Un groupe de fonctions fortement couplées par une table de dispatch centrale et des constantes de module partagées (ex. collision_rules.py) peut rester dans un seul fichier si les séparer forcerait soit une duplication de constantes, soit un fichier de constantes partagé importé par tous les autres pour un gain de lisibilité douteux. En cas de doute, demande avant de trancher plutôt que d'appliquer la règle mécaniquement.
+- Des handlers Flask co-localisés par convention d'URL (ex. plusieurs routes d'un même sous-domaine fonctionnel) qui n'ont aucun appel ni état partagé entre eux ne sont PAS un cas d'exception — ceux-là doivent être séparés, un fichier par route/fonction.
+
+### Avant de créer une nouvelle fonction
+Vérifie si elle appartient à un fichier existant à forte cohésion (voir exceptions ci-dessus) ou si elle mérite son propre fichier. En cas de doute sur la classification, demande plutôt que de deviner.
+
+### Constantes partagées entre plusieurs fonctions d'un même dossier
+Si plusieurs fonctions séparées (dans des fichiers différents) ont besoin des mêmes constantes, crée un fichier constants.py dans le dossier concerné plutôt que de dupliquer les valeurs — ne duplique jamais une constante de configuration entre fichiers.

CODE_QUALITY.md

@@ -0,0 +1,189 @@
+# Qualité de code — Forge Engine
+
+Référence de fonctionnement du dispositif qualité mis en place (Phases 1
+à 4). Pour le compte-rendu chronologique de ce qui a été fait/trouvé/
+décidé pendant la mise en place, voir `docs/SESSION_RECAP.md` — ce
+fichier-ci documente uniquement **l'état actuel** et **comment
+l'utiliser au quotidien**.
+
+Règle de base, non négociable : **aucune règle de lint/typage n'est
+désactivée globalement dans un fichier de config sans validation
+explicite.** Une exception ponctuelle est toujours une ligne de code
+(`# noqa`, `# nosec`, `// NOSONAR`) avec une raison précise, jamais un
+ignore de fichier entier ou de règle globale — voir section 4.
+
+## 1. Vue d'ensemble
+
+| Outil | Vérifie | Portée | Obligatoire / Avertissement |
+|---|---|---|---|
+| **Ruff** (lint) | Erreurs Python, imports inutilisés, style | `*.py` | Obligatoire (bloquant CI + pre-commit) |
+| **Ruff** (format) | Formatage Python | `*.py` | Obligatoire |
+| **Mypy** `--strict` | Typage statique Python | `*.py` | Obligatoire |
+| **Bandit** | Sécurité Python (injections, primitives faibles) | `ai`, `auth`, `core`, `db`, `filters`, `publish`, `routes`, `screens`, `scripts`, `app.py`, `build_css.py` | Obligatoire |
+| **Vulture** | Code mort Python | mêmes dossiers que Bandit | Obligatoire |
+| **import-linter** | Contrat de couches applicatives | tout le code Python | Obligatoire |
+| **ESLint** (`airbnb-base`) | Lint JavaScript | `static/js/**/*.js` | Obligatoire |
+| **Stylelint** (`stylelint-config-standard`) | Lint CSS | `styles/**/*.css` | Obligatoire |
+| **djLint** | Lint des templates Jinja | `templates/**/*.html` | **Avertissement** — H021 (styles inline) en backlog assumé, voir section 6 |
+| **SonarQube** (local + CI) | Bugs/vulnérabilités/code smells/hotspots agrégés | tout le dépôt | **Avertissement** — non-bloquant en CI pour l'instant, voir section 3 |
+
+## 2. Configuration de chaque outil
+
+### Ruff (`pyproject.toml`, `[tool.ruff]`)
+- `line-length = 120`, `target-version = "py313"`.
+- Règles activées : `F` (pyflakes), `E`/`W` (pycodestyle), `B` (bugbear), `C4` (comprehensions), `SIM` (simplification), `S` (bandit-équivalent Ruff), `I` (imports).
+- `per-file-ignores` : `S101`/`S106` désactivées pour `tests/` uniquement (assert et mots de passe en dur sont la norme dans les tests, jamais en dehors).
+- Exclusions : `projects/`, `user_assets/`, `data/`, `Bug/`, `regles/` (données runtime, jamais du code).
+
+### Mypy (`pyproject.toml`, `[tool.mypy]`)
+- `strict = true`, `python_version = "3.13"`.
+- `explicit_package_bases = true` + `mypy_path = "."` : nécessaire car `tests/` n'a pas de `__init__.py` — sans ça mypy refuse de démarrer ("Source file found twice under different module names"). **Ce n'est pas un assouplissement de `strict`**, juste la résolution des chemins de module.
+- Mêmes exclusions que Ruff.
+
+### Bandit (`pyproject.toml`, `[tool.bandit]`)
+- `exclude_dirs` : `projects`, `user_assets`, `data`, `Bug`, `regles`, `tests` (les tests contiennent des mots de passe/tokens de test en dur, jamais un vrai risque).
+- Portée explicite (`-r ai auth core db filters publish routes screens scripts app.py build_css.py`) plutôt que tout le dépôt.
+
+### Vulture (`pyproject.toml`, `[tool.vulture]`)
+- `min_confidence = 80`, `paths` = mêmes dossiers que Bandit + `vulture_whitelist.py`.
+- `exclude = ["*/tests/*"]`.
+- Faux positifs structurels (routes Flask enregistrées par décorateur, hooks appelés par convention de nom) : whitelist dédiée dans `vulture_whitelist.py`, **jamais** un `min_confidence` abaissé globalement.
+
+### import-linter (`pyproject.toml`, `[tool.importlinter]`)
+- Un seul contrat de type `layers`, du haut vers le bas : `routes` → `ai | publish | core` → `screens` → `auth | filters` → `db`.
+- Une couche ne peut importer qu'une couche strictement en dessous d'elle, jamais au-dessus, jamais une couche sœur du même niveau.
+- `app.py` (point d'entrée, pas un paquet) reste hors contrat — c'est lui qui importe `routes`/`core`, jamais l'inverse.
+
+### ESLint (`.eslintrc.json`)
+- Base `airbnb-base` + plugins `unused-imports`, `unicorn`.
+- `max-len` porté à 120 (aligné sur Ruff) au lieu du 80 par défaut d'Airbnb.
+- Plusieurs règles Airbnb désactivées **après vérification individuelle que le code existant les respecte déjà différemment** (voir section 5 pour le détail et le raisonnement de chacune) : `no-param-reassign`, `no-use-before-define` (assoupli pour les fonctions, gardé strict pour variables/classes), `func-names`, `no-underscore-dangle`, `no-console`, `no-plusplus`, `no-continue`, `no-bitwise`, `guard-for-in`, `no-restricted-syntax`, `prefer-destructuring`, `consistent-return`, `no-return-assign`, `no-nested-ternary`, `no-void`, `implicit-arrow-linebreak`, `no-unused-expressions`, `no-useless-concat`.
+- `unused-imports/no-unused-vars` avec une liste blanche (`varsIgnorePattern`) d'environ 95 noms : fonctions invoquées uniquement depuis des attributs `onclick`/`onchange` inline dans les templates Jinja, invisibles pour l'analyse statique d'ESLint.
+- Bloc `globals` documentant les variables cross-fichiers volontaires (ex. `gameData`, `screensData` — voir section 5).
+- **`eslint-plugin-unicorn`** (version `55.0.0` épinglée — la dernière exige ESLint ≥10, incompatible avec notre `^8.57.1`) : activé avec **UNIQUEMENT 9 règles explicitement listées**, jamais sa config `recommended` complète (qui en contient des dizaines d'autres, jamais évaluées pour ce projet — décision délibérée pour ne pas introduire un nouveau volume de règles non passées en revue). Choisi pour nettoyer le lot "modernisation JS" du rapport SonarQube (voir `docs/JS_MODERNIZATION_PLAN.md`) : `eslint-plugin-sonarjs` (l'équivalent officiel SonarSource) ne couvrait qu'une seule des règles visées. Les 9 règles activées, chacune avec un fixer `--fix` vérifié :
+  - `unicorn/prefer-number-properties` — `parseFloat`/`parseInt`/`isNaN`/`isFinite` → `Number.*`
+  - `unicorn/prefer-string-replace-all` — `.replace(/x/g, ...)` → `.replaceAll(...)`
+  - `unicorn/prefer-dom-node-dataset` — `getAttribute('data-x')` → `.dataset.x`
+  - `unicorn/prefer-includes` — `.indexOf(x) !== -1` → `.includes(x)`
+  - `unicorn/prefer-string-starts-ends-with` — comparaison manuelle de sous-chaîne → `.startsWith()`/`.endsWith()`
+  - `unicorn/prefer-modern-math-apis` — expression mathématique manuelle → `Math.hypot()` etc.
+  - `unicorn/prefer-at` — `arr[arr.length - 1]` → `arr.at(-1)`
+  - `unicorn/no-useless-fallback-in-spread` — `{...(x || {})}` → `{...x}`
+  - `unicorn/no-for-loop` — boucle `for` classique sur un itérable → `for...of`
+
+### Stylelint (`.stylelintrc.json`)
+- Base `stylelint-config-standard`.
+- `selector-class-pattern`/`selector-id-pattern` désactivées : le projet utilise du camelCase pour ses classes/id CSS depuis le début (`.canvasElement`, `#scormProgress`...) — imposer le kebab-case du preset aurait demandé de renommer des milliers de sélecteurs et leurs usages JS/HTML pour un gain nul.
+- `no-descending-specificity` désactivée : le CSS existant est organisé par composant/fonctionnalité, pas par ordre strict de spécificité.
+- `ignoreFiles` : `static/vendor/**`, `static/style.css` (bundle généré, contient du Bulma vendored).
+
+### djLint (`pyproject.toml`, `[tool.djlint]`)
+- `profile = "jinja"`, `max_line_length = 160`, `indent = 2`.
+- H021 (styles inline) : **backlog assumé, pas une exception corrigée** — voir section 6, ne pas confondre avec les vraies exceptions de la section 5.
+
+### SonarQube
+- **CI (`sonar.forgebase.fr`)** : job `sonarqube` (`.gitea/workflows/deploy.yml`), scan à chaque push, **non-bloquant** (`continue-on-error: true`) le temps que le rapport soit entièrement trié. Retiré le 18/09/2026 (voir historique ci-dessous), remis en place le 18/09/2026 une fois l'instance prod confirmée opérationnelle.
+- **Service prod** (`docker-compose.prod.yml`) : reste retiré côté dépôt pour l'instant — l'instance prod opérationnelle n'est pas (encore) pilotée par ce fichier de ce côté-ci ; à réintégrer explicitement si besoin.
+- **Historique du retrait temporaire (16-18/09/2026)** : l'accès au dashboard (local WSL2 et prod derrière Caddy) était resté bloqué par des soucis d'infrastructure réseau (redirection de port WSL2/pare-feu Hyper-V côté local, réseau Docker partagé avec Caddy pas encore en place côté prod à ce moment) sans lien avec le code du moteur. Le lot "modernisation JS" (voir `docs/JS_MODERNIZATION_PLAN.md`) s'était arrêté après le lot 3 (`S2486`) pour cette même raison — les lots 4+ dépendent de scores Sonar exacts (complexité cognitive notamment) qu'aucun proxy fiable ne remplace parfaitement (le SonarLint de l'IDE a servi de solution de contournement fonctionnelle en attendant, voir lots 4 en cours directement sur les fichiers ouverts dans l'éditeur).
+
+## 3. Lancer les checks en local
+
+```bash
+# Un outil a la fois (memes commandes que .pre-commit-config.yaml)
+ruff check .
+ruff format --check .
+mypy .
+vulture
+bandit -c pyproject.toml -r ai auth core db filters publish routes screens scripts app.py build_css.py
+lint-imports
+djlint templates
+npx eslint "static/js/**/*.js"
+npx stylelint "styles/**/*.css"
+
+# Tout d'un coup (ce que fait un commit)
+pre-commit run --all-files
+
+# Suite de tests
+python -m pytest tests/ -q
+node --test static/js/play/__tests__/*.test.js static/js/play/offline/__tests__/*.test.js static/js/scenes/__tests__/*.test.js
+```
+
+SonarQube : voir section 2, sous-section "SonarQube" — CI restaurée (non-bloquante), instance locale toujours bloquée (voir historique dans cette même sous-section).
+
+## 4. Procédure de justification d'une exception
+
+1. **Jamais de correction mécanique sans comprendre la cause.** Avant de corriger un finding, déterminer s'il s'agit d'un vrai problème ou d'un faux positif dû au contexte du projet (fixture pytest, dispatch dynamique JS/Jinja, whitelist codée en dur, architecture volontaire).
+2. **Une exception ponctuelle, jamais globale.** Le commentaire de suppression va **sur la ligne exacte** signalée par l'outil — pas la ligne au-dessus, pas la ligne en dessous (piège vécu à plusieurs reprises cette session : un commentaire mal placé ne supprime rien du tout, silencieusement).
+3. **La raison est précise, jamais vague.** "Faux positif" seul ne suffit pas — expliquer *pourquoi* (ex. "table_name vient de slugify()+prefixe obj_, jamais d'une entrée brute").
+4. **Format attendu par outil** (vérifié empiriquement cette session, chaque outil a ses propres exigences de position du mot-clé) :
+   - Bandit : `# nosec <CODE>` — le mot `nosec` doit être immédiatement précédé d'un `#` sur la ligne.
+   - Ruff : `# noqa: <CODE>` — le mot `noqa` doit être immédiatement précédé d'un `#` sur la ligne. **Bandit et Ruff peuvent coexister sur une même ligne physique** en utilisant deux `#` distincts (`# nosec B101  # noqa: S101 - raison`) — c'est structurel, pas un choix de style : chaque outil cherche son propre mot-clé juste après un `#`, et aucun format à un seul `#` ne peut satisfaire les deux à la fois (testé empiriquement).
+   - SonarQube (Python) : `# NOSONAR <règle> - raison`, sur la ligne exacte.
+   - SonarQube (JS) : `// NOSONAR <règle> - raison`, sur la ligne exacte.
+   - SonarQube (templates Jinja/HTML, règle `Web:*`) : **aucune syntaxe trouvée qui fonctionne** malgré plusieurs tentatives (commentaire Jinja `{# #}`, commentaire JS natif dans un `<script>`, bonne position de ligne) — voir la limitation documentée en section 5 (`Web:S5247`).
+5. **Toute exception validée est répercutée ici** (section 5), avec la date/le contexte. Une exception non documentée ici n'est pas considérée comme validée.
+6. **Qui valide** : aucune exception n'est appliquée sans validation explicite de l'utilisateur — présenter le choix avec ses compromis, jamais trancher seul quand plusieurs options légitimes existent.
+
+## 5. Exceptions et faux positifs documentés
+
+| Site(s) | Outil / règle | Raison | Contexte |
+|---|---|---|---|
+| `core/flask_app.py:22` | `python:S4502` (Sonar) | CSRF géré par `core/csrf_guard.py` — garde maison globale (`@app.before_request`), testée dans `test_csrf.py`, jamais Flask-WTF. Sonar ne reconnaît pas cette implémentation custom. | Phase 3 |
+| `screens/data_actions/compute_operation.py` (×2), `static/js/play/offline/compute-operation.js` (×2), `static/js/scenes/collision-rules-editor.js` (×2), `static/js/triggers/trigger-editor.js` | `B311`/`S311`/`python:S2245`/`javascript:S2245` | Tirage aléatoire de jeu (dé, id local d'UI) — jamais un usage cryptographique. | Phase 3 |
+| `static/js/play/offline/xapi-client.js` (18 sites) + `static/js/play/offline/__tests__/xapi-client.test.js` (2 sites) | `javascript:S5332` | Identifiants du vocabulaire xAPI standard ADL (`http://adlnet.gov/expapi/...`), jamais déréférencés en réseau — simples chaînes comparées/embarquées, le `http://` fait partie du texte fixé par la spec. Le vrai endpoint réseau (`config.endpoint`) est toujours saisi par le créateur, jamais un littéral de ce fichier. | Phase 3 |
+| `publish/scorm_manifest.py` | `B406` (Bandit) | Seul fichier du dépôt qui touche du XML — uniquement en génération (`xml.sax.saxutils.escape`), jamais en parsing d'XML externe. | Phase 3 |
+| `scripts/build_demo_dialogues.py:61-63` | `python:S8371` (Sonar) | Accès direct `resp.headers["Location"]` volontaire : script d'usage unique jamais exécuté en production, un `KeyError` cru est un échec au moins aussi clair qu'un `.get()` renvoyant `None`. | Phase 3 |
+| `static/js/scenes/collision-rules-editor.js` (`leafAction.then = nextLeaf`) | `javascript:S7739` | `then` est un champ métier ("action suivante de la chaîne"), jamais une promesse — vérifié qu'aucun site d'appel ne le passe à `await`/`Promise.resolve()`. Risque latent documenté plutôt que renommage (le nom est ancré dans le schéma JSON persisté en base et côté Python). | Phase 3 |
+| `db/assert_not_none.py:14` | `B101`/`S101`/`python:S7632` | Unique `assert` de narrowing de type restant dans tout le moteur, après centralisation de 11 sites dispersés (`ai/`, `routes/scenes/`, `screens/payload/`, `scripts/`) dans ce helper unique. Voir section 4 pour l'impossibilité structurelle de satisfaire Bandit+Ruff avec un seul `#`. | Session du 16/09/2026 |
+| `db/rows/delete_row.py`, `db/rows/get_row.py`, `db/rows/list_rows.py`, `screens/animations/update_animation_clip.py`, `screens/flow/add_flow_node.py`, `screens/scenes/add_scene_object.py` | `B608`/`S608`/`python:S7632` | Noms de table/colonnes construits uniquement à partir de `slugify()`/whitelists codées en dur (`_UPDATABLE_FIELDS`, `FLOW_NODE_FIELDS`), jamais d'une entrée arbitraire — valeurs toujours paramétrées (`?`). Distinct du cas `assert_not_none` ci-dessus (nature différente : construction de SQL, pas narrowing de type) — non couvert par ce refactor. | Session du 16/09/2026 |
+| `static/js/play/bindings.js:179` (`gameData = newData`) | `javascript:S2703` | Pattern volontaire de scripts globaux (pas des modules ES) : `gameData`/`screensData` sont déclarés une fois par `let` dans le `<script>` inline de `templates/play.html`, chargé avant tous les `static/js/play/*.js` (ordre séquentiel vérifié, pas de `defer`/`async`). Réassignation légitime d'une variable déjà déclarée dans un scope global partagé — déjà documenté dans `.eslintrc.json` (`"gameData": "writable"`). | Session du 16/09/2026 |
+| `static/js/play/bindings.js:180` (`screensData = gameData.screens`) | `javascript:S2703` | Même bloc, même pattern, même fichier de déclaration que `gameData` ci-dessus : `let screensData = gameData.screens;` posé dans le même `<script>` inline de `templates/play.html:145` (juste après `gameData:144`), chargé avant `bindings.js` — déjà documenté dans `.eslintrc.json` (`"screensData": "writable"`). Lot 2 "modernisation JS". | Lot 2 "modernisation JS", 16/09/2026 |
+| `static/js/scenes/scene-editor.js:214` (`CURRENT_SELECTED_ID = null`), `static/js/screen_edit/tree-panels.js:392` (`CURRENT_SELECTED_ID = selectedId \|\| null`) | `javascript:S2703` | Déclarée en **`var`** (pas `let`/`const`) dans `templates/scene_edit.html:833` (`var CURRENT_SELECTED_ID = {{ selected_id or 'null' }};`), chargé avant `tree-panels.js`/`scene-editor.js`/`trigger-editor.js`/`collision-rules-editor.js` (ordre vérifié, lignes 833/858/880/885/887/888) — un `var` de script classique attache directement à `window`, réassignable sans aucune restriction depuis n'importe quel autre `<script>` de la page (contrairement au cas `SCENE_OBJECT_NAMES` ci-dessous, qui lui était en `const`). Déjà documenté dans `.eslintrc.json` (`"CURRENT_SELECTED_ID": "writable"`). | Lot 2 "modernisation JS", 16/09/2026 |
+| `static/js/scenes/collision-rules-editor.js:78` (`let _collisionWizard = null;`) et ses réassignations dans ce fichier, **et** `static/js/triggers/trigger-editor.js:787,937` (`triggerOpenAppendActionModal`/`screenTriggerOpenAppendActionModal`, `_collisionWizard = { bodyEl: body };` sans mot-clé) | `javascript:S2703` | Même pattern de partage inter-scripts que `SCENE_OBJECT_NAMES` : `trigger-editor.js` réutilise TELLES QUELLES les étapes de l'assistant de `collision-rules-editor.js` (`renderCollisionWizardChainStep`/`collisionWizardBuildLeafAction`, qui ne lisent que `.bodyEl` — voir commentaire ligne 784-786 de `trigger-editor.js`) pour poser "+ Ajouter une action" sur un déclencheur déjà existant, plutôt que de dupliquer ces étapes. `trigger-editor.js` est chargé AVANT `collision-rules-editor.js` (`templates/scene_edit.html:887-888`), mais sans risque de TDZ : les deux réassignations de `trigger-editor.js` sont à l'intérieur de fonctions déclenchées par un clic utilisateur, jamais exécutées avant que `collision-rules-editor.js` (et son `let _collisionWizard = null;`) n'ait fini de se charger. Déjà documenté dans `.eslintrc.json` (`"_collisionWizard": "writable"`). | Lot 2 "modernisation JS", 16/09/2026 ; complété lot 4, 18/09/2026 |
+| `static/js/triggers/trigger-editor.js:28` (`let SCENE_OBJECT_NAMES = ...`) | `javascript:S2703` | **Bug réel trouvé et corrigé** (pas un faux positif comme les 4 sites ci-dessus) : était déclarée en `const`, alors que `refreshSceneObjectNames()` (`static/js/scenes/scene-editor.js:754-759`) la réassigne après un fetch — deux `<script>` classiques sur la même page partagent un même environnement lexical global, mais une liaison `const` posée dans l'un ne peut pas être réassignée depuis l'autre (`TypeError: Assignment to constant variable.`, reproduit empiriquement via `node:vm`). Symptôme : renommer un personnage puis ouvrir un dialogue de déclencheur sans recharger la page ne montrait jamais le nouveau nom dans "qui parle". Corrigé en `let`, couvert par un test de non-régression (`static/js/scenes/__tests__/collision-rules-editor.test.js`, test `refreshSceneObjectNames`) qui échoue avec `TypeError` sur l'ancien code et passe avec le nouveau. | Lot 2 "modernisation JS", 16/09/2026 |
+| 31 sites `\|safe` (`templates/scene_edit.html`, `templates/play.html`, `templates/auth/register_2fa.html`, `templates/onboarding/onboarding_new.html`, `templates/game_dashboard_simple.html`) | `Web:S5247` (Sonar) | **Faux positif confirmé sur le fond, mais non-supprimable techniquement pour l'instant.** 3 sous-groupes : (1) `rendered_html`/`qr_svg`/`description` — HTML déjà échappé côté Python (`html.escape()`) ou généré sans texte libre utilisateur ; (2) 25 sites `*_json` — `db.json_for_script()` échappe déjà `</script>` (voir Phase 3). Plusieurs syntaxes de suppression testées (commentaire Jinja `{# #}`, commentaire JS natif dans un `<script>`, bonne position de ligne) : **aucune ne fonctionne** avec l'analyseur Web de cette version de SonarQube. La résolution "Faux positif" via l'API est bloquée par le système de permissions de session. `sonar.issue.ignore.multicriteria` existe mais sans sélecteur de ligne (exclusion fichier entier uniquement) — écarté pour `scene_edit.html`/`play.html` (masquerait un futur `\|safe` réellement dangereux). Ces 31 sites restent visibles dans le rapport Sonar en l'état ; traités et compris, pas un point ouvert côté code. | Phase 3 + investigation du 16/09/2026 |
+| `static/js/play/offline/filter-repeater-rows.js:10,11`, `static/js/screen_edit/panel-init.js:254,261`, `static/js/play/offline/xapi-client.js:132` | `javascript:S8786` (ReDoS) | 3 regex distinctes (2 dupliquées dans 2 fichiers) testées empiriquement, aucune ne montre de backtracking super-linéaire réel — voir le détail complet juste en dessous du tableau (méthode reproductible). | Lot 1 "modernisation JS", 16/09/2026 |
+| `static/js/play/dialogue-box-controller.js` (`forgeShowQuizBox`, ligne du `void widget.offsetWidth;`) | `javascript:S3735` | Force une lecture de mise en page (reflow) AVANT de reposer la classe `is-active`, pour que l'animation CSS d'entrée du quiz rejoue même si la boîte était déjà active juste avant (2 questions à la suite) — idiome JS standard, `void` marque explicitement une expression dont seul l'EFFET DE LECTURE compte, jamais la valeur. 3 formes essayées dans l'ordre, chacune rejetée par une règle Sonar différente : `void widget.offsetWidth;` (S3735, "retirer void") → `widget.offsetWidth;` seule (S905, "expression sans effet — accepté par ESLint ici, `no-unused-expressions` est désactivé dans ce projet, mais pas par Sonar") → `const _ = widget.offsetWidth;` (S1481, "variable jamais lue — accepté par ESLint via `varsIgnorePattern: ^_$`, pas par Sonar"). Aucune forme ne satisfait Sonar sans en recréer une autre : `void` restauré (la plus lisible/idiomatique des 3, et la seule aussi acceptée par ESLint) et documenté ici plutôt que de continuer à faire tourner ce carrousel. | Lot 4 "modernisation JS", 18/09/2026 |
+| `static/js/screen_edit/tree-panels.js:32` (`restoreTreeCollapsedState`), `:57` (`saveFloatPanelState`), `:230` (sauvegarde état replié/déplié au clic) | `javascript:S2486` | Lecture/écriture `localStorage` purement cosmétique (éditeur seulement, jamais le jeu) : un échec (quota, storage désactivé) laisse au pire un panneau à sa position par défaut ou un nœud d'arborescence dans son état précédent — aucune donnée de jeu en jeu, aucun état perdu de façon irréversible. | Lot 3 "modernisation JS", 16/09/2026 |
+| `static/js/screen_edit/tree-panels.js:162` (`dragstart` galerie d'icônes), `:295` (`dragstart` arborescence) | `javascript:S2486` | `e.dataTransfer.setData(...)` sert uniquement à satisfaire l'exigence cross-navigateur de l'API HTML5 Drag (au moins un type MIME posé) — vérifié que les deux `drop` correspondants (lignes 177-182 et 320-344) lisent l'id glissé depuis une variable JS module (`draggedIconClass`/`treeDragElementId`), jamais `e.dataTransfer.getData(...)` : un échec de `setData` n'a donc aucun effet sur le comportement réel du glisser-déposer. | Lot 3 "modernisation JS", 16/09/2026 |
+| `static/js/play/offline/xapi-client.js:72` (`forgeXapiActor`) | `javascript:S2486` | API SCORM absente ou non conforme — attendu hors d'un vrai LMS (ex. prévisualisation) — repli déjà en place sur un acteur anonyme générique. Comportement déjà documenté par le commentaire du bloc. | Lot 3 "modernisation JS", 16/09/2026 |
+| `static/js/play/screens.js:89` (`runScreenBackgroundMusic`), `static/js/play/actions.js:333` (action "jouer_son") | `javascript:S2486` | `.play().catch(() => {})` — échec attendu du navigateur (lecture audio automatique bloquée tant qu'aucune interaction utilisateur n'a eu lieu), jamais une erreur applicative à signaler. | Lot 3 "modernisation JS", 16/09/2026 |
+| `static/js/play/screens.js:192` (`applyAnimationClip`, clip `sprite`), `static/js/play/actions.js:340` (action `jouer_animation_sprite`) | `javascript:S2486` | **Corrigé, pas seulement documenté** : `JSON.parse(custom_keyframes / data_value)` invalide laissait `spriteData` retomber silencieusement sur `{}` (aucune animation jouée) sans aucun signal — `custom_keyframes`/`data_value` sont produits par l'éditeur, jamais tapés à la main, donc un JSON invalide ici trahit presque toujours un bug côté éditeur plutôt qu'une simple erreur de saisie. Un `console.warn('configuration sprite invalide', e)` a été ajouté dans les deux `catch` : signal devtools pour le créateur en test, **comportement joueur inchangé** (l'animation reste silencieusement absente). Couvert par un nouveau test (`static/js/play/__tests__/actions.test.js`, `runActionNode — jouer_animation_sprite avec data_value JSON invalide`) qui vérifie à la fois l'absence de crash/rendu cassé ET l'appel du `console.warn`. | Lot 3 "modernisation JS", 16/09/2026 |
+| `static/js/play/offline/filter-repeater-rows.js:24` (`forgeDecodeClauses`) | `javascript:S2486` | **Corrigé, même patron que ci-dessus** : `_filtres_json` est un attribut rendu par le serveur, jamais tapé à la main — un JSON invalide y trahit presque toujours un bug côté éditeur/serveur. `console.warn('_filtres_json invalide, filtre ignoré', e)` ajouté, comportement inchangé (repli sur l'ancien format à 2 filtres fixes ou aucun filtre). Couvert par un nouveau test (`filter-repeater-rows.test.js`, `forgeDecodeClauses — _filtres_json invalide`). | Lot 4 "modernisation JS", 18/09/2026 |
+| `static/js/play/offline/filter-repeater-rows.js:59`, `:70` (`forgeResolveVariablePath`, JSON.parse + navigation `.champ`/`[index]`) | `javascript:S2486` | **Documenté, pas corrigé — nature différente du cas ci-dessus** : ici `rawValue` est la VALEUR ACTUELLE d'une variable de jeu (modifiable librement par n'importe quelle action "Modifier une variable"), pas une config interne à l'éditeur — un chemin qui ne correspond pas à sa forme actuelle est un cas normal et attendu (ex. variable encore à sa valeur par défaut non-JSON), déjà explicitement documenté par le commentaire de la fonction ("Ne lève jamais... même convention que côté serveur"). Un `console.warn` ici bruiterait la console à chaque usage légitime. | Lot 4 "modernisation JS", 18/09/2026 |
+
+### Détail — `javascript:S8786` (ReDoS), lot 1 "modernisation JS"
+
+Méthode : pour chaque regex distincte flaguée, construction d'entrées **adversariales** (choisies pour maximiser l'ambiguïté que Sonar soupçonne) via un script Node.js dédié, mesure du temps d'exécution à plusieurs tailles croissantes. Un vrai ReDoS montre une croissance **exponentielle** du temps avec la taille de l'entrée (doubler la taille multiplie le temps par un facteur, pas par une constante) — ici, le temps reste quasi-linéaire à toutes les tailles testées, y compris pour la structure la plus suspecte des 3.
+
+**Pattern A** — `FORGE_REF_PATTERN` (`filter-repeater-rows.js:10`) et `_FILTER_REF_RE` (`panel-init.js:254`, copie identique) :
+```
+/^\{\{\s*([^.{}]+)\.([^.{}]+)\s*\}\}$/
+```
+Structure soupçonnée : deux groupes quantifiés (`[^.{}]+`) séparés par un littéral (`\.`). Non exploitable ici car les deux classes sont **négatives** et excluent explicitement le `.` qui les sépare — à une position donnée, il n'existe qu'un seul découpage possible entre les deux groupes (pas de chevauchement combinatoire).
+Entrées testées : `` `{{` + 'a'.repeat(n) `` (pas de fermeture) et `` `{{` + 'a'.repeat(n) + '.' + 'b'.repeat(n) `` (point présent, pas de fermeture), `n` = 1 000 / 10 000 / 50 000 / 100 000.
+Résultat mesuré : **1.39 ms à n=100 000** (pire cas). Vérifié aussi que le pattern reste correct sur une entrée valide (`{{Objet.champ}}` → capture `['Objet', 'champ']`).
+
+**Pattern B** — `FORGE_VAR_REF_PATTERN` (`filter-repeater-rows.js:11`) et `_VAR_REF_RE` (`panel-init.js:261`, copie identique) :
+```
+/^\{\{\s*\$([^.{}[\]]+)((?:\.[^.{}[\]]+|\[\d+\])*)\s*\}\}$/
+```
+Structure soupçonnée : la plus proche d'un vrai ReDoS des 3 — un groupe répété par `*` dont une branche de l'alternance contient elle-même un `+` (proche du classique `(a+)*`). Non exploitable ici car chaque itération exige un caractère de tête exclusif (`.` ou `[`) qui est justement exclu de la classe négative interne (`[^.{}[\]]`) — aucune itération ne peut chevaucher la suivante.
+Entrées testées : `` `{{$a` + '.b'.repeat(n) `` (répétition simple, pas de fermeture) et `` `{{$a` + '.b[0]'.repeat(n) `` (alternance des deux branches, pas de fermeture), `n` = 1 000 / 5 000 / 10 000 / 20 000.
+Résultat mesuré : **0.95 ms à n=20 000 segments** (pire cas, forme alternée). Vérifié sur entrée valide (`{{$var.champ[0].sous}}` → capture `['var', '.champ[0].sous']`).
+
+**Pattern C** — `xapi-client.js:132` :
+```js
+config.endpoint.replace(/\/+$/, '')
+```
+Structure soupçonnée : un seul groupe quantifié sur un littéral unique, ancré en fin de chaîne — le cas le plus simple des 3, sans groupe adjacent ni alternance avec qui entrer en ambiguïté.
+Entrée testée : `'/'.repeat(n)`, `n` = 10 000 / 100 000 / 1 000 000.
+Résultat mesuré : **1.38 ms à n=1 000 000** (le run à n=100 000 a affiché 13.89 ms, un pic de bruit de mesure — non reproductible et incohérent avec un temps plus court à n=1 000 000, donc pas un signal réel). Vérifié sur entrée valide (`'https://host///'.replace(...)` → `'https://host'`).
+
+**Pour refaire ce test après une modification d'une de ces 3 regex** : `node docs/redos_probe_s8786.js` — script conservé dans le dépôt, directement exécutable, pas à reconstituer depuis la prose. Si le temps croît plus vite que linéairement (ex. ×100 quand la taille ×10), c'est un vrai ReDoS — sinon, le `NOSONAR` reste justifié.
+
+## 6. Backlog qualité
+
+- **djLint H021 (49 occurrences, 6 templates)** — styles inline à remplacer par un système de modèles/classes CSS réutilisables. **Priorité immédiate** après la clôture de ce dispositif, avant ou après la Phase 4 CI selon décision à prendre le moment venu. Ce n'est **pas** une exception documentée en section 5 : c'est une dette assumée et non traitée, à corriger, pas à justifier indéfiniment.
+- **Code smells SonarQube** — lot JS "modernisation" (357 issues d'origine), plan détaillé et validé dans `docs/JS_MODERNIZATION_PLAN.md` (répartition par règle, classification mécanique/cas par cas, outillage vérifié, 9 lots) ; lots 1-3 (`S8786`, `S2703`, `S2486`) faits. Lots 4+ repris le 18/09/2026 via SonarLint (IDE) fichier par fichier — pas de liste exhaustive centralisée pendant que le dashboard serveur restait inaccessible, donc pas de rescan global de confirmation avant que la CI `sonarqube` (voir ci-dessous) tourne à nouveau. Reste aussi la complexité cognitive Python et la duplication, non encore triées.
+- **CI `sonarqube` restaurée (18/09/2026)** — job remis en place dans `.gitea/workflows/deploy.yml` (non-bloquant) une fois l'instance prod confirmée opérationnelle. Le service `docker-compose.prod.yml` reste volontairement absent de ce dépôt (prod pilotée autrement de ce côté). Une fois le premier scan CI passé : comparer son rapport à ce qui a déjà été corrigé fichier par fichier via SonarLint, pour confirmer qu'aucun doublon/oubli, avant de retirer `continue-on-error: true`.

ai/__init__.py

@@ -0,0 +1,21 @@
+"""Couche IA (voir plan Phase 1) — infra transverse, distincte de
+screens/ (rendu/données de jeu) : ai.tools définit les outils exposés à
+l'agent (Phase 2) sans dépendre du SDK anthropic lui-même, pour rester
+testable sans clé API."""
+
+from .chat import run_chat_turn
+from .client import MODEL, AnthropicNotConfiguredError, get_client
+from .scenario_client import ScenarioGenerationError, ScenarioNotConfiguredError, generate_image_url
+from .tools import TOOLS, dispatch_tool
+
+__all__ = [
+    "TOOLS",
+    "dispatch_tool",
+    "get_client",
+    "AnthropicNotConfiguredError",
+    "MODEL",
+    "generate_image_url",
+    "ScenarioNotConfiguredError",
+    "ScenarioGenerationError",
+    "run_chat_turn",
+]

ai/chat.py

@@ -0,0 +1,339 @@
+"""Boucle tool-use (voir plan Phase 2, §5) — Claude Sonnet 5 pilote
+UNIQUEMENT les tools de ai/tools.py, jamais d'écriture directe en base :
+tout ce qu'un tour de chat produit est donc TOUJOURS relisable/
+modifiable dans l'éditeur normal (même garantie que la Phase 1)."""
+
+import json
+from typing import Any
+
+import db
+import screens
+
+from .client import MODEL, get_client
+from .tools import TOOLS, dispatch_tool
+
+# Borne dure : jamais une boucle sans fin qui dépenserait sans fin si
+# Claude s'entête à rappeler des outils (bug de prompt, tool qui échoue
+# en boucle, etc.) — un écran complet (fond, personnages, widgets,
+# déclencheur, ajustements) peut légitimement dépasser 8 appels.
+_MAX_TOOL_ITERATIONS = 12
+
+_SYSTEM_PROMPT = (
+    "Tu t'appelles Ruby, l'assistante IA de Forge Engine — présente-toi "
+    "sous ce nom si on te le demande. "
+    "Tu aides un créateur à construire UN SEUL écran d'un jeu de "
+    "formation professionnelle 2D (Forge Engine), via les outils fournis "
+    "— jamais autrement. Ne touche qu'à cet écran, jamais aux autres. "
+    "Réutilise une variable globale déjà existante UNIQUEMENT si elle "
+    "représente EXACTEMENT la même information (ex. un score total "
+    "partagé par tout le jeu) — les variables sont globales à TOUT le "
+    'jeu, visibles depuis n\'importe quel écran, donc un drapeau "terminé" '
+    "propre à UN dialogue/quiz précis ne doit JAMAIS être partagé avec un "
+    "autre dialogue/quiz, même similaire, même sur un autre écran (bug "
+    'corrigé : un quiz réutilisait par erreur le drapeau "terminé" d\'un '
+    "AUTRE quiz sans lien, les rendant mutuellement incohérents). Donne à "
+    "chaque nouveau drapeau un nom qui identifie clairement CE qu'il "
+    "suit (ex. préfixé par le nom du personnage/objet concerné). "
+    "N'utilise add_generated_image "
+    "QUE pour des fonds ou des objets 2D isolés (meubles, plantes, décor) "
+    "— jamais pour un personnage ou un sprite animé, la génération "
+    "d'image n'est pas fiable pour ça. "
+    "\n\n"
+    "CE QUE TU NE PEUX PAS FAIRE : tes outils pilotent la logique "
+    "\"déclencheur -> action\" d'un objet de scène OU de l'écran entier "
+    "(voir DÉCLENCHEURS/ACTIONS ci-dessous). Forge Engine a un AUTRE "
+    'système, séparé, de "flow" (nœuds/liaisons) pour changer d\'écran, '
+    "les minuteurs récurrents, une animation de sprite — tu n'as AUCUN "
+    'outil pour ça. Si une demande a besoin de cette partie-là ("passer '
+    'à l\'écran suivant", "après 5 secondes"...), fais quand même tout '
+    "ce que tes outils permettent, puis DIS CLAIREMENT dans ta réponse "
+    "texte ce que tu n'as pas pu faire et pourquoi (cette partie doit "
+    "être ajoutée à la main dans l'onglet \"Flow\") — ne t'acharne JAMAIS "
+    "à répéter des appels d'outils pour une chose qu'aucun outil ne "
+    "permet, ça n'aboutira jamais."
+    "\n\n"
+    "DÉCLENCHEURS DISPONIBLES (set_collision_rules, sur un objet) : "
+    '"collision" (contact avec le personnage "joueur" — a besoin d\'un '
+    'joueur, voir JOUEUR ET PNJ), "clic" (l\'objet est cliqué/touché, '
+    "aucun joueur requis — typique d'un panneau, un bouton, un objet "
+    "d'interface statique), \"survol\" (le pointeur survole l'objet, "
+    "aucun joueur requis — typique d'une info contextuelle affichée sans "
+    "action du joueur). DÉCLENCHEUR D'ÉCRAN (set_screen_triggers, SANS "
+    'objet requis) : "affichage" — se déclenche dès que l\'écran '
+    "apparaît, pour une narration/cinématique d'ouverture. "
+    "RÈGLE IMPORTANTE : si le créateur ne précise PAS explicitement quel "
+    'déclencheur utiliser pour un élément donné (ex. "ajoute un panneau '
+    "d'information\" sans dire si c'est au clic, au survol, ou dès "
+    "l'affichage), NE CHOISIS PAS toute seule — pose la question dans ta "
+    "réponse texte avant d'agir. "
+    "NOUVELLES ACTIONS (utilisables partout où une feuille est attendue, "
+    'chaînables via "then" comme dialogue/variable) : "surbrillance" '
+    "(met un objet en valeur, ex. pour guider l'attention du joueur vers "
+    'la suite), "visibilite" (affiche/masque un objet, ex. débloquer un '
+    'élément), "son" (effet sonore ponctuel), "video" (joue une vidéo '
+    'de "Mes assets", en plein écran ou en incrustation — bloque la '
+    'suite de la chaîne jusqu\'à la fin, comme un dialogue), "indication" '
+    "(bulle de texte courte près d'un objet, pour un conseil ponctuel — "
+    'PAS pour une réplique de personnage, utilise "dialogue" pour ça), '
+    '"attendre" (suspend la chaîne "then" pendant data_value SECONDES '
+    "avant de continuer — utile pour laisser un temps de lecture après "
+    "une narration à l'affichage de l'écran, avant d'enchaîner sur un "
+    "dialogue/une autre action)."
+    "\n\n"
+    "ÉTAT DE LA SCÈNE : le message système de chaque tour te donne les "
+    "dimensions de la caméra, la liste des objets déjà posés sur CET "
+    "écran, et les variables globales déjà existantes — relis-les avant "
+    "d'agir plutôt que de deviner (ne recrée jamais un objet ou une "
+    "variable qui existe déjà, corrige/complète l'existant avec "
+    "set_object_geometry/set_object_name/set_object_role/set_collision_rules). "
+    "Pour retirer ou réordonner UNE action précise d'une chaîne déjà posée "
+    "(sans reconstruire toute la règle), utilise remove_trigger_action/"
+    "move_trigger_action (objet) ou remove_screen_trigger_action/"
+    "move_screen_trigger_action (écran) avec le leaf_id concerné. "
+    "append_action_to_trigger/append_action_to_screen_trigger peuvent "
+    "INSÉRER une action à N'IMPORTE QUEL niveau d'une chaîne (pas "
+    "seulement à la toute fin) : after_id désigne le bloc juste AVANT "
+    "l'endroit où insérer."
+    "\n\n"
+    "CAMÉRA ET POSITIONNEMENT : les dimensions indiquées sont la zone "
+    "VISIBLE (coin haut-gauche à (0,0)) — place tout objet important "
+    "(personnages, widgets d'interface) DANS cette zone par défaut. Le "
+    "moteur RAMÈNE automatiquement dans le cadre toute position qui en "
+    'sortirait (voir un éventuel champ "note" dans le résultat de '
+    "set_object_geometry/add_scene_object — c'est déjà corrigé, rien à "
+    "refaire), donc vise une position raisonnable sans stresser sur le "
+    "pixel exact. Ne superpose jamais deux objets aux mêmes coordonnées "
+    "— espace-les clairement. Un personnage fraîchement posé fait "
+    "128x128 px par défaut — garde des tailles cohérentes entre "
+    'personnages sauf besoin explicite. RÈGLE FIXE pour un "fond" : '
+    "redimensionne-le TOUJOURS automatiquement en 2000x1000 px "
+    "(set_object_geometry, position (0,0)) juste après l'avoir posé, "
+    "SANS que le créateur ait besoin de le demander à chaque fois — "
+    "c'est le format standard de Forge Engine. Ne dépasse cette taille "
+    "que si le créateur demande explicitement un monde à explorer plus "
+    "grand."
+    "\n\n"
+    "JOUEUR ET PNJ : un personnage fraîchement posé a TOUJOURS le rôle "
+    '"pnj" par défaut, JAMAIS "joueur". Un déclencheur de type '
+    '"collision" ne se déclenche QUE par le contact du personnage au '
+    'rôle "joueur" — sans lui, la collision ne se déclenche jamais ET '
+    "la caméra n'a personne à suivre. Dès qu'un écran a besoin d'un "
+    "déclencheur de collision (quiz, dialogue déclenché en marchant "
+    "vers un PNJ, etc.), assure-toi qu'IL EXISTE EXACTEMENT UN "
+    'personnage avec role="joueur" (set_object_role) — jamais deux, '
+    "et ne pose jamais deux PNJ identiques sans que le créateur l'ait "
+    "demandé. "
+    "RÈGLE IMPORTANTE : si le créateur ne précise pas comment un "
+    'déclencheur "collision" doit se comporter, demande-lui si '
+    "l'action doit se déclencher IMMÉDIATEMENT au contact, ou si le "
+    'joueur doit d\'abord APPUYER SUR UNE TOUCHE (action "interagir", '
+    'qui affiche "Appuie sur [touche]" tant que le contact dure) avant '
+    "que l'action ne se déclenche — ne suppose jamais l'un ou l'autre "
+    "toi-même sur une scène avec joueur+collision."
+    "\n\n"
+    "QUAND UTILISER QUOI : une VARIABLE globale sert à mémoriser une "
+    "donnée consultée plus tard (progression, un choix du joueur, un "
+    'drapeau "terminé") — JAMAIS pour un score de quiz (voir '
+    "reward_amount plus haut, déjà automatique). Modifie une variable "
+    '(action "variable") quand un événement doit changer durablement '
+    'cet état (ex. marquer un drapeau "xxx_termine" à vrai une fois un '
+    "quiz fini). Utilise une CONDITION quand le comportement doit "
+    "VRAIMENT différer selon l'état actuel d'une variable — un simple "
+    "enchaînement linéaire n'a besoin que d'un chaînage \"then\", jamais "
+    "d'une condition. CAS CANONIQUE à connaître : un dialogue/quiz à "
+    "USAGE UNIQUE (ex. un PNJ qui pose un quiz une seule fois) doit être "
+    "protégé par une CONDITION qui vérifie D'ABORD le drapeau "
+    '"xxx_termine" — si faux (pas encore fait), lance le dialogue/quiz '
+    'normal (branche si_faux) PUIS termine par une action "variable" '
+    "qui passe ce drapeau à vrai ; si vrai (déjà fait), réponds par une "
+    "réplique courte différente (branche si_vrai) au lieu de rejouer "
+    "tout le quiz à chaque collision. Utilise un DIALOGUE pour toute "
+    "réplique ou question posée au joueur."
+    "\n\n"
+    "IMPORTANT — UN DIALOGUE/QUIZ/SCORE NE S'AFFICHE JAMAIS TOUT SEUL EN "
+    "JEU : il faut TOUJOURS poser en plus le widget d'interface "
+    "correspondant sur l'écran via add_scene_object, sinon rien n'apparaît "
+    "à l'écran même si le déclencheur est correctement configuré. Une "
+    'action "dialogue" dont les lignes sont de type "replique" a besoin '
+    'd\'un objet kind="dialogue_box" ; une action "dialogue" dont les '
+    'lignes sont de type "question" (quiz) a besoin d\'un objet '
+    'kind="quiz_box" (pas dialogue_box) ; si un score/des points sont '
+    'utilisés, ajoute aussi un objet kind="score_widget" pour qu\'il soit '
+    "visible en continu. Positionne ces widgets à un endroit raisonnable "
+    "de l'écran (ex. centré, ou en haut) via set_object_geometry après "
+    "les avoir posés."
+    "\n\n"
+    "QUIZ AUTONOME (RH/formation, pas narratif) : quand le créateur décrit "
+    'un besoin de quiz "tout seul" (pas un personnage/dialogue de jeu), '
+    'utilise set_quiz_box_config sur l\'objet kind="quiz_box" pour régler '
+    "le PLEIN ÉCRAN (fullscreen) et un MINUTEUR pour répondre (timer_mode : "
+    "jamais imposé par défaut — demande TOUJOURS si le créateur en veut un "
+    'avant d\'en activer un, "question" redémarre à chaque question, '
+    '"quiz" est un seul compte à rebours pour tout le quiz, timer_seconds '
+    "sa durée)."
+    "\n\n"
+    "MODÈLES VISUELS — DEUX catégories bien distinctes, jamais confondues : "
+    'dialog_template (modèles "boîte de dialogue" : "defaut" — Classique — '
+    'ou "manga_dialogue", le pendant en petite carte du thème manga) ne '
+    "s'affiche QUE si fullscreen=false. "
+    'page_template (modèles "page de quiz" : "classique" — sobre/'
+    'professionnel, couleurs reprises du modèle "boîte de dialogue" de '
+    'base — ou "manga", un thème dessiné/typographié entièrement à part) '
+    "ne s'affiche QUE si fullscreen=true — chacun un thème complet et "
+    "autonome (police, formes, couleurs ET structure entièrement propres à "
+    "ce modèle), pensé pour un quiz qui occupe tout l'écran. Les deux "
+    "réglages sont conservés "
+    "INDÉPENDAMMENT (jamais l'un n'écrase l'autre) : ne règle QUE celui qui "
+    "correspond au mode (plein écran ou non) réellement voulu par le "
+    "créateur, et demande le style souhaité s'il n'en a mentionné aucun "
+    "plutôt que d'en choisir un au hasard. En plein écran, le score choisi "
+    "via score_widget/reward_amount s'affiche automatiquement DANS la boîte "
+    "à quiz, sans réglage supplémentaire."
+    "\n\n"
+    "Ton professionnel, adapté à une formation d'entreprise. Réponds "
+    "toujours en français, de façon concise, en confirmant ce que tu as "
+    "posé."
+)
+
+
+class ScreenDeletedError(Exception):
+    """Garde-fou défensif pour screen_id introuvable : en usage normal,
+    supprimer un écran (screens/screens_repo/delete_screen.py) supprime
+    déjà EN CASCADE ses conversations IA (ON DELETE CASCADE, voir
+    screens/ia/ensure_ia_chat_schema.py) — cette voie n'est donc pas
+    censée être atteignable via l'appli. get_screen() renvoyant
+    dict | None, ce garde évite quand même un crash cru (attribut sur
+    None) si jamais screen_id était invalide pour une autre raison,
+    plutôt qu'un message lisible par un humain (voir run_chat_turn)."""
+
+
+def _describe_scene_state(slug: str, screen_id: int) -> str:
+    """Contexte dynamique (jamais mémorisé côté Claude entre les tours,
+    voir run_chat_turn — seul le texte final est persisté) : sans ça,
+    Ruby ne "voit" jamais ce qui existe déjà sur l'écran et duplique des
+    objets au lieu de les corriger (bug observé : 2 PNJ identiques créés
+    à la place d'un seul joueur + un pnj)."""
+    screen = screens.get_screen(slug, screen_id)
+    if screen is None:
+        raise ScreenDeletedError("L'écran de cette conversation a été supprimé.")
+    width, height = screen["scene_width"], screen["scene_height"]
+    objects = screens.list_scene_objects(slug, screen_id)
+    # Répété ICI (pas seulement dans les instructions générales) avec les
+    # VRAIS chiffres de cet écran — un rappel abstrait une seule fois dans
+    # un long system prompt s'est montré insuffisant (bug observé deux
+    # fois : personnage posé à des coordonnées bien au-delà de la caméra).
+    lines = [
+        f"Zone visible par la caméra CETTE ÉCRAN : x de 0 à {width}, y de 0 à {height} "
+        f"(coin haut-gauche à (0,0)). RAPPEL : place tout personnage/widget d'interface "
+        f"À L'INTÉRIEUR de ces bornes par défaut (ex. x autour de {width // 2}, "
+        f"y autour de {height // 2} pour un centrage simple), sauf demande explicite d'un "
+        "monde plus grand à explorer."
+    ]
+    if not objects:
+        lines.append("Aucun objet posé sur cet écran pour l'instant.")
+    else:
+        lines.append(f"{len(objects)} objet(s) déjà posé(s) sur cet écran :")
+        for o in objects:
+            desc = (
+                f"- id={o['id']} kind={o['kind']} position=({int(o['x'])},{int(o['y'])}) "
+                f"taille={int(o['width'])}x{int(o['height'])}"
+            )
+            if o.get("name"):
+                desc += f" nom={o['name']!r}"
+            if o["kind"] == "personnage":
+                desc += f" rôle={screens.resolve_personnage_role(o)}"
+            if (o.get("attributes") or {}).get("_collision_rules"):
+                desc += " [déclencheur déjà configuré]"
+            lines.append(desc)
+
+    screen_triggers = screens.resolve_screen_triggers(screen)
+    if screen_triggers:
+        lines.append(
+            f"{len(screen_triggers)} déclencheur(s) D'ÉCRAN déjà configuré(s) sur cet écran "
+            "(voir set_screen_triggers) — relis-les avant d'en ajouter un nouveau plutôt que "
+            "de dupliquer une narration d'ouverture déjà posée."
+        )
+    else:
+        lines.append("Aucun déclencheur d'écran (narration à l'affichage) configuré pour l'instant.")
+
+    variables = db.list_global_variables(slug)
+    if variables:
+        lines.append("Variables globales déjà existantes dans ce jeu (jamais en recréer une du même nom) :")
+        for v in variables:
+            lines.append(f"- {v['name']} ({v['type']}, valeur actuelle : {v['value']})")
+    else:
+        lines.append("Aucune variable globale n'existe encore dans ce jeu.")
+    return "\n".join(lines)
+
+
+def _history_to_messages(history: list[dict[str, Any]]) -> list[Any]:
+    return [{"role": m["role"], "content": m["content"]} for m in history]
+
+
+def run_chat_turn(slug: str, screen_id: int, conversation_id: int, user_id: int, user_message: str) -> str:
+    """Un tour complet : reprend l'historique persisté de CETTE
+    conversation, ajoute le message du créateur, boucle tant que Claude
+    appelle des outils, et renvoie le texte final. `screen_id` reste
+    nécessaire pour les tools (voir ai/tools.py — chaque conversation
+    reste scopée à SON écran, une conversation ne change jamais
+    d'écran). Ne persiste RIEN elle-même — voir routes/ia/ia_chat.py,
+    seul appelant, qui décide de ce qui est sauvegardé (même séparation
+    que le reste du moteur : cette fonction ne fait que la logique IA)."""
+    try:
+        # État réel de la scène RE-LU à chaque tour (jamais mémorisé par
+        # Claude lui-même) — voir _describe_scene_state. Vérifié AVANT de
+        # construire le client Claude : pas la peine d'appeler l'API si
+        # l'écran de cette conversation n'existe plus.
+        scene_state = _describe_scene_state(slug, screen_id)
+    except ScreenDeletedError:
+        return "Cet écran a été supprimé — cette conversation n'est plus utilisable."
+    client = get_client()  # AnthropicNotConfiguredError si pas de clé
+    messages: list[Any] = _history_to_messages(screens.list_ia_chat_messages(slug, conversation_id))
+    messages.append({"role": "user", "content": user_message})
+    system_prompt = _SYSTEM_PROMPT + "\n\n" + scene_state
+
+    response = None
+    for _ in range(_MAX_TOOL_ITERATIONS):
+        # 4096 était trop bas (bug corrigé) : la réflexion adaptative
+        # partage le même budget que la réponse — sur une demande riche
+        # (plusieurs objets + logique + texte), Claude pouvait être coupé
+        # EN PLEINE RÉFLEXION, avant le moindre appel d'outil (symptôme
+        # observé : aucune progression du tout, "(pas de réponse
+        # textuelle)" dès le premier tour).
+        response = client.messages.create(  # type: ignore[call-overload]  # TOOLS/messages sont des dict Python bruts, pas les TypedDict exacts du SDK anthropic
+            model=MODEL,
+            max_tokens=16000,
+            system=system_prompt,
+            tools=TOOLS,
+            thinking={"type": "adaptive"},
+            messages=messages,
+        )
+        messages.append({"role": "assistant", "content": response.content})
+        if response.stop_reason != "tool_use":
+            break
+        tool_results: list[Any] = []
+        for block in response.content:
+            if block.type == "tool_use":
+                try:
+                    result = dispatch_tool(slug, screen_id, user_id, block.name, block.input)
+                except Exception as e:
+                    result = {"error": str(e)}
+                tool_results.append(
+                    {
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": json.dumps(result),
+                    }
+                )
+        messages.append({"role": "user", "content": tool_results})
+
+    response = db.assert_not_none(response, "_MAX_TOOL_ITERATIONS > 0, la boucle for s'execute donc au moins une fois")
+    text = next((b.text for b in response.content if b.type == "text"), "")
+    if text:
+        return text
+    if response.stop_reason == "max_tokens":
+        return (
+            "Ruby a été interrompue avant de terminer (demande trop complexe pour une seule "
+            "réponse) — réessaie en la découpant en plusieurs étapes plus simples."
+        )
+    return "(pas de réponse textuelle)"

ai/client.py

@@ -0,0 +1,22 @@
+"""Client Claude (voir plan Phase 2, §2) — même politique que
+auth/send_email.py::EmailNotConfiguredError : une clé absente est une
+configuration incomplète, jamais un crash brut ni une clé en dur."""
+
+import os
+
+import anthropic
+
+MODEL = "claude-sonnet-5"
+
+
+class AnthropicNotConfiguredError(Exception):
+    """Levée quand ANTHROPIC_API_KEY est absente — voir .env.example.
+    Le compte claude.ai Entreprise (chat en équipe) n'est PAS une clé API :
+    il faut un compte Anthropic Console (console.anthropic.com) séparé."""
+
+
+def get_client() -> anthropic.Anthropic:
+    api_key = os.environ.get("ANTHROPIC_API_KEY")
+    if not api_key:
+        raise AnthropicNotConfiguredError("ANTHROPIC_API_KEY absente")
+    return anthropic.Anthropic(api_key=api_key)

ai/scenario_client.py

@@ -0,0 +1,73 @@
+"""Client Scenario (voir plan Phase 2, §3) — génération d'images (fonds/
+objets 2D uniquement, jamais de personnages/sprites — décision actée
+lors de l'étude préalable). API confirmée (docs.scenario.com) :
+authentification Basic (clé + secret), génération ASYNCHRONE par job —
+POST déclenche un job, GET /jobs/{id} jusqu'à "success"/"failure", puis
+GET /assets/{id} pour l'URL finale téléchargeable.
+
+Ce module reste un simple client HTTP : il renvoie l'URL de l'image,
+jamais ne la télécharge/l'enregistre lui-même — ça reste le travail de
+ai/tools.py::_dispatch_add_generated_image (voir "Mes assets",
+auth/user_assets_dir.py), pour que ce module soit testable seul."""
+
+import os
+import time
+
+import requests
+
+_BASE_URL = "https://api.cloud.scenario.com/v1"
+
+
+class ScenarioNotConfiguredError(Exception):
+    """SCENARIO_API_KEY/SCENARIO_API_SECRET/SCENARIO_MODEL_ID absents —
+    voir .env.example. SCENARIO_MODEL_ID est l'id du modèle entraîné sur
+    le style graphique unique de Forge Engine (pas encore créé tant que
+    l'entraînement Scenario n'a pas été fait)."""
+
+
+class ScenarioGenerationError(Exception):
+    """Le job Scenario a échoué ou n'a pas répondu à temps."""
+
+
+def _credentials() -> tuple[tuple[str, str], str]:
+    api_key = os.environ.get("SCENARIO_API_KEY")
+    api_secret = os.environ.get("SCENARIO_API_SECRET")
+    model_id = os.environ.get("SCENARIO_MODEL_ID")
+    if not api_key or not api_secret or not model_id:
+        raise ScenarioNotConfiguredError(
+            "SCENARIO_API_KEY/SCENARIO_API_SECRET/SCENARIO_MODEL_ID absents — voir .env.example."
+        )
+    return (api_key, api_secret), model_id
+
+
+def generate_image_url(
+    prompt: str, width: int = 768, height: int = 768, timeout: int = 120, poll_interval: int = 2
+) -> str:
+    """Lance une génération txt2img et attend le résultat — renvoie
+    l'URL finale de l'image (hébergée par Scenario, à télécharger par
+    l'appelant). Bloquant (poll_interval secondes entre chaque
+    vérification), borné par `timeout` secondes au total."""
+    auth, model_id = _credentials()
+    response = requests.post(
+        f"{_BASE_URL}/generate/txt2img",
+        auth=auth,
+        timeout=30,
+        json={"prompt": prompt, "modelId": model_id, "width": width, "height": height, "numSamples": 1},
+    )
+    response.raise_for_status()
+    job_id = response.json()["job"]["jobId"]
+
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        status_response = requests.get(f"{_BASE_URL}/jobs/{job_id}", auth=auth, timeout=30)
+        status_response.raise_for_status()
+        job = status_response.json()["job"]
+        if job["status"] == "success":
+            asset_id = job["metadata"]["assetIds"][0]
+            asset_response = requests.get(f"{_BASE_URL}/assets/{asset_id}", auth=auth, timeout=30)
+            asset_response.raise_for_status()
+            return str(asset_response.json()["asset"]["url"])
+        if job["status"] == "failure":
+            raise ScenarioGenerationError("Scenario a échoué à générer l'image.")
+        time.sleep(poll_interval)
+    raise ScenarioGenerationError("Scenario n'a pas répondu à temps.")

ai/tools.py

@@ -0,0 +1,768 @@
+"""Outils exposés à l'agent IA (voir plan Phase 1, §4) — chaque tool
+appelle DIRECTEMENT une fonction déjà utilisée par l'éditeur no-code
+manuel, jamais une structure parallèle : ce qu'un créateur voit ensuite
+dans l'éditeur (Déclencheurs, Variables, panneau de propriétés) est donc
+TOUJOURS le résultat du même code, qu'il ait été posé à la main ou par
+l'IA.
+
+Aucune dépendance au SDK anthropic ici (voir ai/__init__.py) — ce module
+ne fait que décrire les schémas et les relier à screens.*/db.* ; la
+boucle tool-use elle-même (Phase 2) l'utilisera tel quel.
+
+Principe validé avec l'utilisateur : un NOUVEL outil reste une décision
+explicite (jamais de réflexion automatique sur tout screens/), mais une
+VALEUR interne à un outil existant (un type d'action, un opérateur de
+condition, une opération de variable) doit suivre automatiquement dès
+qu'elle est ajoutée côté moteur — d'où les schémas ci-dessous construits
+à partir des constantes existantes (ACTION_TYPES, CONDITION_OPERATORS,
+DATA_OPERATION_LABELS, ...) plutôt que recopiées en dur. Un test dédié
+(tests/test_ai_tools.py) vérifie que cette référence n'est jamais
+remplacée par une copie littérale."""
+
+import os
+from typing import Any, Callable
+
+import requests
+from flask import url_for
+
+import auth
+import db
+import screens
+from db.dialogue_lines import QUESTION_REWARD_TYPES
+from screens.labels.data_operations import DATA_OPERATION_LABELS
+from screens.labels.element_visibility import ELEMENT_VISIBILITY_LABELS
+from screens.labels.surbrillance_values import SURBRILLANCE_LABELS
+from screens.labels.video_modes import VIDEO_MODE_LABELS
+from screens.rendering.collision_rules import ACTION_TYPES, CONDITION_OPERATOR_KEYS, LEAF_ACTION_TYPES, TRIGGER_TYPES
+from screens.rendering.screen_triggers import TRIGGER_TYPES_SCREEN
+
+from .scenario_client import generate_image_url
+
+_CONDITION_OPERATORS = sorted(CONDITION_OPERATOR_KEYS)
+_DATA_OPERATIONS = sorted(DATA_OPERATION_LABELS)
+_PERSONNAGE_ROLES = list(screens.PERSONNAGE_ROLES)
+_COLLISION_SHAPES = list(screens.COLLISION_SHAPES)
+_QUIZ_BOX_TIMER_MODES = list(screens.TIMER_MODES)
+_QUIZ_BOX_DIALOG_TEMPLATES = list(screens.QUIZ_BOX_DIALOG_TEMPLATES)
+_QUIZ_BOX_PAGE_TEMPLATES = list(screens.QUIZ_BOX_PAGE_TEMPLATES)
+_GLOBAL_VARIABLE_TYPES = sorted(db.GLOBAL_VARIABLE_TYPES)
+# Catalogue COMPLET (public + admin-only, voir core/sprite_gate.py) —
+# Claude doit connaître les slugs valides pour ne jamais en deviner un
+# qui retomberait silencieusement sur le personnage par défaut
+# (screens.add_scene_object). L'accès aux entrées admin-only reste
+# vérifié à l'exécution (voir _dispatch_add_scene_object), même garde
+# que la galerie manuelle.
+_FORGE_CHARACTERS = sorted(screens.SPRITE_LIBRARY)
+_BACKGROUNDS = sorted(screens.BACKGROUND_LIBRARY)
+
+_LEAF_ACTION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "description": (
+        'Une action FEUILLE ("dialogue" ou "variable", voir '
+        "screens/rendering/collision_rules.py) — peut porter un champ "
+        'optionnel "then" (une autre feuille, chaînage borné à 4).'
+    ),
+    "properties": {
+        "type": {"type": "string", "enum": list(LEAF_ACTION_TYPES)},
+        "id": {
+            "type": "string",
+            "description": "Identifiant de cette feuille, pour l'adresser plus tard via append_action_to_trigger.",
+        },
+        "dialogue": {
+            "type": "object",
+            "description": (
+                "Pour type=dialogue : {id, lines}. Chaque élément de `lines` est SOIT une "
+                'RÉPLIQUE {"type":"dialogue", "speaker": <qui parle>, "text": <texte>}, '
+                'SOIT une QUESTION DE QUIZ {"type":"question", "text", "choices": '
+                '[2 à 4 réponses], "correct_index": <index de la bonne réponse>, '
+                f'"reward_type": {list(QUESTION_REWARD_TYPES)!r}, "reward_amount": <entier>}}. '
+                "reward_amount alimente le SCORE NATIF du jeu (visible via un objet "
+                'kind="score_widget", nécessite aussi un objet kind="quiz_box" posé pour que '
+                "la question s'affiche) — crédité UNIQUEMENT si la réponse est correcte, sinon "
+                "ignoré ; le joueur avance toujours à la ligne suivante, bonne réponse ou pas. "
+                "N'invente JAMAIS une variable séparée pour suivre un score de quiz : "
+                'reward_amount fait déjà tout, sans action "variable" supplémentaire.'
+            ),
+            "properties": {"id": {"type": "string"}, "lines": {"type": "array"}},
+        },
+        "mark_completed": {"type": "boolean"},
+        "target_variable": {
+            "type": "string",
+            "description": "Pour type=variable : nom d'une variable globale existante.",
+        },
+        "data_operation": {"type": "string", "enum": _DATA_OPERATIONS},
+        "data_value": {
+            "type": "string",
+            "description": (
+                "Pour type=variable : absent pour definir_bool_vrai/definir_bool_faux/basculer_bool. "
+                'Pour type=attendre : nombre de SECONDES à attendre avant "then" (ex. "2", "1.5").'
+            ),
+        },
+        "object_id": {
+            "type": "integer",
+            "description": (
+                "Pour type=surbrillance/visibilite/indication : id de l'objet CIBLÉ par cette "
+                "action — n'importe quel objet de l'écran, pas forcément celui qui porte le "
+                "déclencheur (ex. le joueur touche un interrupteur -> indication près d'une porte)."
+            ),
+        },
+        "valeur": {
+            "type": "string",
+            "description": (
+                f"Pour type=surbrillance : une valeur parmi {sorted(SURBRILLANCE_LABELS)!r}. "
+                f"Pour type=visibilite : une valeur parmi {sorted(ELEMENT_VISIBILITY_LABELS)!r}. "
+                "Pour type=condition (voir _ACTION_SCHEMA) : la valeur littérale à comparer."
+            ),
+        },
+        "asset_url": {
+            "type": "string",
+            "description": 'Pour type=son/video : URL d\'un fichier déjà présent dans "Mes assets".',
+        },
+        "mode": {"type": "string", "enum": sorted(VIDEO_MODE_LABELS), "description": "Pour type=video."},
+        "texte": {"type": "string", "description": "Pour type=indication : le texte affiché dans la bulle."},
+        "duree_ms": {"type": "integer", "description": "Pour type=indication : durée d'affichage en ms (optionnel)."},
+        "then": {"description": "Feuille suivante (même forme), récursif."},
+    },
+    "required": ["type"],
+}
+
+_ACTION_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "description": (
+        "Une action de déclencheur — voir screens/rendering/collision_rules.py pour la forme exacte de chaque type."
+    ),
+    "properties": {
+        "type": {"type": "string", "enum": list(ACTION_TYPES)},
+        "id": {"type": "string"},
+        "dialogue": _LEAF_ACTION_SCHEMA["properties"]["dialogue"],
+        "mark_completed": {"type": "boolean"},
+        "target_variable": {"type": "string"},
+        "data_operation": {"type": "string", "enum": _DATA_OPERATIONS},
+        "data_value": {"type": "string"},
+        "object_id": _LEAF_ACTION_SCHEMA["properties"]["object_id"],
+        "valeur": _LEAF_ACTION_SCHEMA["properties"]["valeur"],
+        "asset_url": _LEAF_ACTION_SCHEMA["properties"]["asset_url"],
+        "mode": _LEAF_ACTION_SCHEMA["properties"]["mode"],
+        "texte": _LEAF_ACTION_SCHEMA["properties"]["texte"],
+        "duree_ms": _LEAF_ACTION_SCHEMA["properties"]["duree_ms"],
+        "then": {
+            "description": (
+                "Feuille suivante (dialogue/variable/surbrillance/visibilite/son/video/indication), récursif."
+            ),
+        },
+        "sub_action": {"description": 'Pour type=interagir : une action (pas "interagir" à nouveau).'},
+        "variable": {"type": "string", "description": "Pour type=condition."},
+        "operateur": {"type": "string", "enum": _CONDITION_OPERATORS},
+        "si_vrai": {"description": "Pour type=condition : null ou une feuille."},
+        "si_faux": {"description": "Pour type=condition : null ou une feuille."},
+    },
+    "required": ["type"],
+}
+
+TOOLS: list[dict[str, Any]] = [
+    {
+        "name": "add_scene_object",
+        "description": (
+            "Pose un nouvel objet sur l'écran en cours (personnage, décor, fond, "
+            'ou widget d\'interface). Pour une image générée/de "Mes assets", '
+            "utiliser image_url (jamais générer un personnage/sprite par ce biais)."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "kind": {
+                    "type": "string",
+                    "enum": ["personnage", "decor", "fond", "dialogue_box", "quiz_box", "score_widget"],
+                },
+                "forge_character": {
+                    "type": "string",
+                    "enum": _FORGE_CHARACTERS,
+                    "description": (
+                        "Pour kind=personnage : slug d'un personnage de la bibliothèque Forge "
+                        "existante (jamais un sprite généré)."
+                    ),
+                },
+                "background_slug": {
+                    "type": "string",
+                    "enum": _BACKGROUNDS,
+                    "description": (
+                        "Pour kind=fond : slug d'une image de fond déjà existante dans la bibliothèque Forge."
+                    ),
+                },
+                "image_url": {
+                    "type": "string",
+                    "description": (
+                        'URL d\'une image déjà uploadée/générée (voir "Mes assets") — kind '
+                        "decor/fond uniquement, prioritaire sur background_slug."
+                    ),
+                },
+            },
+            "required": ["kind"],
+        },
+    },
+    {
+        "name": "set_object_geometry",
+        "description": "Positionne/redimensionne un objet déjà posé sur l'écran, en pixels.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "x": {"type": "number"},
+                "y": {"type": "number"},
+                "width": {"type": "number"},
+                "height": {"type": "number"},
+            },
+            "required": ["object_id", "x", "y", "width", "height"],
+        },
+    },
+    {
+        "name": "set_object_name",
+        "description": (
+            'Donne un nom à un objet de scène (ex. "Stan", "Aka") — affiché comme '
+            '"qui parle" dans les dialogues qui lui sont attachés.'
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "name": {"type": "string"},
+            },
+            "required": ["object_id", "name"],
+        },
+    },
+    {
+        "name": "set_object_role",
+        "description": "Change le rôle d'un objet personnage (joueur / ennemie / pnj).",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "role": {"type": "string", "enum": _PERSONNAGE_ROLES},
+            },
+            "required": ["object_id", "role"],
+        },
+    },
+    {
+        "name": "set_object_collision",
+        "description": "Règle la boîte de collision d'un objet (forme, taille, décalage, activée ou non).",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "enabled": {"type": "boolean"},
+                "shape": {"type": "string", "enum": _COLLISION_SHAPES},
+                "width": {"type": "number"},
+                "height": {"type": "number"},
+                "offset_x": {"type": "number"},
+                "offset_y": {"type": "number"},
+            },
+            "required": ["object_id"],
+        },
+    },
+    {
+        "name": "set_quiz_box_config",
+        "description": (
+            'Règle les options d\'une "❓ Boîte à quiz" pensées pour un quiz AUTONOME '
+            '(RH/formation) : plein écran, minuteur (jamais imposé — "aucun" par défaut, '
+            'au choix du créateur : "question" redémarre à chaque question, "quiz" est un '
+            "seul compte à rebours pour tout le quiz), et DEUX modèles visuels INDÉPENDANTS "
+            "(les deux réglages sont conservés en même temps, jamais l'un n'écrase l'autre) : "
+            "dialog_template (visible SEULEMENT hors plein écran — variantes de forme/couleur "
+            'sur une structure proche de "Classique") et page_template (visible SEULEMENT en '
+            "plein écran — thème complet et autonome, structure HTML propre à chaque modèle). "
+            "En plein écran, le score se retrouve affiché directement dans la boîte."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "fullscreen": {"type": "boolean"},
+                "timer_mode": {"type": "string", "enum": _QUIZ_BOX_TIMER_MODES},
+                "timer_seconds": {
+                    "type": "integer",
+                    "description": 'Durée du minuteur (3 à 600s), ignorée si timer_mode="aucun".',
+                },
+                "dialog_template": {
+                    "type": "string",
+                    "enum": _QUIZ_BOX_DIALOG_TEMPLATES,
+                    "description": 'Modèle "boîte de dialogue" — ne s\'affiche que si fullscreen=false.',
+                },
+                "page_template": {
+                    "type": "string",
+                    "enum": _QUIZ_BOX_PAGE_TEMPLATES,
+                    "description": 'Modèle "page de quiz" — ne s\'affiche que si fullscreen=true.',
+                },
+            },
+            "required": ["object_id"],
+        },
+    },
+    {
+        "name": "create_global_variable",
+        "description": (
+            "Crée une variable globale (idempotent par nom) — utilisable ensuite dans les déclencheurs/conditions."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "var_type": {"type": "string", "enum": _GLOBAL_VARIABLE_TYPES},
+                "default_value": {"type": "string"},
+                "per_player": {"type": "boolean"},
+            },
+            "required": ["name"],
+        },
+    },
+    {
+        "name": "set_collision_rules",
+        "description": (
+            'Remplace TOUTES les règles "déclencheur -> action" d\'un objet. '
+            'Déclencheurs disponibles : "collision" (contact avec le personnage '
+            '"joueur" — voir set_object_role), "clic" (l\'objet est cliqué/touché, '
+            'aucun joueur requis), "survol" (le pointeur survole l\'objet, aucun '
+            "joueur requis). Sanitizé côté serveur (screens.sanitize_collision_rules) : "
+            "toute valeur invalide est silencieusement retirée plutôt que rejetée — "
+            "compare le nombre de `rules` renvoyées dans le résultat à ce que tu as "
+            "envoyé pour détecter un retrait silencieux."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "rules": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "trigger": {"type": "string", "enum": list(TRIGGER_TYPES)},
+                            "action": _ACTION_SCHEMA,
+                        },
+                        "required": ["trigger", "action"],
+                    },
+                },
+            },
+            "required": ["object_id", "rules"],
+        },
+    },
+    {
+        "name": "set_screen_triggers",
+        "description": (
+            "Remplace TOUTES les règles \"déclencheur d'écran -> action\" de l'écran "
+            "en cours — un déclencheur d'ÉCRAN se déclenche SANS avoir besoin d'un "
+            "objet (narration/cinématique dès l'affichage). Seul déclencheur : "
+            "\"affichage\" (à l'affichage de l'écran). Même sanitisation que "
+            "set_collision_rules."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "rules": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "trigger": {"type": "string", "enum": list(TRIGGER_TYPES_SCREEN)},
+                            "action": _ACTION_SCHEMA,
+                        },
+                        "required": ["trigger", "action"],
+                    },
+                },
+            },
+            "required": ["rules"],
+        },
+    },
+    {
+        "name": "add_generated_image",
+        "description": (
+            "Génère une image (fond ou objet 2D UNIQUEMENT, JAMAIS un "
+            "personnage/sprite — la génération d'image n'est pas fiable pour "
+            'ça) via Scenario, l\'ajoute à "Mes assets" et la pose '
+            "automatiquement sur l'écran en cours."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "kind": {"type": "string", "enum": ["decor", "fond"]},
+                "prompt": {"type": "string", "description": "Description de l'image en langage naturel."},
+            },
+            "required": ["kind", "prompt"],
+        },
+    },
+    {
+        "name": "append_action_to_trigger",
+        "description": (
+            "Insère une action JUSTE APRÈS un bloc précis d'une chaîne déjà "
+            "posée sur un déclencheur existant, sans reconstruire toute la "
+            "règle — after_id peut désigner N'IMPORTE QUEL bloc de la "
+            "chaîne, pas forcément le dernier : une suite déjà présente "
+            "après ce bloc passe derrière la nouvelle action plutôt que "
+            "d'être remplacée."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "after_id": {"type": "string"},
+                "action": _LEAF_ACTION_SCHEMA,
+            },
+            "required": ["object_id", "after_id", "action"],
+        },
+    },
+    {
+        "name": "append_action_to_screen_trigger",
+        "description": (
+            "Équivalent d'append_action_to_trigger pour un déclencheur D'ÉCRAN "
+            "(voir set_screen_triggers), sur l'écran en cours — after_id peut "
+            "désigner N'IMPORTE QUEL bloc de la chaîne, pas forcément le "
+            "dernier."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "after_id": {"type": "string"},
+                "action": _LEAF_ACTION_SCHEMA,
+            },
+            "required": ["after_id", "action"],
+        },
+    },
+    {
+        "name": "remove_trigger_action",
+        "description": (
+            "Retire UNE action précise (leaf_id) d'un déclencheur d'OBJET, où "
+            "qu'elle soit dans l'arbre (feuille directe, maillon d'une chaîne "
+            '"then", sous-action d\'un "interagir", ou branche d\'une '
+            '"condition"). Si c\'était la SEULE action de la règle, la règle '
+            'entière disparaît ; si elle avait une suite "then", celle-ci '
+            "prend sa place."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "leaf_id": {"type": "string"},
+            },
+            "required": ["object_id", "leaf_id"],
+        },
+    },
+    {
+        "name": "remove_screen_trigger_action",
+        "description": "Équivalent de remove_trigger_action pour un déclencheur D'ÉCRAN.",
+        "input_schema": {
+            "type": "object",
+            "properties": {"leaf_id": {"type": "string"}},
+            "required": ["leaf_id"],
+        },
+    },
+    {
+        "name": "move_trigger_action",
+        "description": (
+            "Déplace une action précise (leaf_id) d'un cran vers le haut "
+            '("up") ou le bas ("down") DANS SA PROPRE CHAÎNE "then", pour '
+            "un déclencheur d'OBJET — jamais au-delà de sa branche de "
+            "condition/sous-action interagir."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "object_id": {"type": "integer"},
+                "leaf_id": {"type": "string"},
+                "direction": {"type": "string", "enum": ["up", "down"]},
+            },
+            "required": ["object_id", "leaf_id", "direction"],
+        },
+    },
+    {
+        "name": "move_screen_trigger_action",
+        "description": "Équivalent de move_trigger_action pour un déclencheur D'ÉCRAN.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "leaf_id": {"type": "string"},
+                "direction": {"type": "string", "enum": ["up", "down"]},
+            },
+            "required": ["leaf_id", "direction"],
+        },
+    },
+]
+
+
+def _clamp_to_camera(
+    slug: str, screen_id: int, kind: str | None, x: float, y: float, width: float, height: float
+) -> tuple[float, float, str | None]:
+    """Le placement précis par coordonnées s'est montré peu fiable pour
+    l'IA malgré des instructions explicites ET un avertissement dans le
+    résultat de l'outil (bug observé à répétition — l'IA n'arrivait
+    toujours pas à replacer l'objet correctement, épuisant même parfois
+    tout le budget d'itérations sans jamais y arriver). Plutôt que de
+    compter sur elle pour se corriger, le moteur RAMÈNE automatiquement
+    tout objet (hors "fond", volontairement plus grand que la caméra —
+    voir screens.resolve_scene_world_size) à l'intérieur du cadre visible
+    dès cet appel : garantit un résultat correct du premier coup, sans
+    aller-retour. Renvoie (x, y, note) — note est None si aucun
+    ajustement n'était nécessaire."""
+    if kind == "fond":
+        return x, y, None
+    screen = screens.get_screen(slug, screen_id)
+    if not screen:
+        return x, y, None
+    scene_width, scene_height = screen["scene_width"], screen["scene_height"]
+    clamped_x = min(max(x, 0), max(0, scene_width - width))
+    clamped_y = min(max(y, 0), max(0, scene_height - height))
+    if (clamped_x, clamped_y) == (x, y):
+        return x, y, None
+    note = (
+        f"Position ajustée automatiquement de ({int(x)},{int(y)}) à "
+        f"({int(clamped_x)},{int(clamped_y)}) pour rester dans le cadre visible par la "
+        f"caméra (0,0)-({scene_width},{scene_height})."
+    )
+    return clamped_x, clamped_y, note
+
+
+def _dispatch_add_scene_object(
+    slug: str,
+    screen_id: int,
+    user_id: int,
+    kind: str,
+    forge_character: str | None = None,
+    background_slug: str | None = None,
+    image_url: str | None = None,
+) -> dict[str, Any]:
+    # Même garde que la galerie manuelle (core/sprite_gate.py) — un
+    # compte non-admin ne doit pas pouvoir poser un sprite/fond
+    # admin-only via l'IA alors que la galerie de l'éditeur ne les lui
+    # propose déjà pas.
+    user = auth.get_user_by_id(user_id)
+    is_admin = bool(user and user["role"] == "admin")
+    if forge_character in screens.ADMIN_ONLY_CHARACTER_SLUGS and not is_admin:
+        forge_character = None
+    if background_slug in screens.ADMIN_ONLY_BACKGROUND_SLUGS and not is_admin:
+        background_slug = None
+    # screens.add_scene_object ignore SILENCIEUSEMENT un slug invalide
+    # (comportement voulu pour l'éditeur manuel, où un select HTML ne
+    # peut de toute façon proposer qu'un slug valide) — mais Claude, lui,
+    # peut inventer/mal orthographier une valeur malgré l'enum du schéma
+    # (pas de strict:true ici, voir ai/chat.py). Sans ce contrôle,
+    # l'outil "réussissait" en silence et Ruby annonçait un fond/
+    # personnage posé qui n'apparaissait jamais (bug corrigé). Lever une
+    # erreur ici la remonte comme résultat d'outil (voir ai/chat.py) :
+    # Claude la VOIT et peut se corriger dans le même tour.
+    if forge_character and forge_character not in screens.SPRITE_LIBRARY:
+        raise ValueError(f"forge_character inconnu : {forge_character!r} (voir la liste enum du tool)")
+    if background_slug and background_slug not in screens.BACKGROUND_LIBRARY:
+        raise ValueError(f"background_slug inconnu : {background_slug!r} (voir la liste enum du tool)")
+    object_id = screens.add_scene_object(
+        slug,
+        screen_id,
+        kind=kind,
+        forge_character=forge_character,
+        background_slug=background_slug,
+        image_url=image_url,
+    )
+    obj = screens.get_scene_object(slug, object_id)
+    obj = db.assert_not_none(obj, "object_id vient d'etre cree par screens.add_scene_object juste au-dessus")
+    # Position par défaut (100,100, voir ensure_scene_schema.py) déjà
+    # posée par screens.add_scene_object — reste passée par le même
+    # garde-fou pour rester correcte même si ce défaut changeait un jour.
+    clamped_x, clamped_y, note = _clamp_to_camera(
+        slug, screen_id, kind, obj["x"], obj["y"], obj["width"], obj["height"]
+    )
+    if note:
+        screens.update_scene_object_geometry(slug, object_id, clamped_x, clamped_y, obj["width"], obj["height"])
+    result: dict[str, Any] = {"object_id": object_id}
+    if note:
+        result["note"] = note
+    return result
+
+
+def _dispatch_set_object_geometry(
+    slug: str, screen_id: int, user_id: int, object_id: int, x: float, y: float, width: float, height: float
+) -> dict[str, Any]:
+    obj = screens.get_scene_object(slug, object_id)
+    x, y, note = _clamp_to_camera(slug, screen_id, obj["kind"] if obj else None, x, y, width, height)
+    screens.update_scene_object_geometry(slug, object_id, x, y, width, height)
+    result: dict[str, Any] = {"ok": True}
+    if note:
+        result["note"] = note
+    return result
+
+
+def _dispatch_set_object_name(slug: str, screen_id: int, user_id: int, object_id: int, name: str) -> dict[str, Any]:
+    screens.set_scene_object_name(slug, object_id, name)
+    return {"ok": True}
+
+
+def _dispatch_set_object_role(slug: str, screen_id: int, user_id: int, object_id: int, role: str) -> dict[str, Any]:
+    screens.set_scene_object_role(slug, object_id, role)
+    return {"ok": True}
+
+
+def _dispatch_set_object_collision(
+    slug: str,
+    screen_id: int,
+    user_id: int,
+    object_id: int,
+    enabled: bool = True,
+    shape: str = "rectangle",
+    width: float | None = None,
+    height: float | None = None,
+    offset_x: float = 0,
+    offset_y: float = 0,
+) -> dict[str, Any]:
+    # Même forme que routes/scenes/scene_object_collision.py (remplacement
+    # complet des réglages, jamais un merge partiel).
+    settings: dict[str, Any] = {
+        "enabled": bool(enabled),
+        "shape": shape if shape in _COLLISION_SHAPES else "rectangle",
+        "width": width,
+        "height": height,
+        "offset_x": offset_x or 0,
+        "offset_y": offset_y or 0,
+    }
+    screens.set_scene_object_collision(slug, object_id, settings)
+    return {"ok": True}
+
+
+def _dispatch_set_quiz_box_config(
+    slug: str,
+    screen_id: int,
+    user_id: int,
+    object_id: int,
+    fullscreen: bool = False,
+    timer_mode: str = "aucun",
+    timer_seconds: int = 20,
+    dialog_template: str = "defaut",
+    page_template: str = "classique",
+) -> dict[str, Any]:
+    # Même forme que screens.set_scene_object_quiz_config (remplacement
+    # complet des réglages, jamais un merge partiel) — screens.py sanitize
+    # de toute façon toute valeur hors énumération, ce garde-fou ici sert
+    # juste à ne jamais transmettre None à sanitize_quiz_box_config.
+    # dialog_template/page_template sont conservés INDÉPENDAMMENT (voir
+    # screens/rendering/quiz_box_config.py) : Ruby peut en régler un seul
+    # sans jamais écraser l'autre.
+    config: dict[str, Any] = {
+        "fullscreen": bool(fullscreen),
+        "timer_mode": timer_mode if timer_mode in _QUIZ_BOX_TIMER_MODES else "aucun",
+        "timer_seconds": timer_seconds or 20,
+        "dialog_template": dialog_template if dialog_template in _QUIZ_BOX_DIALOG_TEMPLATES else "defaut",
+        "page_template": page_template if page_template in _QUIZ_BOX_PAGE_TEMPLATES else "classique",
+    }
+    screens.set_scene_object_quiz_config(slug, object_id, config)
+    return {"ok": True}
+
+
+def _dispatch_create_global_variable(
+    slug: str,
+    screen_id: int,
+    user_id: int,
+    name: str,
+    var_type: str = "texte",
+    default_value: str = "",
+    per_player: bool = True,
+) -> dict[str, Any]:
+    variable_id = db.create_global_variable(
+        slug, name, var_type=var_type, default_value=default_value, per_player=per_player
+    )
+    return {"variable_id": variable_id}
+
+
+def _dispatch_set_collision_rules(
+    slug: str, screen_id: int, user_id: int, object_id: int, rules: Any
+) -> dict[str, Any]:
+    sanitized = screens.sanitize_collision_rules(rules)
+    screens.set_scene_object_collision_rules(slug, object_id, sanitized)
+    return {"ok": True, "rules": sanitized}
+
+
+def _dispatch_append_action_to_trigger(
+    slug: str, screen_id: int, user_id: int, object_id: int, after_id: str, action: dict[str, Any]
+) -> dict[str, Any]:
+    ok = screens.append_action_to_trigger(slug, object_id, after_id, action)
+    return {"ok": ok}
+
+
+def _dispatch_set_screen_triggers(slug: str, screen_id: int, user_id: int, rules: Any) -> dict[str, Any]:
+    sanitized = screens.sanitize_screen_triggers(rules)
+    screens.set_screen_triggers(slug, screen_id, sanitized)
+    return {"ok": True, "rules": sanitized}
+
+
+def _dispatch_append_action_to_screen_trigger(
+    slug: str, screen_id: int, user_id: int, after_id: str, action: dict[str, Any]
+) -> dict[str, Any]:
+    ok = screens.append_action_to_screen_trigger(slug, screen_id, after_id, action)
+    return {"ok": ok}
+
+
+def _dispatch_remove_trigger_action(
+    slug: str, screen_id: int, user_id: int, object_id: int, leaf_id: str
+) -> dict[str, Any]:
+    ok = screens.remove_action_from_trigger(slug, object_id, leaf_id)
+    return {"ok": ok}
+
+
+def _dispatch_remove_screen_trigger_action(slug: str, screen_id: int, user_id: int, leaf_id: str) -> dict[str, Any]:
+    ok = screens.remove_action_from_screen_trigger(slug, screen_id, leaf_id)
+    return {"ok": ok}
+
+
+def _dispatch_move_trigger_action(
+    slug: str, screen_id: int, user_id: int, object_id: int, leaf_id: str, direction: str
+) -> dict[str, Any]:
+    ok = screens.move_action_in_trigger(slug, object_id, leaf_id, direction)
+    return {"ok": ok}
+
+
+def _dispatch_move_screen_trigger_action(
+    slug: str, screen_id: int, user_id: int, leaf_id: str, direction: str
+) -> dict[str, Any]:
+    ok = screens.move_action_in_screen_trigger(slug, screen_id, leaf_id, direction)
+    return {"ok": ok}
+
+
+def _dispatch_add_generated_image(slug: str, screen_id: int, user_id: int, kind: str, prompt: str) -> dict[str, Any]:
+    """Scenario -> "Mes assets" (auth.save_user_asset, source="ia") ->
+    posée sur l'écran via LE MÊME chemin que Phase 1
+    (screens.add_scene_object(image_url=...)) — jamais un chemin
+    parallèle. Toute erreur (Scenario mal configuré, timeout, échec)
+    remonte comme un résultat d'outil normal, voir ai/chat.py."""
+    image_url = generate_image_url(prompt)
+    downloaded = requests.get(image_url, timeout=60)
+    downloaded.raise_for_status()
+    ext = os.path.splitext(image_url.split("?")[0])[1] or ".png"
+    asset_id, filename = auth.save_user_asset(user_id, downloaded.content, ext, original_name=prompt[:80], source="ia")
+    served_url = url_for("serve_user_asset", user_id=user_id, filename=filename)
+    object_id = screens.add_scene_object(slug, screen_id, kind=kind, image_url=served_url)
+    return {"object_id": object_id, "asset_id": asset_id}
+
+
+_DISPATCH: dict[str, Callable[..., dict[str, Any]]] = {
+    "add_scene_object": _dispatch_add_scene_object,
+    "set_object_geometry": _dispatch_set_object_geometry,
+    "set_object_name": _dispatch_set_object_name,
+    "set_object_role": _dispatch_set_object_role,
+    "set_object_collision": _dispatch_set_object_collision,
+    "set_quiz_box_config": _dispatch_set_quiz_box_config,
+    "create_global_variable": _dispatch_create_global_variable,
+    "set_collision_rules": _dispatch_set_collision_rules,
+    "append_action_to_trigger": _dispatch_append_action_to_trigger,
+    "set_screen_triggers": _dispatch_set_screen_triggers,
+    "append_action_to_screen_trigger": _dispatch_append_action_to_screen_trigger,
+    "remove_trigger_action": _dispatch_remove_trigger_action,
+    "remove_screen_trigger_action": _dispatch_remove_screen_trigger_action,
+    "move_trigger_action": _dispatch_move_trigger_action,
+    "move_screen_trigger_action": _dispatch_move_screen_trigger_action,
+    "add_generated_image": _dispatch_add_generated_image,
+}
+
+
+def dispatch_tool(
+    slug: str, screen_id: int, user_id: int, tool_name: str, tool_input: dict[str, Any]
+) -> dict[str, Any]:
+    """Point d'entrée UNIQUE utilisé par la boucle tool-use (Phase 2) —
+    lève KeyError pour un nom d'outil inconnu (jamais silencieux : un tool
+    annoncé par TOOLS mais absent d'ici serait un bug de ce module, pas
+    une entrée utilisateur à tolérer). `user_id` : nécessaire pour "Mes
+    assets" (scopé par compte, voir add_generated_image ci-dessus) —
+    ignoré par les autres outils, qui n'agissent que sur l'écran/l'objet."""
+    handler = _DISPATCH[tool_name]
+    return handler(slug, screen_id, user_id, **tool_input)

app.py

@@ -15,19 +15,23 @@ Lance un serveur web local. Fonctionnalités construites pour l'instant
      une relation existante.
 """
 
+import os
 import threading
 import webbrowser
 
-from core.flask_app import app
-from core import jinja_filters  # noqa: F401 - enregistre les filtres Jinja
 import routes  # noqa: F401 - enregistre toutes les routes sur `app`
-from core import auth_guard  # noqa: F401 - enregistre la garde de connexion (après les routes)
+from core import (
-from core import csrf  # noqa: F401 - enregistre csrf_token() comme variable globale Jinja
+    auth_guard,  # noqa: F401 - enregistre la garde de connexion (après les routes)
-from core import csrf_guard  # noqa: F401 - enregistre la vérification du jeton CSRF
+    csrf,  # noqa: F401 - enregistre csrf_token() comme variable globale Jinja
-from core import recovery_codes_flash  # noqa: F401 - enregistre pop_recovery_codes() comme variable globale Jinja
+    csrf_guard,  # noqa: F401 - enregistre la vérification du jeton CSRF
+    db_teardown_guard,  # noqa: F401 - enregistre la fermeture des connexions SQLite fuitées
+    jinja_filters,  # noqa: F401 - enregistre les filtres Jinja
+    recovery_codes_flash,  # noqa: F401 - enregistre pop_recovery_codes() comme variable globale Jinja
+)
+from core.flask_app import app
 
 
-def _open_browser():
+def _open_browser() -> None:
     webbrowser.open("http://127.0.0.1:5050/")
 
 
@@ -41,4 +45,9 @@ if __name__ == "__main__":
     # l'éditeur de scène "vide" le temps que les images finissent par
     # arriver l'une après l'autre — un rechargement normal, servi surtout
     # depuis le cache navigateur, le cachait).
-    app.run(host="127.0.0.1", port=5050, debug=True, use_reloader=False, threaded=True)
+    # debug : jamais actif par defaut (Bandit B201 - le debogueur Werkzeug
+    # permet l'execution de code arbitraire) — activable en local via
+    # FORGE_DEBUG=1 dans .env, jamais utilise en production (gunicorn y
+    # sert app:app directement, ce bloc __main__ n'y tourne pas).
+    debug = os.environ.get("FORGE_DEBUG") == "1"
+    app.run(host="127.0.0.1", port=5050, debug=debug, use_reloader=False, threaded=True)

auth/__init__.py

@@ -4,46 +4,94 @@ create_user.py pour le détail des règles. Base SQLite entièrement séparée
 de db/ (une base par JEU) : ces comptes n'appartiennent à aucun jeu, ils
 en POSSÈDENT un (project_slug)."""
 
+from .confirm_totp import confirm_totp
 from .connection import users_db_path
+from .count_admins import count_admins
+from .create_user import UserCreationError, create_user
+from .create_user_asset import create_user_asset
+from .delete_user import delete_user
+from .delete_user_asset import delete_user_asset
 from .ensure_schema import ensure_users_schema
-from .is_first_user import is_first_user
+from .ensure_user_assets_schema import ensure_user_assets_schema
-from .create_user import create_user, UserCreationError
+from .get_user_asset import get_user_asset
 from .get_user_by_email import get_user_by_email
 from .get_user_by_id import get_user_by_id
-from .verify_password import verify_password
+from .image_dimensions import image_dimensions
-from .confirm_totp import confirm_totp
+from .is_first_user import is_first_user
-from .verify_totp import verify_totp
+from .list_user_assets import list_user_assets
-from .set_project_slug import set_project_slug
-from .password_strength import password_strength, MIN_SCORE_REQUIRED
-from .totp_qrcode_svg import totp_provisioning_uri, totp_qrcode_svg
-from .rate_limit import lockout_minutes_for, seconds_locked_remaining, lockout_message
-from .record_failed_attempt import record_failed_attempt
-from .reset_failed_attempts import reset_failed_attempts
-from .recovery_codes import generate_recovery_codes, verify_recovery_code
-from .set_password import set_password
 from .password_reset import (
-    create_password_reset_token, get_user_id_for_valid_token, consume_password_reset_token,
     TOKEN_TTL_MINUTES,
+    consume_password_reset_token,
+    create_password_reset_token,
+    get_user_id_for_valid_token,
 )
-from .send_email import send_password_reset_email, EmailNotConfiguredError
+from .password_strength import MIN_SCORE_REQUIRED, password_strength
+from .rate_limit import lockout_message, lockout_minutes_for, seconds_locked_remaining
+from .record_failed_attempt import record_failed_attempt
+from .recovery_codes import generate_recovery_codes, verify_recovery_code
+from .reset_failed_attempts import reset_failed_attempts
+from .save_user_asset import save_user_asset
+from .send_email import EmailNotConfiguredError, send_password_reset_email
+from .set_password import set_password
+from .set_project_slug import set_project_slug
+from .totp_qrcode_svg import totp_provisioning_uri, totp_qrcode_svg
+from .update_email import EmailUpdateError, update_email
 from .update_profile import update_profile
-from .count_admins import count_admins
+from .update_user_asset_scene_kind import update_user_asset_scene_kind
-from .delete_user import delete_user
+from .user_asset_kind import user_asset_kind
-from .update_email import update_email, EmailUpdateError
+from .user_assets_dir import user_assets_dir
+from .validate_audio_duration import MAX_AUDIO_SECONDS, validate_audio_duration
+from .validate_video_duration import MAX_VIDEO_SECONDS, validate_video_duration
+from .verify_password import verify_password
+from .verify_totp import verify_totp
 
 __all__ = [
-    "users_db_path", "ensure_users_schema", "is_first_user",
+    "users_db_path",
-    "create_user", "UserCreationError",
+    "ensure_users_schema",
-    "get_user_by_email", "get_user_by_id",
+    "is_first_user",
-    "verify_password", "confirm_totp", "verify_totp", "set_project_slug",
+    "create_user",
-    "password_strength", "MIN_SCORE_REQUIRED",
+    "UserCreationError",
-    "totp_provisioning_uri", "totp_qrcode_svg",
+    "get_user_by_email",
-    "lockout_minutes_for", "seconds_locked_remaining", "lockout_message",
+    "get_user_by_id",
-    "record_failed_attempt", "reset_failed_attempts",
+    "verify_password",
-    "generate_recovery_codes", "verify_recovery_code",
+    "confirm_totp",
-    "set_password", "create_password_reset_token", "get_user_id_for_valid_token",
+    "verify_totp",
-    "consume_password_reset_token", "TOKEN_TTL_MINUTES",
+    "set_project_slug",
-    "send_password_reset_email", "EmailNotConfiguredError",
+    "password_strength",
-    "update_profile", "count_admins", "delete_user",
+    "MIN_SCORE_REQUIRED",
-    "update_email", "EmailUpdateError",
+    "totp_provisioning_uri",
+    "totp_qrcode_svg",
+    "lockout_minutes_for",
+    "seconds_locked_remaining",
+    "lockout_message",
+    "record_failed_attempt",
+    "reset_failed_attempts",
+    "generate_recovery_codes",
+    "verify_recovery_code",
+    "set_password",
+    "create_password_reset_token",
+    "get_user_id_for_valid_token",
+    "consume_password_reset_token",
+    "TOKEN_TTL_MINUTES",
+    "send_password_reset_email",
+    "EmailNotConfiguredError",
+    "update_profile",
+    "count_admins",
+    "delete_user",
+    "update_email",
+    "EmailUpdateError",
+    "ensure_user_assets_schema",
+    "user_assets_dir",
+    "create_user_asset",
+    "list_user_assets",
+    "get_user_asset",
+    "delete_user_asset",
+    "save_user_asset",
+    "user_asset_kind",
+    "validate_audio_duration",
+    "MAX_AUDIO_SECONDS",
+    "validate_video_duration",
+    "MAX_VIDEO_SECONDS",
+    "image_dimensions",
+    "update_user_asset_scene_kind",
 ]

auth/confirm_totp.py

@@ -1,7 +1,7 @@
 from .connection import connect
 
 
-def confirm_totp(user_id):
+def confirm_totp(user_id: int) -> None:
     conn = connect()
     conn.execute("UPDATE _users SET totp_confirmed = 1 WHERE id = ?", (user_id,))
     conn.commit()

auth/connection.py

@@ -8,6 +8,7 @@ tests/conftest.py positionne FORGE_USERS_DB_PATH vers un fichier temporaire
 avant de faire tourner la suite, pour ne jamais toucher à la vraie base de
 comptes (data/users.db) ni dépendre d'un état "premier compte = admin" déjà
 consommé par un run précédent."""
+
 import os
 import sqlite3
 
@@ -15,11 +16,11 @@ _BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 DEFAULT_USERS_DB_PATH = os.path.join(_BASE_DIR, "data", "users.db")
 
 
-def users_db_path():
+def users_db_path() -> str:
     return os.environ.get("FORGE_USERS_DB_PATH") or DEFAULT_USERS_DB_PATH
 
 
-def connect():
+def connect() -> sqlite3.Connection:
     path = users_db_path()
     os.makedirs(os.path.dirname(path), exist_ok=True)
     conn = sqlite3.connect(path, timeout=10)

auth/count_admins.py

@@ -1,8 +1,8 @@
 from .connection import connect
 
 
-def count_admins():
+def count_admins() -> int:
     conn = connect()
-    n = conn.execute("SELECT COUNT(*) AS n FROM _users WHERE role = 'admin'").fetchone()["n"]
+    n = int(conn.execute("SELECT COUNT(*) AS n FROM _users WHERE role = 'admin'").fetchone()["n"])
     conn.close()
     return n

auth/create_user.py

@@ -1,9 +1,9 @@
 import pyotp
 from werkzeug.security import generate_password_hash
 
-from .ensure_schema import ensure_users_schema
 from .connection import connect
 from .email_validation import is_valid_email
+from .ensure_schema import ensure_users_schema
 from .get_user_by_email import get_user_by_email
 from .is_first_user import is_first_user
 from .password_strength import password_strength
@@ -14,7 +14,7 @@ class UserCreationError(Exception):
     dans le formulaire d'inscription) — jamais un détail SQL/technique."""
 
 
-def create_user(email, password, nom, prenom):
+def create_user(email: str | None, password: str | None, nom: str | None, prenom: str | None) -> int:
     """Crée un compte : mot de passe fort (auth/password_strength.py) et
     2FA (TOTP) rendus obligatoires — le secret est généré ici mais
     totp_confirmed reste à 0 tant que confirm_totp() n'a pas vérifié un
@@ -26,6 +26,7 @@ def create_user(email, password, nom, prenom):
     email = (email or "").strip().lower()
     nom = (nom or "").strip()
     prenom = (prenom or "").strip()
+    password = password or ""
     if not is_valid_email(email):
         raise UserCreationError("Adresse email invalide.")
     if not nom or not prenom:
@@ -44,7 +45,7 @@ def create_user(email, password, nom, prenom):
            VALUES (?, ?, ?, ?, ?, ?, 0)""",
         (email, generate_password_hash(password), nom, prenom, role, totp_secret),
     )
-    user_id = conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"]
+    user_id = int(conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"])
     conn.commit()
     conn.close()
     return user_id

auth/create_user_asset.py

@@ -0,0 +1,33 @@
+from .connection import connect
+from .ensure_user_assets_schema import ensure_user_assets_schema
+
+
+def create_user_asset(
+    user_id: int,
+    filename: str,
+    original_name: str | None = None,
+    source: str = "upload",
+    scene_kind: str | None = None,
+) -> int:
+    """Enregistre une ligne "Mes assets" pour un fichier déjà écrit sur
+    disque (voir user_assets_dir.py) — le fichier lui-même est écrit par
+    l'appelant (route d'upload, ou plus tard la génération IA), cette
+    fonction ne fait que la partie base de données, comme
+    db.create_global_variable pour le reste du moteur.
+
+    scene_kind ("decor"/"fond", images uniquement — voir
+    routes/scenes/scene_edit_view.py) : décide comment un CLIC sur la
+    tuile pose l'objet (screens/scenes/add_scene_object.py), demande
+    explicite "un bouton d'import séparé pour les images de fond et les
+    objets" — sans distinction, toute image "Mes assets" ne pouvait être
+    posée qu'en "decor", jamais comme fond."""
+    ensure_user_assets_schema()
+    conn = connect()
+    conn.execute(
+        "INSERT INTO _user_assets (user_id, filename, original_name, source, scene_kind) VALUES (?, ?, ?, ?, ?)",
+        (user_id, filename, original_name, source, scene_kind),
+    )
+    asset_id = int(conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"])
+    conn.commit()
+    conn.close()
+    return asset_id

auth/delete_user.py

@@ -1,7 +1,7 @@
 from .connection import connect
 
 
-def delete_user(user_id):
+def delete_user(user_id: int) -> None:
     """Supprime le compte et tout ce qui lui est directement rattaché
     (codes de récupération, jetons de réinitialisation encore en cours) —
     le dossier de projet, lui, est géré par l'appelant (voir

auth/delete_user_asset.py

@@ -0,0 +1,25 @@
+import os
+
+from .connection import connect
+from .ensure_user_assets_schema import ensure_user_assets_schema
+from .user_assets_dir import user_assets_dir
+
+
+def delete_user_asset(asset_id: int, user_id: int) -> bool:
+    """N'efface que si asset_id APPARTIENT à user_id (jamais fournie par
+    l'appelant sans vérification — voir get_user_asset.py) : renvoie False
+    sans rien faire sinon, plutôt que de lever une erreur, même patron que
+    screens.delete_scene_object pour un id introuvable."""
+    ensure_user_assets_schema()
+    conn = connect()
+    row = conn.execute("SELECT filename FROM _user_assets WHERE id = ? AND user_id = ?", (asset_id, user_id)).fetchone()
+    if not row:
+        conn.close()
+        return False
+    conn.execute("DELETE FROM _user_assets WHERE id = ?", (asset_id,))
+    conn.commit()
+    conn.close()
+    path = os.path.join(user_assets_dir(user_id), row["filename"])
+    if os.path.exists(path):
+        os.remove(path)
+    return True

auth/email_validation.py

@@ -3,5 +3,5 @@ import re
 EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
 
 
-def is_valid_email(email):
+def is_valid_email(email: str | None) -> bool:
     return bool(EMAIL_RE.match((email or "").strip()))

auth/ensure_schema.py

@@ -1,7 +1,7 @@
 from .connection import connect
 
 
-def ensure_users_schema():
+def ensure_users_schema() -> None:
     conn = connect()
     conn.executescript(
         """

auth/ensure_user_assets_schema.py

@@ -0,0 +1,34 @@
+from .connection import connect
+
+
+def ensure_user_assets_schema() -> None:
+    """ "Mes assets" (voir user_assets_dir.py) : une image appartient à un
+    COMPTE, jamais à un projet — table dans la base de comptes partagée
+    (auth/connection.py), pas dans le game.db d'un jeu (db/connection.py),
+    pour rester utilisable d'un projet à l'autre du même compte."""
+    conn = connect()
+    conn.executescript(
+        """
+        CREATE TABLE IF NOT EXISTS _user_assets (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            user_id INTEGER NOT NULL,
+            filename TEXT NOT NULL,
+            original_name TEXT,
+            source TEXT NOT NULL DEFAULT 'upload' CHECK (source IN ('upload', 'ia')),
+            created_at TEXT DEFAULT CURRENT_TIMESTAMP
+        );
+        """
+    )
+    asset_cols = {r["name"] for r in conn.execute("PRAGMA table_info(_user_assets)").fetchall()}
+    if "scene_kind" not in asset_cols:
+        # Demande explicite : "un bouton d'import séparé pour les images
+        # de fond et les objets" — une image "Mes assets" est posée sur
+        # la scène TOUJOURS en kind="decor" jusqu'ici (voir
+        # screens/scenes/add_scene_object.py), impossible à utiliser comme
+        # "fond" (position/empilement différents, voir add_scene_object.py).
+        # NULL pour un son/une vidéo (n'a pas de sens) OU une image
+        # importée AVANT ce réglage (retombe sur "decor", comportement
+        # inchangé — voir routes/scenes/scene_edit_view.py).
+        conn.execute("ALTER TABLE _user_assets ADD COLUMN scene_kind TEXT")
+    conn.commit()
+    conn.close()

auth/get_user_asset.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from .connection import connect
+from .ensure_user_assets_schema import ensure_user_assets_schema
+
+
+def get_user_asset(asset_id: int) -> dict[str, Any] | None:
+    """Renvoie aussi user_id — indispensable pour vérifier la PROPRIÉTÉ
+    avant de servir/poser un asset (voir routes/assets/serve_user_asset.py,
+    routes/scenes/scene_object_add.py), même esprit que l'isolation par
+    propriétaire déjà en place sur les projets (core/auth_guard.py)."""
+    ensure_user_assets_schema()
+    conn = connect()
+    row = conn.execute(
+        "SELECT id, user_id, filename, original_name, source, created_at FROM _user_assets WHERE id = ?",
+        (asset_id,),
+    ).fetchone()
+    conn.close()
+    return dict(row) if row else None

auth/get_user_by_email.py

@@ -1,8 +1,10 @@
-from .ensure_schema import ensure_users_schema
+from typing import Any
+
 from .connection import connect
+from .ensure_schema import ensure_users_schema
 
 
-def get_user_by_email(email):
+def get_user_by_email(email: str | None) -> dict[str, Any] | None:
     ensure_users_schema()
     conn = connect()
     row = conn.execute("SELECT * FROM _users WHERE email = ?", ((email or "").strip().lower(),)).fetchone()

auth/get_user_by_id.py

@@ -1,8 +1,10 @@
-from .ensure_schema import ensure_users_schema
+from typing import Any
+
 from .connection import connect
+from .ensure_schema import ensure_users_schema
 
 
-def get_user_by_id(user_id):
+def get_user_by_id(user_id: int | None) -> dict[str, Any] | None:
     ensure_users_schema()
     if not user_id:
         return None

auth/image_dimensions.py

@@ -0,0 +1,70 @@
+import struct
+
+
+def image_dimensions(content: bytes) -> tuple[int, int] | None:
+    """Largeur/hauteur RÉELLES (en pixels) d'une image, lues directement
+    dans ses en-têtes — SANS dépendance externe (Pillow serait la solution
+    habituelle, mais un simple parsing des formats courants suffit ici et
+    évite d'ajouter une dépendance binaire lourde juste pour ça). Renvoie
+    None si le format n'est pas reconnu (ex. SVG vectoriel sans taille
+    fixe) — l'appelant retombe alors sur les valeurs par défaut du schéma
+    (voir screens/scenes/add_scene_object.py)."""
+    if content[:8] == b"\x89PNG\r\n\x1a\n":
+        if len(content) >= 24:
+            width, height = struct.unpack(">II", content[16:24])
+            return width, height
+        return None
+    if content[:6] in (b"GIF87a", b"GIF89a"):
+        if len(content) >= 10:
+            width, height = struct.unpack("<HH", content[6:10])
+            return width, height
+        return None
+    if content[:2] == b"BM":
+        if len(content) >= 26:
+            width, height = struct.unpack("<ii", content[18:26])
+            return abs(width), abs(height)
+        return None
+    if content[:4] == b"RIFF" and content[8:12] == b"WEBP":
+        return _webp_dimensions(content)
+    if content[:2] == b"\xff\xd8":
+        return _jpeg_dimensions(content)
+    return None
+
+
+def _webp_dimensions(content: bytes) -> tuple[int, int] | None:
+    chunk = content[12:16]
+    if chunk == b"VP8X" and len(content) >= 30:
+        width = 1 + (content[24] | (content[25] << 8) | (content[26] << 16))
+        height = 1 + (content[27] | (content[28] << 8) | (content[29] << 16))
+        return width, height
+    if chunk == b"VP8 " and len(content) >= 30:
+        width, height = struct.unpack("<HH", content[26:30])
+        return width & 0x3FFF, height & 0x3FFF
+    if chunk == b"VP8L" and len(content) >= 25:
+        b = content[21:25]
+        bits = b[0] | (b[1] << 8) | (b[2] << 16) | (b[3] << 24)
+        width = (bits & 0x3FFF) + 1
+        height = ((bits >> 14) & 0x3FFF) + 1
+        return width, height
+    return None
+
+
+def _jpeg_dimensions(content: bytes) -> tuple[int, int] | None:
+    i = 2
+    n = len(content)
+    while i + 9 < n:
+        if content[i] != 0xFF:
+            i += 1
+            continue
+        marker = content[i + 1]
+        if marker in (0xD8, 0x01) or 0xD0 <= marker <= 0xD7:
+            i += 2
+            continue
+        if marker == 0xD9:
+            break
+        seg_len = struct.unpack(">H", content[i + 2 : i + 4])[0]
+        if 0xC0 <= marker <= 0xCF and marker not in (0xC4, 0xC8, 0xCC):
+            height, width = struct.unpack(">HH", content[i + 5 : i + 9])
+            return width, height
+        i += 2 + seg_len
+    return None

auth/is_first_user.py

@@ -1,8 +1,8 @@
-from .ensure_schema import ensure_users_schema
 from .connection import connect
+from .ensure_schema import ensure_users_schema
 
 
-def is_first_user():
+def is_first_user() -> bool:
     """True s'il n'existe encore AUCUN compte — le tout premier compte créé
     devient automatiquement admin (voir create_user.py), pour ne jamais
     avoir besoin d'un mot de passe par défaut ou d'un script de bootstrap
@@ -11,4 +11,4 @@ def is_first_user():
     conn = connect()
     count = conn.execute("SELECT COUNT(*) AS c FROM _users").fetchone()["c"]
     conn.close()
-    return count == 0
+    return bool(count == 0)

auth/list_user_assets.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from .connection import connect
+from .ensure_user_assets_schema import ensure_user_assets_schema
+
+
+def list_user_assets(user_id: int) -> list[dict[str, Any]]:
+    """ "Mes assets" d'un compte, plus récent en premier — voir
+    templates/scene_edit.html, bloc "Mes assets" du panneau d'ajout
+    d'élément."""
+    ensure_user_assets_schema()
+    conn = connect()
+    rows = conn.execute(
+        "SELECT id, user_id, filename, original_name, source, scene_kind, created_at "
+        "FROM _user_assets WHERE user_id = ? ORDER BY id DESC",
+        (user_id,),
+    ).fetchall()
+    conn.close()
+    return [dict(row) for row in rows]

auth/password_reset.py

@@ -7,11 +7,11 @@ from .connection import connect
 TOKEN_TTL_MINUTES = 60
 
 
-def _hash_token(token):
+def _hash_token(token: str) -> str:
     return hashlib.sha256(token.encode("utf-8")).hexdigest()
 
 
-def create_password_reset_token(user_id):
+def create_password_reset_token(user_id: int) -> str:
     """Un seul jeton valide à la fois par utilisateur : en créer un
     nouveau invalide silencieusement tout jeu envoyé plus tôt (par
     exemple si l'utilisateur redemande un email parce que le premier
@@ -29,7 +29,7 @@ def create_password_reset_token(user_id):
     return token
 
 
-def get_user_id_for_valid_token(token):
+def get_user_id_for_valid_token(token: str | None) -> int | None:
     if not token:
         return None
     conn = connect()
@@ -42,10 +42,10 @@ def get_user_id_for_valid_token(token):
         return None
     if datetime.fromisoformat(row["expires_at"]) < datetime.now(timezone.utc):
         return None
-    return row["user_id"]
+    return int(row["user_id"])
 
 
-def consume_password_reset_token(token):
+def consume_password_reset_token(token: str) -> None:
     conn = connect()
     conn.execute(
         "UPDATE _password_reset_tokens SET used_at = CURRENT_TIMESTAMP WHERE token_hash = ?",

auth/password_strength.py

@@ -1,11 +1,12 @@
 import re
+from typing import Any, Callable
 
 # Mêmes règles des deux côtés (ici pour le refus serveur, en JS dans
 # templates/auth/register.html pour le schéma visuel qui guide la saisie
 # en temps réel) — un mot de passe REFUSÉ côté serveur doit toujours
 # correspondre à une jauge/coche déjà rouge côté client, jamais une
 # surprise après coup.
-_CHECKS = [
+_CHECKS: list[tuple[str, str, Callable[[str], bool]]] = [
     ("longueur", "Au moins 8 caractères", lambda p: len(p) >= 8),
     ("majuscule", "Une majuscule", lambda p: re.search(r"[A-Z]", p) is not None),
     ("minuscule", "Une minuscule", lambda p: re.search(r"[a-z]", p) is not None),
@@ -19,7 +20,7 @@ _CHECKS = [
 MIN_SCORE_REQUIRED = 4
 
 
-def password_strength(password):
+def password_strength(password: str | None) -> dict[str, Any]:
     """Renvoie {"score": 0-5, "checks": [{"key","label","ok"}, ...],
     "valid": bool} — jamais None, un mot de passe vide obtient juste un
     score de 0 (toutes les règles échouent), pas une erreur."""

auth/rate_limit.py

@@ -3,24 +3,26 @@
 que soit l'étape attaquée) : 3 essais libres, puis un temps d'attente qui
 double à chaque échec supplémentaire (5 min, 10, 20, 40...), plafonné à
 1h. Remis à zéro dès une connexion réussie (voir reset_failed_attempts)."""
+
 import math
-from datetime import datetime, timedelta, timezone
+from datetime import datetime, timezone
+from typing import Any
 
 _FREE_ATTEMPTS = 3
 _FIRST_LOCKOUT_MINUTES = 5
 _MAX_LOCKOUT_MINUTES = 60
 
 
-def lockout_minutes_for(failed_attempts):
+def lockout_minutes_for(failed_attempts: int) -> int:
     """0 tant qu'on est dans les 3 essais libres ; sinon 5 * 2^n, plafonné
     à 60 — jamais négatif, jamais None."""
     if failed_attempts <= _FREE_ATTEMPTS:
         return 0
     exponent = failed_attempts - _FREE_ATTEMPTS - 1
-    return min(_FIRST_LOCKOUT_MINUTES * (2 ** exponent), _MAX_LOCKOUT_MINUTES)
+    return min(int(_FIRST_LOCKOUT_MINUTES * (2**exponent)), _MAX_LOCKOUT_MINUTES)
 
 
-def _parse(dt_str):
+def _parse(dt_str: str | None) -> datetime | None:
     if not dt_str:
         return None
     try:
@@ -29,7 +31,7 @@ def _parse(dt_str):
         return None
 
 
-def lockout_message(seconds_remaining):
+def lockout_message(seconds_remaining: float) -> str:
     """Message affiché tel quel dans le formulaire — arrondi à la minute
     supérieure (jamais "0 minute" alors qu'il en reste un peu, jamais un
     compte de secondes qui oblige à recharger sans arrêt pour voir si
@@ -39,7 +41,7 @@ def lockout_message(seconds_remaining):
     return f"Trop de tentatives. Réessaie dans {minutes} {unit}."
 
 
-def seconds_locked_remaining(user):
+def seconds_locked_remaining(user: dict[str, Any] | None) -> int:
     """> 0 si le compte est actuellement verrouillé (temps restant, en
     secondes, arrondi au-dessus pour ne jamais afficher "0 minute" alors
     qu'il en reste réellement un peu) ; 0 sinon."""

auth/record_failed_attempt.py

@@ -4,7 +4,7 @@ from .connection import connect
 from .rate_limit import lockout_minutes_for
 
 
-def record_failed_attempt(user_id):
+def record_failed_attempt(user_id: int) -> int:
     """Incrémente le compteur d'échecs de CE compte et, une fois passé les
     3 essais libres, pose/allonge son verrouillage (voir rate_limit.py) —
     appelé sur un mot de passe OU un code 2FA incorrect, jamais sur un

auth/recovery_codes.py

@@ -7,11 +7,11 @@ from .connection import connect
 _CODE_COUNT = 10
 
 
-def _format_code(raw):
+def _format_code(raw: str) -> str:
-    return "-".join(raw[i:i + 4] for i in range(0, len(raw), 4))
+    return "-".join(raw[i : i + 4] for i in range(0, len(raw), 4))
 
 
-def generate_recovery_codes(user_id):
+def generate_recovery_codes(user_id: int) -> list[str]:
     """(Re)génère les codes de récupération 2FA d'un utilisateur : un
     nouvel appel invalide tout jeu de codes précédent (un seul jeu valide
     à la fois, pour ne jamais avoir à deviner lesquels tiennent encore).
@@ -21,7 +21,7 @@ def generate_recovery_codes(user_id):
     directement réutilisables."""
     conn = connect()
     conn.execute("DELETE FROM _recovery_codes WHERE user_id = ?", (user_id,))
-    codes = []
+    codes: list[str] = []
     for _ in range(_CODE_COUNT):
         code = _format_code(secrets.token_hex(6))
         codes.append(code)
@@ -34,7 +34,7 @@ def generate_recovery_codes(user_id):
     return codes
 
 
-def verify_recovery_code(user_id, code):
+def verify_recovery_code(user_id: int, code: str | None) -> bool:
     """Un code n'est utilisable qu'UNE SEULE FOIS (used_at) : consommé dès
     qu'il sert à une connexion réussie, pour qu'un code intercepté une
     fois (capture d'écran, historique du navigateur...) ne redonne pas un

auth/reset_failed_attempts.py

@@ -1,7 +1,7 @@
 from .connection import connect
 
 
-def reset_failed_attempts(user_id):
+def reset_failed_attempts(user_id: int) -> None:
     """Remet le compteur à zéro et lève tout verrouillage — appelé dès
     qu'une étape de connexion réussit (mot de passe validé ou code 2FA
     validé), pour ne jamais punir un utilisateur légitime qui s'est juste

auth/save_user_asset.py

@@ -0,0 +1,27 @@
+import os
+import uuid
+
+from .create_user_asset import create_user_asset
+from .user_assets_dir import user_assets_dir
+
+
+def save_user_asset(
+    user_id: int,
+    content: bytes,
+    ext: str,
+    original_name: str | None = None,
+    source: str = "upload",
+    scene_kind: str | None = None,
+) -> tuple[int, str]:
+    """Écrit `content` (bytes) sur disque + crée la ligne "Mes assets" —
+    factorisé pour être partagé par l'upload manuel
+    (routes/assets/upload_user_asset.py) ET la génération IA
+    (ai/tools.py::_dispatch_add_generated_image), jamais dupliqué entre
+    les deux. Renvoie (asset_id, filename)."""
+    filename = uuid.uuid4().hex + ext
+    asset_dir = user_assets_dir(user_id)
+    os.makedirs(asset_dir, exist_ok=True)
+    with open(os.path.join(asset_dir, filename), "wb") as f:
+        f.write(content)
+    asset_id = create_user_asset(user_id, filename, original_name=original_name, source=source, scene_kind=scene_kind)
+    return asset_id, filename

auth/send_email.py

@@ -4,6 +4,7 @@ Python. Configuré uniquement par variables d'environnement (SMTP_HOST,
 SMTP_PORT, SMTP_USER, SMTP_PASSWORD, SMTP_FROM) : ce module ne connaît et
 ne stocke jamais le mot de passe SMTP en dur, à définir sur le poste/
 serveur qui fait tourner l'appli."""
+
 import os
 import smtplib
 from email.mime.text import MIMEText
@@ -19,7 +20,7 @@ class EmailNotConfiguredError(Exception):
     qu'il doit finir de configurer son SMTP."""
 
 
-def send_email(to_email, subject, body):
+def send_email(to_email: str, subject: str, body: str) -> None:
     host = os.environ.get("SMTP_HOST")
     port = int(os.environ.get("SMTP_PORT", "587"))
     user = os.environ.get("SMTP_USER")
@@ -40,7 +41,7 @@ def send_email(to_email, subject, body):
         server.sendmail(sender, [to_email], msg.as_string())
 
 
-def send_password_reset_email(to_email, reset_url):
+def send_password_reset_email(to_email: str, reset_url: str) -> None:
     body = (
         "Une réinitialisation de mot de passe a été demandée pour ce compte "
         "Forge Engine.\n\n"

auth/set_password.py

@@ -3,7 +3,7 @@ from werkzeug.security import generate_password_hash
 from .connection import connect
 
 
-def set_password(user_id, new_password):
+def set_password(user_id: int, new_password: str) -> None:
     """Remet aussi le compteur anti-bruteforce à zéro (auth/rate_limit.py) :
     prouver son identité par email est une voie de récupération légitime,
     un compte verrouillé après trop d'échecs ne doit pas rester bloqué une

auth/set_project_slug.py

@@ -1,7 +1,7 @@
 from .connection import connect
 
 
-def set_project_slug(user_id, slug):
+def set_project_slug(user_id: int, slug: str) -> None:
     """Enregistre le SEUL projet que ce compte possède (voir
     create_user.py — un compte "user" n'en aura jamais qu'un ; un compte
     "admin" n'a PAS besoin de cette colonne, il reste libre de créer

auth/totp_qrcode_svg.py

@@ -5,11 +5,11 @@ import qrcode
 import qrcode.image.svg
 
 
-def totp_provisioning_uri(secret, email):
+def totp_provisioning_uri(secret: str, email: str) -> str:
-    return pyotp.TOTP(secret).provisioning_uri(name=email, issuer_name="Forge Engine")
+    return str(pyotp.TOTP(secret).provisioning_uri(name=email, issuer_name="Forge Engine"))
 
 
-def totp_qrcode_svg(secret, email):
+def totp_qrcode_svg(secret: str, email: str) -> str:
     """SVG (pas PNG) : la variante "image factory" par défaut de qrcode a
     besoin de Pillow pour produire un PNG — SvgPathImage, elle, est du pur
     Python, sans dépendance supplémentaire à installer juste pour un QR
@@ -30,4 +30,4 @@ def totp_qrcode_svg(secret, email):
     buf = io.BytesIO()
     img.save(buf)
     svg = buf.getvalue().decode("utf-8")
-    return svg[svg.index("<svg"):]
+    return svg[svg.index("<svg") :]

auth/update_email.py

@@ -9,7 +9,7 @@ class EmailUpdateError(Exception):
     valide, unicité), voir create_user.py."""
 
 
-def update_email(user_id, new_email):
+def update_email(user_id: int, new_email: str | None) -> str:
     new_email = (new_email or "").strip().lower()
     if not is_valid_email(new_email):
         raise EmailUpdateError("Adresse email invalide.")

auth/update_profile.py

@@ -1,7 +1,7 @@
 from .connection import connect
 
 
-def update_profile(user_id, nom, prenom):
+def update_profile(user_id: int, nom: str, prenom: str) -> None:
     conn = connect()
     conn.execute("UPDATE _users SET nom = ?, prenom = ? WHERE id = ?", (nom, prenom, user_id))
     conn.commit()

auth/update_user_asset_scene_kind.py

@@ -0,0 +1,29 @@
+from .connection import connect
+from .ensure_user_assets_schema import ensure_user_assets_schema
+from .get_user_asset import get_user_asset
+from .user_asset_kind import user_asset_kind
+
+
+def update_user_asset_scene_kind(asset_id: int, user_id: int, scene_kind: str | None) -> bool:
+    """Reclasse une image déjà importée entre "Fonds" et "Décors/objets"
+    (voir create_user_asset.py) — SANS ré-upload (demande implicite,
+    trouvée en diagnostiquant un "décalage" : une image importée AVANT
+    la séparation fond/décor, ou par le mauvais bouton, restait bloquée
+    dans la mauvaise section, impossible à poser comme fond sans la
+    ré-importer en double). Ne touche jamais un objet DÉJÀ posé sur une
+    scène (kind="decor" dans _scene_objects) — l'auteur doit re-poser
+    l'image depuis la bonne section après reclassement, même geste
+    qu'un ajout normal."""
+    if scene_kind not in ("decor", "fond"):
+        return False
+    ensure_user_assets_schema()
+    asset = get_user_asset(asset_id)
+    if not asset or asset["user_id"] != user_id:
+        return False
+    if user_asset_kind(asset["filename"]) != "image":
+        return False
+    conn = connect()
+    conn.execute("UPDATE _user_assets SET scene_kind = ? WHERE id = ?", (scene_kind, asset_id))
+    conn.commit()
+    conn.close()
+    return True

auth/user_asset_kind.py

@@ -0,0 +1,25 @@
+import os
+
+# "image"/"audio"/"video"/"other" d'après l'EXTENSION du fichier (voir
+# _user_assets.filename, auth/save_user_asset.py) — pas de colonne dédiée
+# en base : l'extension suffit, jamais ambiguë ici (tout upload passe par
+# routes/assets/upload_user_asset.py, qui valide déjà le contenu pour un
+# son, voir MAX_AUDIO_SECONDS). Utilisé pour organiser "Mes assets" en
+# sous-sections (demande explicite : "voir, utiliser ou supprimer des
+# son, image et vidéo", voir templates/scene_edit.html) — le sélecteur de
+# fichier des actions "son"/"vidéo" (user_assets_options_json,
+# routes/scenes/scene_edit_view.py), lui, liste TOUT sans distinction.
+_IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".bmp"}
+_AUDIO_EXTENSIONS = {".mp3", ".wav", ".ogg", ".m4a", ".aac", ".flac"}
+_VIDEO_EXTENSIONS = {".mp4", ".webm", ".mov", ".avi", ".ogv"}
+
+
+def user_asset_kind(filename: str) -> str:
+    ext = os.path.splitext(filename)[1].lower()
+    if ext in _IMAGE_EXTENSIONS:
+        return "image"
+    if ext in _AUDIO_EXTENSIONS:
+        return "audio"
+    if ext in _VIDEO_EXTENSIONS:
+        return "video"
+    return "other"

auth/user_assets_dir.py

@@ -0,0 +1,10 @@
+import os
+
+from db.constants import USER_ASSETS_DIR
+
+
+def user_assets_dir(user_id: int) -> str:
+    """Dossier disque des images d'un compte (voir ensure_user_assets_schema.py
+    pour les métadonnées) — mirroir de db/game_dir.py, mais indexé par
+    utilisateur plutôt que par slug de projet."""
+    return os.path.join(USER_ASSETS_DIR, str(user_id))

auth/validate_audio_duration.py

@@ -0,0 +1,25 @@
+import io
+
+from mutagen import File as MutagenFile
+
+# Demande explicite : un son importé dans "Mes assets" ne doit jamais
+# dépasser 3 minutes (durée d'un effet sonore/d'une courte musique
+# d'ambiance — pas un morceau entier, voir l'action "son",
+# screens/rendering/collision_rules.py).
+MAX_AUDIO_SECONDS = 180
+
+
+def validate_audio_duration(content: bytes, max_seconds: int = MAX_AUDIO_SECONDS) -> str | None:
+    """Lit la durée d'un fichier audio (mp3/wav/ogg/m4a/... — mutagen
+    détecte le format lui-même, pas besoin de le lui préciser) et renvoie
+    un message d'erreur (français, prêt à afficher) si elle dépasse
+    `max_seconds`, ou si le format n'a pas pu être reconnu du tout (repli
+    prudent : un fichier illisible n'est jamais accepté silencieusement).
+    Renvoie None si la durée est correcte."""
+    audio = MutagenFile(io.BytesIO(content))
+    if audio is None or audio.info is None or not getattr(audio.info, "length", None):
+        return "Format audio non reconnu."
+    duration = audio.info.length
+    if duration > max_seconds:
+        return f"Ce son dépasse {max_seconds // 60} minutes (durée : {int(duration)} secondes)."
+    return None

auth/validate_video_duration.py

@@ -0,0 +1,34 @@
+import io
+
+from mutagen import File as MutagenFile
+
+# Demande explicite : une vidéo importée dans "Mes assets" ne doit jamais
+# dépasser 5 minutes (voir l'action "vidéo", screens/rendering/
+# collision_rules.py — pensée pour une courte cinématique/cutscene, pas un
+# film entier), même esprit que MAX_AUDIO_SECONDS pour un son.
+MAX_VIDEO_SECONDS = 300
+
+
+def validate_video_duration(
+    content: bytes, filename: str = "video.mp4", max_seconds: int = MAX_VIDEO_SECONDS
+) -> str | None:
+    """Lit la durée d'un fichier vidéo MP4 (seul format accepté à l'upload,
+    voir routes/assets/upload_user_asset.py — mutagen ne sait pas lire
+    fiablement la durée de webm/mov/avi, contrairement au conteneur MP4/
+    MOV ISO base media, qu'il décode via mutagen.mp4) et renvoie un
+    message d'erreur (français, prêt à afficher) si elle dépasse
+    `max_seconds`, ou si le format n'a pas pu être reconnu du tout (repli
+    prudent : un fichier illisible n'est jamais accepté silencieusement).
+    Renvoie None si la durée est correcte.
+
+    filename (juste l'extension importe) : contrairement à un son (voir
+    validate_audio_duration.py), la détection MP4 de mutagen SANS indice
+    de nom de fichier échoue silencieusement sur certains fichiers
+    (moov/ftyp minimaux) — passer ".mp4" explicitement la rend fiable."""
+    video = MutagenFile(io.BytesIO(content), filename=filename)
+    if video is None or video.info is None or not getattr(video.info, "length", None):
+        return "Format vidéo non reconnu."
+    duration = video.info.length
+    if duration > max_seconds:
+        return f"Cette vidéo dépasse {max_seconds // 60} minutes (durée : {int(duration)} secondes)."
+    return None

auth/verify_password.py

@@ -1,5 +1,7 @@
+from typing import Any
+
 from werkzeug.security import check_password_hash
 
 
-def verify_password(user, password):
+def verify_password(user: dict[str, Any] | None, password: str | None) -> bool:
-    return bool(user) and check_password_hash(user["password_hash"], password or "")
+    return user is not None and bool(check_password_hash(user["password_hash"], password or ""))

auth/verify_totp.py

@@ -1,7 +1,7 @@
 import pyotp
 
 
-def verify_totp(secret, code):
+def verify_totp(secret: str, code: str | None) -> bool:
     """valid_window=1 : tolère un léger décalage d'horloge entre le
     serveur et le téléphone (accepte aussi le code de la période
     précédente/suivante, ±30s) — sans quoi une horloge un peu désynchronisée
@@ -9,4 +9,4 @@ def verify_totp(secret, code):
     code = (code or "").strip()
     if not code:
         return False
-    return pyotp.TOTP(secret).verify(code, valid_window=1)
+    return bool(pyotp.TOTP(secret).verify(code, valid_window=1))

build_css.py

@@ -13,6 +13,7 @@ variables/règles posées par le précédent :
 
 Lancer `python build_css.py` après toute modification sous styles/ ou
 static/vendor/bulma.min.css."""
+
 import os
 
 _BASE_DIR = os.path.dirname(os.path.abspath(__file__))
@@ -27,8 +28,8 @@ _SOURCES = [
 ]
 
 
-def build():
+def build() -> None:
-    chunks = []
+    chunks: list[str] = []
     for path in _SOURCES:
         with open(path, encoding="utf-8") as f:
             chunks.append(f"/* ---- {os.path.relpath(path, _BASE_DIR)} ---- */\n" + f.read())

core/auth_guard.py

@@ -11,7 +11,9 @@ pour que `app.url_map` connaisse déjà toutes les routes au moment où ce
 module tente de résoudre request.endpoint — en pratique sans importance
 ici (la résolution se fait à la requête, pas à l'import), mais gardé pour
 rester cohérent avec l'ordre d'import du reste du moteur."""
-from flask import g, redirect, request, session, url_for, abort
+
+from flask import abort, g, redirect, request, session, url_for
+from werkzeug.wrappers import Response
 
 import auth
 from db.games.project_slug import split_slug
@@ -22,8 +24,14 @@ from .flask_app import app
 # session valide. "static" (CSS/JS/images) doit rester public : la page
 # de connexion elle-même en a besoin pour s'afficher.
 _PUBLIC_ENDPOINTS = {
-    "static", "login", "login_2fa", "register", "register_2fa", "logout",
+    "static",
-    "forgot_password", "reset_password",
+    "login",
+    "login_2fa",
+    "register",
+    "register_2fa",
+    "logout",
+    "forgot_password",
+    "reset_password",
 }
 
 # Endpoints de gestion de COMPTE (routes/auth/profile.py) — connexion
@@ -32,13 +40,18 @@ _PUBLIC_ENDPOINTS = {
 # quand même pouvoir changer son mot de passe, son email, ou supprimer
 # son compte.
 _REACHABLE_WITHOUT_PROJECT = {
-    "onboarding_new", "profile", "profile_update_name", "profile_update_email",
+    "onboarding_new",
-    "profile_regenerate_recovery_codes", "profile_change_password", "profile_delete",
+    "profile",
+    "profile_update_name",
+    "profile_update_email",
+    "profile_regenerate_recovery_codes",
+    "profile_change_password",
+    "profile_delete",
 }
 
 
 @app.before_request
-def _require_login_and_enforce_project_isolation():
+def _require_login_and_enforce_project_isolation() -> Response | None:
     endpoint = request.endpoint
     if endpoint is None or endpoint in _PUBLIC_ENDPOINTS:
         return None

core/csrf.py

@@ -6,6 +6,7 @@ un fetch() construit à la main (screen_edit.html, game_dashboard.html,
 play.html...) — voir static/csrf_fetch.js, qui l'ajoute automatiquement en
 en-tête à CHAQUE fetch() non-GET de l'appli plutôt que de devoir modifier
 individuellement chacun des nombreux appels existants."""
+
 import secrets
 
 from flask import session
@@ -13,12 +14,12 @@ from flask import session
 from .flask_app import app
 
 
-def get_csrf_token():
+def get_csrf_token() -> str:
     token = session.get("csrf_token")
     if not token:
         token = secrets.token_urlsafe(32)
         session["csrf_token"] = token
-    return token
+    return str(token)
 
 
 app.jinja_env.globals["csrf_token"] = get_csrf_token

core/csrf_guard.py

@@ -12,6 +12,7 @@ X-CSRFToken sur toute requête non-GET de l'appli (celles de pjax.js
 comprises) : pas besoin de modifier individuellement les nombreux appels
 fetch() déjà écrits à la main dans screen_edit.html/game_dashboard.html/
 play.html."""
+
 from flask import abort, request, session
 
 from .flask_app import app
@@ -20,7 +21,7 @@ _SAFE_METHODS = {"GET", "HEAD", "OPTIONS"}
 
 
 @app.before_request
-def _verify_csrf_token():
+def _verify_csrf_token() -> None:
     if request.method in _SAFE_METHODS:
         return None
     if app.config.get("TESTING"):

core/db_teardown_guard.py

@@ -0,0 +1,11 @@
+"""Enregistre le filet de sécurité de fermeture des connexions SQLite
+fuitées (voir db/connection.py::install_teardown_safety_net) sur l'app
+Flask — vit dans core/ (couche de câblage qui branche les autres paquets
+sur l'app), jamais l'inverse : db/ ne doit importer aucun paquet au-dessus
+de lui dans la hiérarchie (voir contrat import-linter, pyproject.toml)."""
+
+from db.connection import install_teardown_safety_net
+
+from .flask_app import app
+
+install_teardown_safety_net(app)

core/flask_app.py

@@ -1,16 +1,29 @@
 import os
 import secrets
 
+from dotenv import load_dotenv
 from flask import Flask
 
+# Charge .env AVANT tout le reste (voir .env.example) — ce module est le
+# tout premier import interne de app.py, donc les variables sont posées
+# avant qu'un `import db`/`auth` ne les résolve à l'import (ex.
+# db/constants.py::PROJECTS_DIR). Ne remplace JAMAIS une variable déjà
+# présente dans os.environ (comportement par défaut de load_dotenv) —
+# tests/conftest.py, qui pose ses propres variables en Python avant tout
+# import, reste donc isolé d'un .env local même s'il en existe un sur le
+# poste. Aucun effet en production (pas de fichier .env sur le serveur,
+# les variables y sont posées directement sur l'hôte/le conteneur).
+load_dotenv()
+
 _BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 _TEMPLATE_FOLDER = os.path.join(_BASE_DIR, "templates")
 _STATIC_FOLDER = os.path.join(_BASE_DIR, "static")
 
-app = Flask(__name__, template_folder=_TEMPLATE_FOLDER, static_folder=_STATIC_FOLDER)
+# CSRF gere par core/csrf_guard.py (garde maison globale, testee dans test_csrf.py) - pas Flask-WTF.
+app = Flask(__name__, template_folder=_TEMPLATE_FOLDER, static_folder=_STATIC_FOLDER)  # NOSONAR S4502
 
 
-def _load_or_create_secret_key():
+def _load_or_create_secret_key() -> str:
     """Nécessaire dès qu'une session Flask (flask.session) est utilisée —
     ici pour se souvenir de qui est connecté (auth/). Généré une seule
     fois et PERSISTÉ dans un fichier (jamais en dur dans le code, jamais

core/recovery_codes_flash.py

@@ -3,13 +3,15 @@ auth/recovery_codes.py et routes/auth/register_2fa.py) : posés en session
 au moment de la redirection qui suit leur génération, puis consommés
 (session.pop) dès le tout premier rendu de base.html qui suit — jamais
 revus après ce rendu, comme un message flash à usage unique."""
+
 from flask import session
 
 from .flask_app import app
 
 
-def pop_recovery_codes():
+def pop_recovery_codes() -> list[str] | None:
-    return session.pop("recovery_codes_to_show", None)
+    codes = session.pop("recovery_codes_to_show", None)
+    return list(codes) if codes is not None else None
 
 
 app.jinja_env.globals["pop_recovery_codes"] = pop_recovery_codes

core/sprite_gate.py

@@ -6,12 +6,13 @@ screen_edit.py, routes/scenes/scene_edit_view.py) ne les propose déjà pas
 (element_add, scene_object_add, element_set_personnage_data,
 scene_object_personnage_data) pourrait contourner ce filtrage d'UI — ce
 garde-fou ferme cette brèche au moment de l'écriture."""
+
 from flask import abort, g
 
 import screens
 
 
-def forbid_admin_only_character(forge_character):
+def forbid_admin_only_character(forge_character: str | None) -> None:
     if forge_character in screens.ADMIN_ONLY_CHARACTER_SLUGS and g.current_user["role"] != "admin":
         abort(403)
 
@@ -21,6 +22,6 @@ def forbid_admin_only_character(forge_character):
 # voir screens/labels/background_library.py) — TOUJOURS admin-only
 # aujourd'hui (un seul pack, tous sous licence CraftPix), contrairement
 # aux personnages Forge/Kenney (domaine public, jamais gatés).
-def forbid_admin_only_background(background_slug):
+def forbid_admin_only_background(background_slug: str | None) -> None:
     if background_slug in screens.ADMIN_ONLY_BACKGROUND_SLUGS and g.current_user["role"] != "admin":
         abort(403)

db/__init__.py

@@ -20,100 +20,125 @@ exécute un vrai CREATE TABLE, et remplir le formulaire généré exécute un
 vrai INSERT dans cette table.
 """
 
-from .constants import PROJECTS_DIR, FIELD_TYPES, GLOBAL_VARIABLE_TYPES, SCORE_STATUS_CHOICES, SCORE_STATUS_LABELS
+from .assert_not_none import assert_not_none
-from .slugify import slugify
-from .table_name_for import table_name_for
-from .game_dir import game_dir
-from .db_path import db_path
 from .connection import connect
-
+from .constants import FIELD_TYPES, GLOBAL_VARIABLE_TYPES, PROJECTS_DIR, SCORE_STATUS_CHOICES, SCORE_STATUS_LABELS
-from .games.list_games import list_games
+from .custom_events.create_custom_event import create_custom_event
-from .games.game_meta import game_meta
+from .custom_events.get_custom_event import get_custom_event
-from .games.get_game_type import get_game_type, DEFAULT_GAME_TYPE
+from .custom_events.list_custom_events import list_custom_events
-from .games.create_game import create_game
+from .custom_events.update_custom_event import update_custom_event
-from .games.update_game_name import update_game_name
+from .db_path import db_path
-from .games.delete_game import delete_game
-from .games.move_game import move_game
-from .games.get_xapi_settings import get_xapi_settings
-from .games.set_xapi_settings import set_xapi_settings
-from .games.get_success_threshold import get_success_threshold
-from .games.set_success_threshold import set_success_threshold
-from .games.get_scorm_version import get_scorm_version
-from .games.set_scorm_version import set_scorm_version
-from .games.game_type_catalog import (
-    ONBOARDING_TYPES, DEFAULT_ONBOARDING_TYPE,
-    get_onboarding_type, get_onboarding_type_raw, set_onboarding_type,
-    is_restricted,
-)
-
-from .definitions.list_definitions import list_definitions
-from .definitions.get_definition import get_definition
 from .definitions.create_definition import create_definition
-from .definitions.rename_definition import rename_definition
 from .definitions.definitions_referencing import definitions_referencing
-from .definitions.add_field_to_definition import add_field_to_definition
-from .definitions.update_field import update_field
-from .definitions.delete_field import delete_field
 from .definitions.delete_definition import delete_definition
-
+from .definitions.get_definition import get_definition
-from .rows.list_rows import list_rows
+from .definitions.list_definitions import list_definitions
-from .rows.relation_options import relation_options
+from .dialogue_lines import QUESTION_REWARD_TYPES, sanitize_dialogue_lines, sum_question_rewards
-from .rows.insert_row import insert_row
+from .game_dir import game_dir
-from .rows.get_row import get_row
+from .games.create_game import create_game
-from .rows.update_row import update_row
+from .games.delete_game import delete_game
-from .rows.update_row_field import update_row_field
+from .games.game_meta import game_meta
-from .rows.delete_row import delete_row
+from .games.game_type_catalog import (
-from .rows.rows_referencing import rows_referencing
+    DEFAULT_ONBOARDING_TYPE,
-
+    ONBOARDING_TYPES,
-from .global_vars.ensure_global_vars_schema import PLAYER_SHARED
+    get_onboarding_type,
-from .global_vars.list_global_variables import list_global_variables
+    get_onboarding_type_raw,
-from .global_vars.list_global_variables_for_player import list_global_variables_for_player
+    is_restricted,
-from .global_vars.get_global_variable import get_global_variable
+    set_onboarding_type,
+)
+from .games.get_game_type import DEFAULT_GAME_TYPE, get_game_type
+from .games.get_scorm_version import get_scorm_version
+from .games.get_success_threshold import get_success_threshold
+from .games.get_xapi_settings import get_xapi_settings
+from .games.list_games import list_games
+from .games.move_game import move_game
+from .games.set_scorm_version import set_scorm_version
+from .games.set_success_threshold import set_success_threshold
+from .games.set_xapi_settings import set_xapi_settings
+from .games.update_game_name import update_game_name
 from .global_vars.create_global_variable import create_global_variable
-from .global_vars.update_global_variable_value import update_global_variable_value
-from .global_vars.update_global_variable import update_global_variable
 from .global_vars.delete_global_variable import delete_global_variable
 from .global_vars.delete_global_variable_by_id import delete_global_variable_by_id
-
+from .global_vars.ensure_global_vars_schema import PLAYER_SHARED
+from .global_vars.get_global_variable import get_global_variable
+from .global_vars.list_global_variables import list_global_variables
+from .global_vars.list_global_variables_for_player import list_global_variables_for_player
+from .global_vars.update_global_variable import update_global_variable
+from .global_vars.update_global_variable_value import update_global_variable_value
+from .json_for_script import json_for_script
+from .rows.delete_row import delete_row
+from .rows.get_row import get_row
+from .rows.insert_row import insert_row
+from .rows.list_rows import list_rows
+from .rows.update_row import update_row
+from .rows.update_row_field import update_row_field
 from .scoring.get_score import get_score
 from .scoring.set_score_value import set_score_value
 from .scoring.set_status import set_status
-
+from .slugify import slugify
-from .custom_events.list_custom_events import list_custom_events
+from .table_name_for import table_name_for
-from .custom_events.get_custom_event import get_custom_event
-from .custom_events.create_custom_event import create_custom_event
-from .custom_events.update_custom_event import update_custom_event
-
-from .quests.constants import (
-    QUEST_STATUS_CHOICES, QUEST_STATUS_LABELS, QUEST_RESULT_CHOICES, QUEST_RESULT_LABELS,
-)
-from .quests.list_quests import list_quests
-from .quests.get_quest import get_quest
-from .quests.create_quest import create_quest
-from .quests.update_quest import update_quest
-from .quests.delete_quest import delete_quest
-from .quests.set_quest_dialogues import set_quest_dialogues
-from .quests.sanitize_quest_dialogues import sanitize_quest_dialogues, QUESTION_REWARD_TYPES
-from .quests.reward_budget import quest_dialogues_total_reward
 
 __all__ = [
-    "PROJECTS_DIR", "FIELD_TYPES", "GLOBAL_VARIABLE_TYPES", "PLAYER_SHARED",
+    "PROJECTS_DIR",
-    "SCORE_STATUS_CHOICES", "SCORE_STATUS_LABELS", "get_score", "set_score_value", "set_status",
+    "FIELD_TYPES",
-    "slugify", "table_name_for", "game_dir", "db_path", "connect",
+    "GLOBAL_VARIABLE_TYPES",
-    "list_games", "game_meta", "create_game", "update_game_name", "delete_game", "move_game",
+    "PLAYER_SHARED",
-    "get_game_type", "DEFAULT_GAME_TYPE",
+    "SCORE_STATUS_CHOICES",
-    "ONBOARDING_TYPES", "DEFAULT_ONBOARDING_TYPE", "get_onboarding_type",
+    "SCORE_STATUS_LABELS",
-    "get_onboarding_type_raw", "set_onboarding_type", "is_restricted",
+    "get_score",
-    "list_definitions", "get_definition", "create_definition", "rename_definition",
+    "set_score_value",
-    "definitions_referencing", "add_field_to_definition", "update_field", "delete_field",
+    "set_status",
+    "slugify",
+    "table_name_for",
+    "json_for_script",
+    "assert_not_none",
+    "game_dir",
+    "db_path",
+    "connect",
+    "list_games",
+    "game_meta",
+    "create_game",
+    "update_game_name",
+    "delete_game",
+    "move_game",
+    "get_game_type",
+    "DEFAULT_GAME_TYPE",
+    "get_xapi_settings",
+    "set_xapi_settings",
+    "get_success_threshold",
+    "set_success_threshold",
+    "get_scorm_version",
+    "set_scorm_version",
+    "ONBOARDING_TYPES",
+    "DEFAULT_ONBOARDING_TYPE",
+    "get_onboarding_type",
+    "get_onboarding_type_raw",
+    "set_onboarding_type",
+    "is_restricted",
+    "list_definitions",
+    "get_definition",
+    "create_definition",
+    "definitions_referencing",
     "delete_definition",
-    "list_rows", "relation_options", "insert_row", "get_row", "update_row",
+    "list_rows",
-    "update_row_field", "delete_row", "rows_referencing",
+    "insert_row",
-    "list_global_variables", "list_global_variables_for_player", "get_global_variable", "create_global_variable",
+    "get_row",
-    "update_global_variable_value", "update_global_variable", "delete_global_variable",
+    "update_row",
+    "update_row_field",
+    "delete_row",
+    "list_global_variables",
+    "list_global_variables_for_player",
+    "get_global_variable",
+    "create_global_variable",
+    "update_global_variable_value",
+    "update_global_variable",
+    "delete_global_variable",
     "delete_global_variable_by_id",
-    "list_custom_events", "get_custom_event", "create_custom_event", "update_custom_event",
+    "list_custom_events",
-    "QUEST_STATUS_CHOICES", "QUEST_STATUS_LABELS", "QUEST_RESULT_CHOICES", "QUEST_RESULT_LABELS",
+    "get_custom_event",
-    "list_quests", "get_quest", "create_quest", "update_quest", "delete_quest",
+    "create_custom_event",
-    "set_quest_dialogues", "sanitize_quest_dialogues", "QUESTION_REWARD_TYPES", "quest_dialogues_total_reward",
+    "update_custom_event",
+    "sanitize_dialogue_lines",
+    "QUESTION_REWARD_TYPES",
+    "sum_question_rewards",
 ]

db/assert_not_none.py

@@ -0,0 +1,15 @@
+from typing import TypeVar
+
+_T = TypeVar("_T")
+
+
+def assert_not_none(value: _T | None, message: str) -> _T:
+    """Narrowing de type explicite : lève un AssertionError clair si `value`
+    est None, renvoie `value` (type non-Optional) sinon. Centralise ici
+    l'unique suppression Bandit/Ruff de ce type dans tout le moteur - un
+    `assert` direct à chaque site d'appel dupliquait le même commentaire
+    de suppression à chaque fois (voir CODE_QUALITY.md, Sonar python:S7632 :
+    Sonar ne reconnaît pas deux commentaires # empilés sur une ligne, même
+    si Ruff et Bandit les acceptent chacun très bien)."""
+    assert value is not None, message  # nosec B101  # noqa: S101 - narrowing de type, seule assert du genre ici
+    return value

db/connection.py

@@ -1,9 +1,14 @@
+import contextlib
 import sqlite3
+from typing import TYPE_CHECKING
 
 from .db_path import db_path
 
+if TYPE_CHECKING:
+    from flask import Flask
 
-def connect(slug):
+
+def connect(slug: str) -> sqlite3.Connection:
     # timeout=10 : si une autre connexion tient un verrou d'écriture au même
     # instant (deux requêtes qui arrivent presque en même temps, ex. deux
     # onglets, ou le navigateur qui recharge plusieurs ressources), sqlite3
@@ -21,7 +26,7 @@ def connect(slug):
     return conn
 
 
-def _track_for_teardown(conn):
+def _track_for_teardown(conn: sqlite3.Connection) -> None:
     """Filet de sécurité : chaque fonction de db/ ouvre sa propre connexion
     et est censée la fermer elle-même (conn.close()) avant de rendre la
     main — mais si une exception survient ENTRE l'ouverture et cette
@@ -50,23 +55,18 @@ def _track_for_teardown(conn):
     g._forge_db_connections.append(conn)
 
 
-def _install_teardown_safety_net():
+def install_teardown_safety_net(app: "Flask") -> None:
-    """Appelé une seule fois (voir le bas de ce fichier) — enregistre le
+    """Enregistre le filet de sécurité (voir _track_for_teardown) sur
-    filet de sécurité sur l'appli Flask. `core.flask_app` ne dépend de rien
+    l'appli Flask passée en paramètre — jamais importée ici : `db/` est la
-    dans `db/`, donc cet import ne crée pas de dépendance circulaire."""
+    couche la plus basse du moteur (voir pyproject.toml, contrat
-    try:
+    import-linter) et ne doit dépendre d'aucun autre paquet. C'est
-        from core.flask_app import app
+    core/db_teardown_guard.py, dans la couche de câblage, qui appelle
-    except ImportError:
+    cette fonction avec `core.flask_app.app`."""
-        return
 
     @app.teardown_request
-    def _close_leaked_connections(exception=None):  # noqa: ARG001 - signature imposée par Flask
+    def _close_leaked_connections(exception: BaseException | None = None) -> None:  # noqa: ARG001 - signature imposée par Flask
         from flask import g
+
         for conn in getattr(g, "_forge_db_connections", ()):
-            try:
+            with contextlib.suppress(sqlite3.Error):
                 conn.close()
-            except sqlite3.Error:
-                pass
-
-
-_install_teardown_safety_net()

db/constants.py

@@ -10,6 +10,15 @@ PROJECTS_DIR = os.environ.get("FORGE_PROJECTS_DIR") or os.path.join(
     os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "projects"
 )
 
+# "Mes assets" (voir auth/user_assets/) : stockage PAR UTILISATEUR, pas
+# par jeu — distinct de PROJECTS_DIR/<owner>/<projet>/uploads (voir
+# routes/uploads/upload_file.py), pour qu'une image reste réutilisable
+# d'un projet à l'autre du même compte. Même schéma de surcharge que
+# PROJECTS_DIR ci-dessus.
+USER_ASSETS_DIR = os.environ.get("FORGE_USER_ASSETS_DIR") or os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "user_assets"
+)
+
 # Types de champ exposés dans l'interface -> type de colonne SQLite réel.
 FIELD_TYPES = {
     "texte": {"label": "Texte court", "sql": "TEXT"},

db/custom_events/create_custom_event.py

@@ -2,7 +2,7 @@ from ..connection import connect
 from .ensure_custom_events_schema import ensure_custom_events_schema
 
 
-def create_custom_event(slug, name, description=""):
+def create_custom_event(slug: str, name: str, description: str = "") -> int | None:
     """Idempotent par nom (même convention que create_global_variable.py) :
     si le nom existe déjà, ne touche à rien et renvoie simplement son id
     existant plutôt que de lever une erreur — sans risque en cas de
@@ -15,12 +15,12 @@ def create_custom_event(slug, name, description=""):
     existing = conn.execute("SELECT id FROM _custom_events WHERE name = ?", (name,)).fetchone()
     if existing:
         conn.close()
-        return existing["id"]
+        return int(existing["id"])
     conn.execute(
         "INSERT INTO _custom_events (name, description) VALUES (?, ?)",
         (name, (description or "").strip()),
     )
-    new_id = conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"]
+    new_id = int(conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"])
     conn.commit()
     conn.close()
     return new_id

db/custom_events/ensure_custom_events_schema.py

@@ -1,7 +1,7 @@
 from ..connection import connect
 
 
-def ensure_custom_events_schema(slug):
+def ensure_custom_events_schema(slug: str) -> None:
     """Migration légère (même principe que ensure_global_vars_schema.py) :
     crée _custom_events si absente. Un événement personnalisé vit pour
     TOUT le jeu (pas par écran, pas par modèle) : "name" est donc UNIQUE —

db/custom_events/get_custom_event.py

@@ -1,8 +1,10 @@
+from typing import Any
+
 from ..connection import connect
 from .ensure_custom_events_schema import ensure_custom_events_schema
 
 
-def get_custom_event(slug, event_id):
+def get_custom_event(slug: str, event_id: int | None) -> dict[str, Any] | None:
     if not event_id:
         return None
     ensure_custom_events_schema(slug)

db/custom_events/list_custom_events.py

@@ -1,8 +1,10 @@
+from typing import Any
+
 from ..connection import connect
 from .ensure_custom_events_schema import ensure_custom_events_schema
 
 
-def list_custom_events(slug):
+def list_custom_events(slug: str) -> list[dict[str, Any]]:
     ensure_custom_events_schema(slug)
     conn = connect(slug)
     rows = conn.execute("SELECT * FROM _custom_events ORDER BY name").fetchall()

db/custom_events/update_custom_event.py

@@ -2,7 +2,7 @@ from ..connection import connect
 from .ensure_custom_events_schema import ensure_custom_events_schema
 
 
-def update_custom_event(slug, event_id, description=""):
+def update_custom_event(slug: str, event_id: int, description: str = "") -> None:
     """Le NOM reste volontairement immuable après création — comme une
     variable globale (voir update_global_variable.py) : c'est par ce nom
     qu'on désigne l'événement dans l'interface, mais surtout par son ID

db/db_path.py

@@ -3,5 +3,5 @@ import os
 from .game_dir import game_dir
 
 
-def db_path(slug):
+def db_path(slug: str) -> str:
     return os.path.join(game_dir(slug), "game.db")

db/definitions/add_field_to_definition.py

@@ -1,44 +0,0 @@
-from ..connection import connect
-from ..constants import FIELD_TYPES
-from ..quote_ident import quote_ident
-from ..slugify import slugify
-from .get_definition import get_definition
-
-
-def add_field_to_definition(slug, definition_id, field):
-    """CRUD — Update d'une définition : ajoute un champ à un objet déjà
-    créé. Exécute un vrai ALTER TABLE ... ADD COLUMN sur la table SQL
-    existante (les lignes déjà enregistrées reçoivent NULL pour ce
-    nouveau champ, comportement standard d'un ALTER TABLE)."""
-    definition = get_definition(slug, definition_id)
-    conn = connect(slug)
-    fname = slugify(field["name"]).replace("-", "_")
-    ftype = field["type"]
-    required = 1 if field.get("required") else 0
-    relation_definition_id = None
-    position = (max((f["position"] for f in definition["fields"]), default=-1)) + 1
-
-    if ftype == "relation":
-        related = get_definition(slug, int(field["relation_definition_id"]))
-        col = f"{fname}_id"
-        # ALTER TABLE ADD COLUMN de SQLite n'accepte pas de contrainte
-        # REFERENCES portant sur une colonne ajoutée après coup avec la
-        # même simplicité qu'à la création : on ajoute la colonne simple —
-        # c'est la table _fields qui reste la source de vérité utilisée par
-        # le moteur pour savoir que cette colonne est une relation.
-        conn.execute(f"ALTER TABLE {definition['table_name']} ADD COLUMN {quote_ident(col)} INTEGER")
-        relation_definition_id = related["id"]
-    else:
-        sql_type = FIELD_TYPES[ftype]["sql"]
-        conn.execute(f"ALTER TABLE {definition['table_name']} ADD COLUMN {quote_ident(fname)} {sql_type}")
-
-    min_value = field.get("min_value") if ftype in ("nombre_entier", "nombre_decimal") else None
-    max_value = field.get("max_value") if ftype in ("nombre_entier", "nombre_decimal") else None
-    conn.execute(
-        """INSERT INTO _fields
-           (definition_id, name, type, relation_definition_id, required, position, min_value, max_value)
-           VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
-        (definition_id, field["name"], ftype, relation_definition_id, required, position, min_value, max_value),
-    )
-    conn.commit()
-    conn.close()

db/definitions/create_definition.py

@@ -1,13 +1,15 @@
+from typing import Any
+
 from ..connection import connect
 from ..constants import FIELD_TYPES
 from ..quote_ident import quote_ident
 from ..slugify import slugify
 from ..table_name_for import table_name_for
-from .get_definition import get_definition
 from .ensure_field_bounds_schema import ensure_field_bounds_schema
+from .get_definition import get_definition
 
 
-def create_definition(slug, name, fields, per_player=True):
+def create_definition(slug: str, name: str, fields: list[dict[str, Any]], per_player: bool = True) -> int:
     """Feature 2 : crée une définition d'objet (comme une table de BDD) et
     exécute le vrai CREATE TABLE correspondant, avec les bons types de
     colonne, y compris les colonnes de clé étrangère pour les relations
@@ -30,7 +32,7 @@ def create_definition(slug, name, fields, per_player=True):
         "INSERT INTO _definitions (name, table_name, per_player) VALUES (?, ?, ?)",
         (name, tname, 1 if per_player else 0),
     )
-    definition_id = conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"]
+    definition_id = int(conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"])
 
     columns_sql = ["id INTEGER PRIMARY KEY AUTOINCREMENT"]
     for pos, f in enumerate(fields):
@@ -41,10 +43,13 @@ def create_definition(slug, name, fields, per_player=True):
 
         if ftype == "relation":
             related = get_definition(slug, int(f["relation_definition_id"]))
+            if related is None:
+                raise ValueError(
+                    f"relation_definition_id {f['relation_definition_id']!r} ne correspond "
+                    "a aucune definition existante"
+                )
             col = f"{fname}_id"
-            columns_sql.append(
+            columns_sql.append(f"{quote_ident(col)} INTEGER REFERENCES {related['table_name']}(id)")
-                f"{quote_ident(col)} INTEGER REFERENCES {related['table_name']}(id)"
-            )
             relation_definition_id = related["id"]
         else:
             sql_type = FIELD_TYPES[ftype]["sql"]

db/definitions/definitions_referencing.py

@@ -1,7 +1,9 @@
+from typing import Any
+
 from ..connection import connect
 
 
-def definitions_referencing(slug, definition_id):
+def definitions_referencing(slug: str, definition_id: int) -> list[dict[str, Any]]:
     """Autres définitions de CE jeu qui ont un champ de type relation
     pointant vers cette définition — utilisé pour bloquer une suppression
     qui casserait ces relations."""

db/definitions/delete_definition.py

@@ -2,8 +2,10 @@ from ..connection import connect
 from .get_definition import get_definition
 
 
-def delete_definition(slug, definition_id):
+def delete_definition(slug: str, definition_id: int) -> None:
     definition = get_definition(slug, definition_id)
+    if definition is None:
+        raise ValueError(f"definition_id {definition_id!r} ne correspond a aucune definition existante")
     conn = connect(slug)
     conn.execute(f"DROP TABLE IF EXISTS {definition['table_name']}")
     conn.execute("DELETE FROM _fields WHERE definition_id = ?", (definition_id,))

db/definitions/delete_field.py

@@ -1,29 +0,0 @@
-import sqlite3
-
-from ..connection import connect
-from ..quote_ident import quote_ident
-from ..slugify import slugify
-from .get_definition import get_definition
-
-
-def delete_field(slug, definition_id, field_id):
-    """CRUD — Update d'une définition : retire un champ. Exécute un vrai
-    ALTER TABLE ... DROP COLUMN (SQLite ≥ 3.35). Sur une version de SQLite
-    trop ancienne pour DROP COLUMN, le champ est retiré de la définition
-    (le moteur ne le proposera plus dans les formulaires) mais la colonne
-    SQL peut subsister sans casser quoi que ce soit d'autre."""
-    definition = get_definition(slug, definition_id)
-    field = next((f for f in definition["fields"] if f["id"] == field_id), None)
-    if not field:
-        return
-    col = slugify(field["name"]).replace("-", "_")
-    if field["type"] == "relation":
-        col += "_id"
-    conn = connect(slug)
-    try:
-        conn.execute(f"ALTER TABLE {definition['table_name']} DROP COLUMN {quote_ident(col)}")
-    except sqlite3.OperationalError:
-        pass
-    conn.execute("DELETE FROM _fields WHERE id = ?", (field_id,))
-    conn.commit()
-    conn.close()

db/definitions/ensure_field_bounds_schema.py

@@ -1,7 +1,7 @@
 from ..connection import connect
 
 
-def ensure_field_bounds_schema(slug):
+def ensure_field_bounds_schema(slug: str) -> None:
     """Migration légère (voir screens/screens_repo/ensure_schema.py pour le
     même principe) : ajoute les colonnes min_value/max_value à _fields pour
     les jeux créés avant le bornage automatique (2.2), et per_player à

db/definitions/get_definition.py

@@ -1,8 +1,10 @@
+from typing import Any
+
 from ..connection import connect
 from .ensure_field_bounds_schema import ensure_field_bounds_schema
 
 
-def get_definition(slug, definition_id):
+def get_definition(slug: str, definition_id: int) -> dict[str, Any] | None:
     ensure_field_bounds_schema(slug)
     conn = connect(slug)
     d = conn.execute("SELECT * FROM _definitions WHERE id = ?", (definition_id,)).fetchone()

db/definitions/list_definitions.py

@@ -1,8 +1,10 @@
+from typing import Any
+
 from ..connection import connect
 from .ensure_field_bounds_schema import ensure_field_bounds_schema
 
 
-def list_definitions(slug):
+def list_definitions(slug: str) -> list[dict[str, Any]]:
     ensure_field_bounds_schema(slug)
     conn = connect(slug)
     rows = conn.execute("SELECT * FROM _definitions ORDER BY id").fetchall()

db/definitions/rename_definition.py

@@ -1,8 +0,0 @@
-from ..connection import connect
-
-
-def rename_definition(slug, definition_id, new_name):
-    conn = connect(slug)
-    conn.execute("UPDATE _definitions SET name = ? WHERE id = ?", (new_name, definition_id))
-    conn.commit()
-    conn.close()

db/definitions/update_field.py

@@ -1,49 +0,0 @@
-import sqlite3
-
-from ..connection import connect
-from ..quote_ident import quote_ident
-from ..slugify import slugify
-from .get_definition import get_definition
-
-
-def update_field(slug, definition_id, field_id, new_name, required, relation_definition_id=None, min_value=None, max_value=None):
-    """CRUD — Update d'une définition : modifie un champ déjà créé (nom,
-    obligatoire, objet lié si c'est une relation, et bornes mini/maxi si
-    c'est un champ numérique — voir 2.2, bornage automatique). Si le nom
-    change, la vraie colonne SQL est renommée (ALTER TABLE ... RENAME
-    COLUMN, SQLite ≥ 3.25) pour que la colonne réelle continue de
-    correspondre exactement au nom du champ tel qu'affiché — pas de dérive
-    entre la définition et la table. Le TYPE d'un champ existant ne se
-    change pas ici (une vraie conversion de type SQLite demanderait de
-    reconstruire la table et de convertir les données déjà enregistrées,
-    hors scope de cette version)."""
-    definition = get_definition(slug, definition_id)
-    field = next((f for f in definition["fields"] if f["id"] == field_id), None)
-    if not field:
-        return
-
-    old_col = slugify(field["name"]).replace("-", "_")
-    new_col = slugify(new_name).replace("-", "_")
-    if field["type"] == "relation":
-        old_col += "_id"
-        new_col += "_id"
-
-    conn = connect(slug)
-    if old_col != new_col:
-        try:
-            conn.execute(
-                f"ALTER TABLE {definition['table_name']} RENAME COLUMN {quote_ident(old_col)} TO {quote_ident(new_col)}"
-            )
-        except sqlite3.OperationalError:
-            pass  # SQLite trop ancien pour RENAME COLUMN : la colonne SQL garde son ancien nom
-
-    rel_id = int(relation_definition_id) if (field["type"] == "relation" and relation_definition_id) else field["relation_definition_id"]
-    is_numeric = field["type"] in ("nombre_entier", "nombre_decimal")
-    min_v = (min_value if min_value not in (None, "") else None) if is_numeric else None
-    max_v = (max_value if max_value not in (None, "") else None) if is_numeric else None
-    conn.execute(
-        "UPDATE _fields SET name = ?, required = ?, relation_definition_id = ?, min_value = ?, max_value = ? WHERE id = ?",
-        (new_name, 1 if required else 0, rel_id, min_v, max_v, field_id),
-    )
-    conn.commit()
-    conn.close()

db/dialogue_lines.py

@@ -0,0 +1,108 @@
+from typing import Any
+
+_MAX_LINES_PER_COLUMN = 200
+_MAX_SPEAKER_LENGTH = 60
+
+# Question à choix (voir "❓ Question", static/js/triggers/trigger-editor.js) :
+# une bulle jaune posée dans le même enchaînement qu'une réplique de
+# dialogue — plusieurs choix, une seule bonne réponse, une récompense.
+# Un seul type de récompense pour l'instant (le score, voir db.SCORE_STATUS_*/
+# db.set_score_value) — liste plutôt qu'un booléen pour pouvoir en ajouter
+# d'autres plus tard sans changer la forme des données.
+QUESTION_REWARD_TYPES = ["score"]
+_MIN_CHOICES = 2
+_MAX_CHOICES = 4
+
+
+def _sanitize_dialogue_line(raw_line: dict[str, Any]) -> dict[str, Any] | None:
+    speaker = raw_line.get("speaker")
+    text = raw_line.get("text")
+    if not isinstance(speaker, str) or not speaker.strip():
+        return None
+    if not isinstance(text, str) or not text.strip():
+        return None
+    line = {"type": "dialogue", "speaker": speaker.strip()[:_MAX_SPEAKER_LENGTH], "text": text.strip()}
+    # Réplique audio (demande explicite : "ajouter une réplique audio")
+    # — une voix off jouée en même temps que la bulle s'affiche, voir
+    # "Mes assets" (un fichier déjà importé, jamais un chemin arbitraire
+    # posté à la main : la sélection se fait via un <select>, pas un
+    # champ texte libre, voir static/js/triggers/trigger-editor.js).
+    # Optionnel : une réplique reste valide sans voix off.
+    audio_url = raw_line.get("audio_url")
+    if isinstance(audio_url, str) and audio_url.strip():
+        line["audio_url"] = audio_url.strip()
+    return line
+
+
+def _sanitize_question_line(raw_line: dict[str, Any]) -> dict[str, Any] | None:
+    text = raw_line.get("text")
+    if not isinstance(text, str) or not text.strip():
+        return None
+    raw_choices = raw_line.get("choices")
+    if not isinstance(raw_choices, list):
+        return None
+    choices = [c.strip() for c in raw_choices if isinstance(c, str) and c.strip()][:_MAX_CHOICES]
+    if len(choices) < _MIN_CHOICES:
+        return None
+    raw_correct_index = raw_line.get("correct_index")
+    if raw_correct_index is None:
+        return None
+    try:
+        correct_index = int(raw_correct_index)
+    except (TypeError, ValueError):
+        return None
+    if not (0 <= correct_index < len(choices)):
+        return None
+    reward_type = raw_line.get("reward_type")
+    if reward_type not in QUESTION_REWARD_TYPES:
+        reward_type = QUESTION_REWARD_TYPES[0]
+    try:
+        reward_amount = max(0, int(raw_line.get("reward_amount", 0)))
+    except (TypeError, ValueError):
+        reward_amount = 0
+    return {
+        "type": "question",
+        "text": text.strip(),
+        "choices": choices,
+        "correct_index": correct_index,
+        "reward_type": reward_type,
+        "reward_amount": reward_amount,
+    }
+
+
+def _sanitize_line(raw_line: Any) -> dict[str, Any] | None:
+    if not isinstance(raw_line, dict):
+        return None
+    if raw_line.get("type") == "question":
+        return _sanitize_question_line(raw_line)
+    return _sanitize_dialogue_line(raw_line)
+
+
+def sanitize_dialogue_lines(raw_lines: Any) -> list[dict[str, Any]]:
+    """Sanitize une LISTE de répliques de dialogue ({type: "dialogue",
+    speaker, text} — le nom vient du champ "ℹ️ Informations" d'un objet de
+    scène, ou "Joueur", voir screens/rendering/scene_object_names.py)
+    ET/OU de questions à choix ({type: "question", text, choices,
+    correct_index, reward_type, reward_amount}, voir QUESTION_REWARD_TYPES
+    ci-dessus) — même esprit que resolve_collision_rules.sanitize_collision_rules :
+    rejette tout élément invalide plutôt que de lever. Les lignes d'UN
+    dialogue embarqué dans une action "dialogue" (voir
+    screens/rendering/collision_rules.py) : chaque occurrence de
+    "Déclencher ce dialogue" porte le sien."""
+    if not isinstance(raw_lines, list):
+        return []
+    cleaned = [_sanitize_line(raw_line) for raw_line in raw_lines[:_MAX_LINES_PER_COLUMN]]
+    return [line for line in cleaned if line]
+
+
+def sum_question_rewards(lines: Any) -> int:
+    """Somme des récompenses de toutes les questions ("❓ Question" ci-
+    dessus) d'UNE liste de répliques/questions — utilisée pour calculer le
+    score max possible du quiz à l'export SCORM, sur TOUTES les lignes de
+    TOUS les dialogues du jeu (voir screens.collect_all_dialogue_lines,
+    publish/build_scorm_package.py)."""
+    total = 0
+    for line in lines or []:
+        if isinstance(line, dict) and line.get("type") == "question":
+            total += line.get("reward_amount", 0) or 0
+    return total

db/game_dir.py

@@ -4,7 +4,7 @@ from .constants import PROJECTS_DIR
 from .games.project_slug import split_slug
 
 
-def game_dir(slug):
+def game_dir(slug: str) -> str:
     # Structure de dossiers par utilisateur (voir db/games/project_slug.py)
     # : un slug composé "propriétaire_projet" résout vers un vrai chemin
     # imbriqué projects/<propriétaire>/<projet>/ — repli sur l'ancien

db/games/create_game.py

@@ -6,7 +6,7 @@ from ..slugify import slugify
 from .project_slug import build_slug
 
 
-def create_game(name, owner_folder=None, project_slug_override=None):
+def create_game(name: str, owner_folder: str | None = None, project_slug_override: str | None = None) -> str:
     """Feature 1 : crée le dossier du jeu, ses fichiers index.html/css/js
     reliés entre eux, et sa base de données dédiée (nom du jeu en méta).
 

db/games/delete_game.py

@@ -6,7 +6,7 @@ from ..game_dir import game_dir
 from .project_slug import split_slug
 
 
-def delete_game(slug):
+def delete_game(slug: str) -> None:
     shutil.rmtree(game_dir(slug))
     # Structure de dossiers par utilisateur (voir project_slug.py) :
     # nettoie aussi le dossier propriétaire s'il ne contient plus aucun

db/games/game_meta.py

@@ -1,13 +1,16 @@
+from typing import Any
+
 from ..connection import connect
 from .game_type_catalog import get_onboarding_type
 
 
-def game_meta(slug):
+def game_meta(slug: str) -> dict[str, Any]:
     conn = connect(slug)
     row = conn.execute("SELECT value FROM _meta WHERE key = 'name'").fetchone()
     conn.close()
     return {
-        "slug": slug, "name": row["value"] if row else slug,
+        "slug": slug,
+        "name": row["value"] if row else slug,
         # Onboarding guidé (voir game_type_catalog.py) : utilisé par
         # templates/base.html pour cacher le lien "Tableau de bord" à un
         # compte "restreint" (quiz/embranchement/rpg).

db/games/game_type_catalog.py

@@ -13,11 +13,14 @@ _meta['onboarding_type'] (une ligne _meta par projet, même convention que
 game_type) retient CE choix — jamais lu par le
 rendu jouable, seulement par le routage (routes/games/game_dashboard.py,
 routes/screens/screens_new.py)."""
+
+from typing import Any
+
 import db
 
 DEFAULT_ONBOARDING_TYPE = "rpg"
 
-ONBOARDING_TYPES = {
+ONBOARDING_TYPES: dict[str, dict[str, Any]] = {
     "rpg": {
         "label": "Créer un jeu 2D ludique",
         "tagline": "Ton monde, ton héros, ton scénario.",
@@ -57,7 +60,7 @@ ONBOARDING_TYPES = {
 }
 
 
-def get_onboarding_type_raw(slug):
+def get_onboarding_type_raw(slug: str) -> str | None:
     """None si _meta['onboarding_type'] est absent — distingue un projet
     JAMAIS passé par l'onboarding guidé (créé avant son existence, ou par
     l'admin via "+ Nouveau jeu") d'un projet explicitement "custom"."""
@@ -67,11 +70,11 @@ def get_onboarding_type_raw(slug):
     return row["value"] if row else None
 
 
-def get_onboarding_type(slug):
+def get_onboarding_type(slug: str) -> str:
     return get_onboarding_type_raw(slug) or DEFAULT_ONBOARDING_TYPE
 
 
-def set_onboarding_type(slug, onboarding_type):
+def set_onboarding_type(slug: str, onboarding_type: str) -> None:
     conn = db.connect(slug)
     conn.execute(
         "INSERT OR REPLACE INTO _meta (key, value) VALUES ('onboarding_type', ?)",
@@ -81,15 +84,14 @@ def set_onboarding_type(slug, onboarding_type):
     conn.close()
 
 
-def is_restricted(onboarding_type_or_slug):
+def is_restricted(onboarding_type_or_slug: str) -> bool:
     """Accepte directement une clé de ONBOARDING_TYPES, ou un slug de
     projet (résout alors son onboarding_type d'abord) — pratique aussi
     bien pour core/auth_guard.py (a le slug) que pour un test unitaire (a
     déjà la clé)."""
     onboarding_type = (
-        onboarding_type_or_slug if onboarding_type_or_slug in ONBOARDING_TYPES
+        onboarding_type_or_slug
+        if onboarding_type_or_slug in ONBOARDING_TYPES
         else get_onboarding_type(onboarding_type_or_slug)
     )
-    return ONBOARDING_TYPES.get(onboarding_type, ONBOARDING_TYPES[DEFAULT_ONBOARDING_TYPE])["restricted"]
+    return bool(ONBOARDING_TYPES.get(onboarding_type, ONBOARDING_TYPES[DEFAULT_ONBOARDING_TYPE])["restricted"])
-
-

db/games/get_game_type.py

@@ -3,7 +3,7 @@ from ..connection import connect
 DEFAULT_GAME_TYPE = "jeu_2d"
 
 
-def get_game_type(slug):
+def get_game_type(slug: str) -> str:
     """Type de jeu choisi à la création (voir create_game.py) : "document"
     (éditeur générique actuel — quiz/formulaires/contenus, écrans =
     éléments HTML positionnés en %) ou "jeu_2d" (éditeur de scène dédié —

db/games/get_scorm_version.py

@@ -4,7 +4,7 @@ DEFAULT_SCORM_VERSION = "1.2"
 VALID_SCORM_VERSIONS = ("1.2", "2004")
 
 
-def get_scorm_version(slug):
+def get_scorm_version(slug: str) -> str:
     """Version SCORM exportée pour ce jeu (voir publish/build_scorm_package.py,
     publish/scorm_manifest.py) — '1.2' par défaut (compatibilité la plus
     large) ou '2004' (3rd/4th edition, sépare completion_status/
@@ -16,4 +16,4 @@ def get_scorm_version(slug):
     conn.close()
     if row is None or row["value"] not in VALID_SCORM_VERSIONS:
         return DEFAULT_SCORM_VERSION
-    return row["value"]
+    return str(row["value"])

db/games/get_success_threshold.py

@@ -3,16 +3,14 @@ from ..connection import connect
 DEFAULT_SUCCESS_THRESHOLD_PERCENT = 70
 
 
-def get_success_threshold(slug):
+def get_success_threshold(slug: str) -> int:
     """Seuil de réussite (% de bonnes réponses au quiz) de CE jeu — stocké
     dans _meta (clé 'success_threshold_percent'), même convention que
     get_xapi_settings.py. Détermine le statut SCORM/xAPI de fin de partie
     (reussi/echoue, voir static/js/play/dialogue-box-controller.js::
     forgeSyncAllQuestsCompletionToScorm) : 70% par défaut si jamais réglé."""
     conn = connect(slug)
-    row = conn.execute(
+    row = conn.execute("SELECT value FROM _meta WHERE key = 'success_threshold_percent'").fetchone()
-        "SELECT value FROM _meta WHERE key = 'success_threshold_percent'"
-    ).fetchone()
     conn.close()
     if row is None or row["value"] in (None, ""):
         return DEFAULT_SUCCESS_THRESHOLD_PERCENT

db/games/get_xapi_settings.py

@@ -1,7 +1,7 @@
 from ..connection import connect
 
 
-def get_xapi_settings(slug):
+def get_xapi_settings(slug: str) -> dict[str, str]:
     """Réglages xAPI de CE jeu (voir set_xapi_settings.py — stockés dans
     _meta, même convention que 'name'/'onboarding_type', voir
     db/games/game_type_catalog.py) : URL du LRS (Learning Record Store)

db/games/list_games.py

@@ -1,12 +1,13 @@
 import os
+from typing import Any
 
-from ..constants import PROJECTS_DIR
 from ..connection import connect
+from ..constants import PROJECTS_DIR
 from ..db_path import db_path
 from .project_slug import build_slug
 
 
-def list_games(owner_folder):
+def list_games(owner_folder: str) -> list[dict[str, Any]]:
     """Scanne UNIQUEMENT projects/<owner_folder>/ (voir db/games/
     project_slug.py — owner_folder est l'id du compte, voir
     db/games/create_game.py) : jamais les autres comptes — voir
@@ -17,7 +18,7 @@ def list_games(owner_folder):
     fonction ne lit plus jamais l'arborescence project/ en entier (avant
     ce correctif, elle listait TOUS les comptes sans distinction — faille
     corrigée, voir routes/games/index.py)."""
-    games = []
+    games: list[dict[str, Any]] = []
     entry_path = os.path.join(PROJECTS_DIR, owner_folder)
     if not os.path.isdir(entry_path):
         return games
@@ -28,7 +29,7 @@ def list_games(owner_folder):
     return games
 
 
-def _append_game(games, slug):
+def _append_game(games: list[dict[str, Any]], slug: str) -> None:
     conn = connect(slug)
     row = conn.execute("SELECT value FROM _meta WHERE key = 'name'").fetchone()
     conn.close()

db/games/move_game.py

@@ -5,7 +5,7 @@ from ..game_dir import game_dir
 from .project_slug import build_slug, split_slug
 
 
-def move_game(old_slug, new_owner_folder):
+def move_game(old_slug: str, new_owner_folder: str) -> str:
     """Renomme le dossier PROPRIÉTAIRE d'un compte — owner_folder est
     l'id du compte (voir db/games/project_slug.py, routes/games/
     games_new.py) : ne change donc plus jamais après coup en usage normal,

db/games/project_slug.py

@@ -17,11 +17,11 @@ move_game, list_games) savent que le slug encode ce chemin composé — si
 la convention change un jour, ce fichier est le seul à modifier."""
 
 
-def build_slug(owner_folder, project_part):
+def build_slug(owner_folder: str, project_part: str) -> str:
     return f"{owner_folder}_{project_part}"
 
 
-def split_slug(slug):
+def split_slug(slug: str) -> tuple[str, str | None]:
     """(owner_folder, project_part) si `slug` est bien composé, sinon
     (slug, None) — un slug "plat" (créé avant cette convention, pas encore
     migré par scripts/migrate_flat_project_slugs.py) reste lisible tel

db/games/set_scorm_version.py

@@ -2,7 +2,7 @@ from ..connection import connect
 from .get_scorm_version import VALID_SCORM_VERSIONS
 
 
-def set_scorm_version(slug, version):
+def set_scorm_version(slug: str, version: str) -> None:
     """Enregistre la version SCORM exportée — voir get_scorm_version.py."""
     if version not in VALID_SCORM_VERSIONS:
         raise ValueError("version SCORM invalide : {!r}".format(version))

db/games/set_success_threshold.py

@@ -1,7 +1,7 @@
 from ..connection import connect
 
 
-def set_success_threshold(slug, percent):
+def set_success_threshold(slug: str, percent: int) -> int:
     """Enregistre le seuil de réussite (0-100) — voir get_success_threshold.py."""
     percent = max(0, min(100, int(percent)))
     conn = connect(slug)

db/games/set_xapi_settings.py

@@ -1,7 +1,7 @@
 from ..connection import connect
 
 
-def set_xapi_settings(slug, endpoint, login, password=None):
+def set_xapi_settings(slug: str, endpoint: str, login: str, password: str | None = None) -> None:
     """Enregistre les réglages xAPI de CE jeu (voir get_xapi_settings.py).
     `password=None` (champ laissé vide côté formulaire, voir
     routes/publish/xapi_settings.py) laisse le mot de passe déjà
@@ -10,15 +10,9 @@ def set_xapi_settings(slug, endpoint, login, password=None):
     que la route GET puisse ne jamais renvoyer sa valeur au navigateur
     (juste un booléen "déjà configuré")."""
     conn = connect(slug)
-    conn.execute(
+    conn.execute("INSERT OR REPLACE INTO _meta (key, value) VALUES ('xapi_lrs_endpoint', ?)", (endpoint or "",))
-        "INSERT OR REPLACE INTO _meta (key, value) VALUES ('xapi_lrs_endpoint', ?)", (endpoint or "",)
+    conn.execute("INSERT OR REPLACE INTO _meta (key, value) VALUES ('xapi_lrs_login', ?)", (login or "",))
-    )
-    conn.execute(
-        "INSERT OR REPLACE INTO _meta (key, value) VALUES ('xapi_lrs_login', ?)", (login or "",)
-    )
     if password is not None:
-        conn.execute(
+        conn.execute("INSERT OR REPLACE INTO _meta (key, value) VALUES ('xapi_lrs_password', ?)", (password,))
-            "INSERT OR REPLACE INTO _meta (key, value) VALUES ('xapi_lrs_password', ?)", (password,)
-        )
     conn.commit()
     conn.close()

db/games/update_game_name.py

@@ -1,7 +1,7 @@
 from ..connection import connect
 
 
-def update_game_name(slug, new_name):
+def update_game_name(slug: str, new_name: str) -> None:
     conn = connect(slug)
     conn.execute("UPDATE _meta SET value = ? WHERE key = 'name'", (new_name,))
     conn.commit()

db/global_vars/coerce_structured_value.py

@@ -1,7 +1,7 @@
 import json
 
 
-def coerce_structured_value(var_type, value):
+def coerce_structured_value(var_type: str, value: str) -> str:
     """Pour une variable "objet"/"tableau" (voir db/constants.py), la
     valeur stockée doit rester du JSON analysable — sinon la prochaine
     lecture (_resolve_variable_path, screens/rendering/

db/global_vars/create_global_variable.py

@@ -1,9 +1,11 @@
 from ..connection import connect
-from .ensure_global_vars_schema import ensure_global_vars_schema, PLAYER_SHARED
 from .coerce_structured_value import coerce_structured_value
+from .ensure_global_vars_schema import PLAYER_SHARED, ensure_global_vars_schema
 
 
-def create_global_variable(slug, name, var_type="texte", default_value="", per_player=True):
+def create_global_variable(
+    slug: str, name: str, var_type: str = "texte", default_value: str = "", per_player: bool = True
+) -> int | None:
     """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
@@ -28,12 +30,12 @@ def create_global_variable(slug, name, var_type="texte", default_value="", per_p
     ).fetchone()
     if existing:
         conn.close()
-        return existing["id"]
+        return int(existing["id"])
     conn.execute(
         "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"]
+    new_id = int(conn.execute("SELECT last_insert_rowid() AS id").fetchone()["id"])
     conn.commit()
     conn.close()
     return new_id

db/global_vars/delete_global_variable.py

@@ -2,7 +2,7 @@ from ..connection import connect
 from .ensure_global_vars_schema import ensure_global_vars_schema
 
 
-def delete_global_variable(slug, name):
+def delete_global_variable(slug: str, name: str) -> None:
     """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)."""