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.
- **Autres mini-jeux** (`scenario`/`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.