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.
• 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.
• Liste à puces/numérotée (liste_puces/liste_numerotee) : <ul> ou <ol> selon le kind (fonction privée _render_list, partagée par les deux) — un <li> par entrée de attributes["items"]. Une liste vide rend <ul>/<ol> sans enfant plutôt qu'un placeholder : contrairement à une image sans fichier, ce n'est pas un état anormal.
• 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 : un scénario est un ARBRE DE DÉCISION (voir scenario_config.py pour la forme exacte — nodes[0] = situation initiale, chaque choix pointe vers un autre nœud via target_id, un nœud sans choix est une fin de branche), pas une simple question à une seule conséquence. Aucune notion de bonne/mauvaise réponse (retour utilisateur du 20/09/2026 : "il n'y a pas de notion vrai/faux, l'utilisateur observe les conséquences") : l'apprenant choisit une option, le texte du nœud visé REMPLACE l'affichage du nœud précédent (les boutons de choix disparaissent avec lui), et ainsi de suite jusqu'à une fin de branche — volontairement PAS le comportement du Quiz, où la question resterait affichée à côté d'un encart de feedback séparé. Une fois une fin de branche atteinte, passage au scénario (arbre) suivant. 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/ .docQuizNextBar/.docQuizQuestionText) plutôt que de dupliquer ces règles. L'arbre complet (tous les nœuds/choix de tous les scénarios) est 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 : toute la navigation dans l'arbre se fait côté client. Comme l'Association/Memory/Mots mêlés (mais contrairement au Quiz), le dernier scénario reste affiché une fois une fin de branche atteinte : seul le bouton "Recommencer" (.docMinigameRestartBar) apparaît. L'arbre lui-même se construit dans une MODALE dédiée depuis le panneau Propriétés (voir forgeDocOpenScenarioTreeModal, static/document/js/document-editor.js) — trop de structure (nœuds + choix + destinations) pour la colonne étroite du panneau Propriétés, contrairement aux autres mini-jeux. La modale est un VRAI graphe visuel (retour utilisateur du 21/09/2026) : chaque nœud a une position x/y (voir scenario_config.py), affiché comme une carte déplaçable à la souris sur un canevas ; chaque choix relié à un target_id est dessiné comme une flèche SVG étiquetée par son texte, jamais un simple menu déroulant. Éditer le texte/les choix d'un nœud se fait dans l'inspecteur (panneau de droite) du nœud sélectionné ; relier un choix se fait en cliquant "Relier" puis le nœud cible sur le graphe (mode connexion, Échap annule).
• 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.