Forge-Engine/document_engine/rendering/rendering.md

# document_engine/rendering/

Rendu HTML du document — point d'entrée unique utilisé à la fois par le
canevas d'édition et par le Mode Aperçu (même fonction, voir
`docs/plan/PLAN.md` — "Aperçu réel").

## `render_document(elements: list[dict[str, Any]]) -> str`
Assemble le document entier à partir de la liste à plat renvoyée par
`document_engine.list_document_elements` : regroupe les éléments par
`parent_id`, puis rend récursivement les éléments top-niveau dans
l'ordre (une rangée rend elle-même ses propres enfants côte à côte).
- **Retour** : le HTML complet du document.
- **Exceptions** : aucune.

## `render_document_element(el: dict[str, Any], children_by_parent: dict[int | None, list[dict[str, Any]]]) -> str`
HTML d'un seul élément — dispatch par dict (table `_RENDERERS`) selon
`el["kind"]`, plutôt qu'un enchaînement de `if` (mirroir de l'esprit de
`game_engine/scenes/render_scene_object.py`). `children_by_parent` est le
regroupement précalculé par `render_document`, transmis pour que les
rangées puissent rendre récursivement leurs enfants sans refaire le
regroupement à chaque appel.
- **Retour** : le HTML de cet élément (et de ses enfants s'il s'agit
  d'une rangée).
- **Exceptions** : aucune ; un `kind` inconnu produit un bloc
  `docUnknown` visible plutôt qu'une levée d'exception.

### Détail des rendus par catégorie (fonctions privées, table de dispatch)
- **Rangée** (`row`) : conteneur flex (`gap`/`align-items`/
  `justify-content` réels depuis `attributes`), enfants rendus
  récursivement.
- **Formes** (`rectangle`/`cercle`/`triangle`/`trait`) : `<div>` positionné
  en absolu (`x`/`y`/`width`/`height`/`rotation`/`z_index` réels) contenant
  un SVG (`rect`/`circle`/`polygon`/`line` selon le type).
- **Texte** (`titre`/`paragraphe`) : `<div>` stylé selon `style` (préréglage
  taille/graisse/interligne) et `bold`/`italic`/`underline`/`align`/`color`.
- **Image** : `<img>`, ou un bloc placeholder si `src` est vide.
- **Bouton** : `<button>` avec son `label` et un `data-target` optionnel.
- **Quiz** : toujours une carte résumant la config réelle (nombre de
  questions, total des points via `quiz_total_points`, minuteur si
  activé) — sanitizée (`sanitize_quiz_config`) avant lecture, jamais un
  rendu direct d'`attributes` brut. Si au moins une question existe,
  s'y ajoute (fonction privée `_render_quiz_player`) le questionnaire
  RÉEL et interactif affiché en Mode Aperçu (voir docs/plan/maquettes/
  document-formation-web.html — référence visuelle), masqué en édition
  par CSS (`.docQuizPlayer`, voir static/document/document-editor.css) :
  les questions sont embarquées en JSON dans un attribut `data-quiz-config`
  (jamais un `<script>` par élément), échappé pour l'HTML
  (`html.escape(..., quote=True)`) — static/document/js/document-editor.js
  lit cet attribut et gère tout le déroulé (réponse/score/question
  suivante/résultat) côté client, sans aucun aller-retour serveur.
- **Association** : toujours une carte résumant la config réelle (nombre
  de paires) — sanitizée (`sanitize_association_config`) avant lecture.
  Si au moins une paire existe, s'y ajoute (fonction privée
  `_render_association_player`) le plateau de glisser-déposer RÉEL et
  interactif affiché en Mode Aperçu, masqué en édition par CSS
  (`.docAssocPlayer`) : les deux colonnes (termes/correspondances) sont
  mélangées INDÉPENDAMMENT (`random.shuffle`, mélange d'affichage — voir
  `CODE_QUALITY.md`) puis embarquées en JSON dans un attribut
  `data-assoc-config`, échappé pour l'HTML — même principe que le Quiz,
  aucun aller-retour serveur pendant qu'on joue. Contrairement au Quiz,
  le plateau reste affiché en permanence une fois la partie terminée :
  seul le bouton "Recommencer" (`.docMinigameRestartBar`, partagé avec
  Memory) apparaît, jamais d'écran de résultat séparé qui le
  remplacerait.
- **Memory** : toujours une carte résumant la config réelle (nombre de
  cartes définies, mode paire/simple) — sanitizée
  (`sanitize_memory_config`) avant lecture. Si au moins une carte existe,
  s'y ajoute (fonction privée `_render_memory_player`) le plateau de
  retournement RÉEL et interactif : en mode `"paire"`, chaque carte
  définie est DUPLIQUÉE en deux instances partageant le même
  `card_index` (l'appariement se fait dessus, classique Memory) ; en mode
  `"single"`, une seule instance par carte (simple retournement, sans
  appariement). Les instances sont mélangées (`random.shuffle`, mélange
  d'affichage — voir `CODE_QUALITY.md`) puis embarquées en JSON dans un
  attribut `data-memory-config`, échappé pour l'HTML — même principe que
  le Quiz/l'Association, aucun aller-retour serveur pendant qu'on joue.
  Comme l'Association, le plateau reste affiché une fois toutes les
  paires trouvées (ou toutes les cartes révélées en mode `"single"`) :
  seul le bouton "Recommencer" (`.docMinigameRestartBar`) apparaît.
- **Mots mêlés** : toujours une carte résumant la config réelle (nombre
  de mots) — sanitizée (`sanitize_mots_config`) avant lecture. Si au
  moins un mot existe, s'y ajoute (fonction privée `_render_mots_player`)
  la grille RÉELLE et interactive. La grille ET la position exacte de
  chaque mot sont calculées ICI côté serveur (`_build_mots_grid`, jamais
  recalculées côté client) : chaque mot est placé horizontalement,
  verticalement, ou en diagonale (haut-gauche→bas-droite ou
  haut-droite→bas-gauche — jamais à l'envers), les lettres restantes
  tirées au hasard (`random.choice`/`random.randint`, tirage de jeu —
  voir `CODE_QUALITY.md`) ; si un mot ne trouve pas sa place, la grille
  entière est agrandie et le placement retenté depuis zéro, plutôt que
  d'abandonner silencieusement ce mot. Le tout (grille + coordonnées de
  chaque mot) est embarqué en JSON dans un attribut `data-mots-config`,
  échappé pour l'HTML — même principe que les autres mini-jeux, aucun
  aller-retour serveur pendant qu'on joue : `static/document/js/
  document-editor.js` compare les coordonnées EXACTES sélectionnées par
  l'apprenant à celles de chaque mot (jamais une simple comparaison de
  texte, qui se tromperait sur des lettres partagées entre deux mots qui
  se croisent). Comme l'Association/Memory, la grille reste affichée une
  fois tous les mots trouvés : seul le bouton "Recommencer"
  (`.docMinigameRestartBar`) apparaît.
- **Scénario** : toujours une carte résumant la config réelle (nombre de
  scénarios) — sanitizée (`sanitize_scenario_config`) avant lecture. Si
  au moins un scénario existe, s'y ajoute (fonction privée
  `_render_scenario_player`) la mise en situation RÉELLE et interactive :
  l'apprenant lit la situation, choisit une option, puis la conséquence
  de SON choix REMPLACE l'affichage de la situation (les boutons de
  choix disparaissent avec elle) avant de passer au scénario suivant —
  volontairement PAS le comportement du Quiz, où la question resterait
  affichée à côté d'un encart de feedback séparé (retour utilisateur du
  20/09/2026 : "ce n'est pas un quiz, la conséquence s'affiche à la
  place de la situation précédente"). Les scénarios gardent l'ORDRE
  d'écriture du créateur (jamais mélangés, contrairement à
  Association/Memory/Mots mêlés — ce sont des mises en situation
  séquentielles, pas des éléments à faire correspondre/retrouver).
  Réutilise les classes visuelles du Quiz (`.docQuizOptions`/
  `.docQuizFeedback`/`.docQuizNextBar`/`.docQuizQuestionText`) plutôt que
  de dupliquer ces règles. Embarqué en
  JSON dans un attribut `data-scenario-config`, échappé pour l'HTML —
  même principe que les autres mini-jeux, aucun aller-retour serveur
  pendant qu'on joue. Comme l'Association/Memory/Mots mêlés (mais
  contrairement au Quiz), le dernier scénario reste affiché une fois
  répondu : seul le bouton "Recommencer" (`.docMinigameRestartBar`)
  apparaît.
- **Autres mini-jeux** (`zones`) : carte placeholder portant le libellé
  du type (voir `document_engine/labels/element_kind_labels.py`) —
  emplacement réservé, formulaire de contenu dédié hors périmètre de
  cette passe.