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`/`strikethrough`/
  `align`/`color`. `underline`/`strikethrough` se combinent dans un seul
  `text-decoration` (`"underline line-through"` si les deux sont actifs).
  `font_size`/`line_height` (vides par défaut) remplacent les valeurs du
  préréglage `style` SANS toucher `font-weight` (toujours piloté par le
  préréglage + `bold`). `text_transform` (`"none"` par défaut) ajoute
  `text-transform` quand différent de `"none"`. `font_family`/
  `letter_spacing`/`text_shadow` (vides par défaut) ajoutent leur
  déclaration CSS respective quand non vides. `max_width` (optionnel, ex.
  `"60ch"`, `"480px"`) ajoute `max-width` au style inline quand non vide —
  pleine largeur de `.docPageContent` par défaut, retour utilisateur du
  24/09/2026 (un paragraphe doit pouvoir rester plus étroit que la page,
  sans dépendre d'une rangée qui en partagerait la largeur avec un frère).
  Termine par `render_box_style(a)` (voir `box_style.py` ci-dessous) pour
  `padding`/`margin`/`background_color`/`border_radius`/`border`/
  `align_self` — attributs PARTAGÉS avec d'autres kinds, jamais dupliqués
  ici (audit du 26/09/2026, réglages manquants à couvrir élément par
  élément en réutilisant ce module).
- **Image** : `<img>`, ou un bloc placeholder si `src` est vide — OU, si
  `attributes["svg_markup"]` est non vide (prioritaire sur `src`), un
  `<div>` portant directement ce fragment SVG nettoyé par
  `sanitize_svg_markup` (voir `sanitize_svg_markup.py` ci-dessous) : un
  contenu vectoriel dessiné/collé par le créateur plutôt qu'un fichier
  hébergé. Style inline : `object_fit` (`"cover"`/`"contain"`/`"fill"`,
  toute autre valeur ignorée), `aspect_ratio` (valeur CSS libre, ex.
  `"16 / 9"`), `filter_preset` (`"grayscale"`/`"sepia"`/`"blur"`, mappé
  vers une vraie valeur `filter` CSS fixe — jamais une valeur de filtre
  libre) + les attributs de boîte partagés (`render_box_style`, voir
  `box_style.py`). `lazy_load` (`True`) ajoute `loading="lazy"` sur
  l'`<img>` uniquement (comportement, pas du style). `click_behavior`
  (`""`/`"link"`/`"lightbox"`) enveloppe le tout dans un `<a target="_blank"
  rel="noopener noreferrer">` (si `link_url` est aussi renseigné) ou un
  `<div class="docImageLightboxTrigger">` — les deux ne deviennent
  réellement cliquables qu'en Mode Aperçu (voir static/document/js/
  document-editor.js::forgeDocBindCanvasInteractions/
  forgeDocOpenImageLightbox), même principe que les mini-jeux et la
  pièce jointe d'un bouton. `caption` (non vide) enveloppe le tout dans
  un `<figure><figcaption>` échappée.
- **Bouton** : `<button>` avec son `label` (enveloppé dans
  `<span class="docButtonLabel">`), un `data-target` optionnel
  (navigation) et un `data-attachment-filename` optionnel — marqueur
  mécanique posé quand un fichier a été joint (voir
  `routes/document/document_element_upload_attachment.py`), jamais
  l'URL de téléchargement elle-même (ce renderer ne connaît pas le slug
  du support ; `static/document/js/document-editor.js` l'assemble à
  partir de `data-element-id` + `FORGE_DOCUMENT.slug`, même principe que
  le reste des appels AJAX de l'éditeur). Style inline (audit du
  26/09/2026, réglages manquants — colonne "Bouton") : `bold` pousse
  `font-weight` à `800` (jamais en dessous du `700` déjà posé par le CSS
  de base — "gras" ne fait que renforcer, jamais affaiblir, aucune
  régression visuelle sur les boutons déjà créés), `italic`/
  `text_transform` (`"uppercase"`/`"lowercase"`/`"capitalize"`, jamais
  `"none"`)/`font_family`/`font_size`/`letter_spacing`/`text_color`
  (vides par défaut) + les attributs de boîte partagés
  (`render_box_style`, voir `box_style.py`). `svg_markup` (optionnel,
  nettoyé par `sanitize_svg_markup`) ajoute un `<span
  class="docButtonIcon">` avant OU après `.docButtonLabel` selon
  `icon_position` (`"before"` par défaut), dimensionné par `icon_size`
  (vide = `1em`, suit la taille du texte). États interactifs
  survol/actif : effet CSS universel (`filter`/`transform`, voir
  `static/document/document-editor.css`), jamais configurable par
  attribut — pas de notion d'état "désactivé" pour un bouton de contenu
  (ce n'est pas un vrai contrôle de formulaire).
- **Étiquette** (`badge`) : `<div>` portant `attributes["content"]`
  échappé, précédé d'un `<span class="docBadgeIcon">` optionnel si
  `svg_markup` est non vide (nettoyé par `sanitize_svg_markup`, même
  mécanisme que le mode SVG de `"image"`). `width` (non vide) ajoute
  `align-self:flex-start; width:{valeur};` en style inline — fixer une
  largeur implique TOUJOURS de sortir de l'étirement pleine largeur par
  défaut d'un enfant flex en colonne (voir static/document/
  document-editor.css, `.docPageContent`), jamais l'un sans l'autre.
  `border_radius` (non vide) ajoute `border-radius:{valeur};`. `bold`/
  `uppercase` ajoutent respectivement `font-weight:800;`/
  `text-transform:uppercase;` quand `True`. Tous ces attributs sont vides
  ou `False` par défaut (comportement historique inchangé, aucun style
  inline ajouté).
- **Carte** (`carte`) : `<div>` composé de trois blocs enfants
  (`label`/`title`/`description`, tous échappés) — contenu pur, aucune
  couleur/forme choisie ici (voir `element_kind_labels.md`).
- **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.
  Style inline (audit du 26/09/2026, portée actée avec l'utilisateur :
  la LISTE ENTIÈRE uniquement, jamais par élément individuel ni de
  sous-listes) : `bold`/`italic`/`underline`/`font_family`/`font_size`/
  `line_height`/`text_color` (typo, `_list_text_style`) +
  `list_style_type` (validé selon le `kind` — `disc`/`circle`/`square`/
  `none` pour `liste_puces`, `decimal`/`decimal-leading-zero`/
  `lower-roman`/`upper-roman`/`lower-alpha`/`upper-alpha`/`none` pour
  `liste_numerotee`, toute autre valeur ignorée)/`list_style_position`
  (`"outside"` par défaut) + les attributs de boîte partagés
  (`render_box_style`, voir `box_style.py`). `marker_color`/
  `marker_size`/`item_padding`/`item_spacing` (`_list_marker_style`/
  `_list_item_style`) passent par des PROPRIÉTÉS PERSONNALISÉES CSS
  (`--doc-marker-color`/`--doc-marker-size`/`--doc-item-padding`/
  `--doc-item-spacing`) : un style inline sur le `<ul>`/`<ol>` ne peut
  pas cibler directement le `::marker` ou le padding de ses `<li>`
  enfants autrement — ces propriétés sont posées sur le conteneur et
  consommées par `static/document/document-editor.css`
  (`.docList li`/`.docList li::marker`), qui hérite jusque-là.
  `svg_markup` (liste à puces UNIQUEMENT, ignoré pour `liste_numerotee`)
  : puce personnalisée — nettoyé par `sanitize_svg_markup` puis encodé
  en URI de données (`urllib.parse.quote`) pour `list-style-image`, qui
  prime visuellement sur `list_style_type` dès qu'il est posé.
  `render_content_align(a)` (voir `box_style.py`) également ajouté :
  `.docList` est `display:flex; flex-direction:column;` (un `<li>` garde
  son `display:list-item` propre — puce/numéro visibles — même une fois
  flex-item, ce sont deux notions indépendantes en CSS).
  **Bug réel corrigé** (retour utilisateur du 26/09/2026 : "si j'enlève
  les puces ou que les puces se mettent à l'intérieur, il reste un
  espace devant la liste, cet espace doit être supprimé") :
  `padding-left:0;` est ajouté automatiquement dès que
  `list_style_type="none"` ou `list_style_position="inside"` — le
  `padding-left:1.4em` par défaut (`.docList`, réservé pour une puce
  EXTÉRIEURE) n'a alors plus lieu d'être ; un `padding` uniforme réglé
  explicitement par ailleurs (attributs de boîte partagés) reste
  prioritaire (déclaré après, dans le même style inline).
- **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.

## `box_style.py` — attributs de "boîte" partagés entre plusieurs kinds

Audit du 26/09/2026 (réglages manquants, à couvrir élément par élément) :
padding/margin/couleur de fond/arrondi/bordure par côté/position du bloc
sont des besoins IDENTIQUES pour la plupart des kinds de contenu — un
seul jeu d'attributs et une seule fonction de rendu ici, jamais réécrits
à chaque kind (voir `_render_text` pour le premier usage réel).

### `BORDER_SIDES: tuple[str, ...]`
`("top", "right", "bottom", "left")`.

### `default_border() -> dict[str, dict[str, str]]`
Un dict à 4 clés (`BORDER_SIDES`), chacune `{"style": "none", "width":
"1px", "color": "var(--doc-border)"}`.
- **Retour** : un NOUVEAU dict à chaque appel (jamais un littéral partagé
  muté par référence entre deux éléments — même précaution que
  `DEFAULT_QUIZ_CONFIG` côté `labels/`).
- **Exceptions** : aucune.

### `BOX_DEFAULTS: dict[str, Any]`
`{"padding": "", "margin": "", "background_color": "", "border_radius":
"", "align_self": "stretch", "width": "", "max_width": "", "height": "",
"min_height": "", "max_height": "", "min_width": "", "box_shadow": "",
"opacity": "", "content_align": "top"}` — `border` n'y figure PAS (voir
`default_border()`, à ajouter séparément par chaque appelant pour éviter
le partage par référence).

### `render_box_style(a: dict[str, Any]) -> str`
Construit les déclarations CSS inline pour chaque attribut listé dans
`BOX_DEFAULTS` (padding/margin/background_color/border_radius/width/
max_width/height/min_height/max_height/min_width/box_shadow/opacity) +
`border`/`align_self` de `a`, via une table de correspondance
(clé d'attribut, propriété CSS) plutôt qu'un bloc `if` par attribut
(complexité cognitive — voir `_render_simple_properties`/`_render_border`,
privées) — un attribut absent ou à sa valeur par défaut ne produit
AUCUNE déclaration (comportement historique inchangé). `border` est un
dict à 4 clés
(`BORDER_SIDES`), chacune `{"style", "width", "color"}` — un côté à
`style="none"` (ou absent) ne produit rien pour ce côté, jamais un
`border-top:none` explicite. `align-self` n'est ajouté que si différent
de `"stretch"` (déjà le comportement par défaut d'un enfant flex en
colonne).
- **Retour** : les déclarations CSS (`"propriete:valeur; ..."`), chaîne
  vide si rien à ajouter.
- **Exceptions** : aucune.

### `render_content_align(a: dict[str, Any]) -> str`
Alignement vertical du CONTENU à l'intérieur de son propre bloc (retour
utilisateur du 26/09/2026 : "je peux augmenter la hauteur d'un
conteneur mais pas l'alignement vertical à l'intérieur") — `content_align`
(`"top"` par défaut, `"center"` ou `"bottom"`) mappé vers
`justify-content` (`""` pour `"top"`, comportement historique inchangé).
Jamais fusionné dans `render_box_style` : contrairement à `align_self`
(position du BLOC dans SON parent, valable pour tout consommateur),
l'alignement du CONTENU dépend de l'axe interne du conteneur —
`justify-content` convient à un conteneur en colonne (`_render_text`/
`_render_list`, dont les classes CSS `.docText`/`.docList` sont
`display:flex; flex-direction:column;`, et la figure d'une image
légendée, déjà flex-colonne), mais serait FAUX pour le Bouton (rangée
icône+texte : l'axe vertical y est déjà géré par `align-items`, voir
`static/document/document-editor.css`, `.docButton`) — chaque renderer
qui veut ce comportement l'appelle donc explicitement lui-même.
- **Retour** : `""` si absent/`"top"`/valeur inconnue, sinon
  `"justify-content:...;"`.
- **Exceptions** : aucune.

## `sanitize_svg_markup.py` — nettoyage du contenu SVG inline d'une image

### `sanitize_svg_markup(markup: str) -> str`
Nettoie un fragment SVG selon une LISTE BLANCHE de balises/attributs
(`_ALLOWED_TAGS`/`_ALLOWED_ATTRS`, privées) — construit sur
`html.parser.HTMLParser` (tokenizer de balises pur, sans DTD ni
résolution d'entité externe) plutôt qu'un analyseur XML, qui resterait
exposé aux attaques classiques d'entité externe sur une entrée non
fiable. Toute balise absente de la liste blanche (`<script>`,
`<foreignObject>`, `<a>`, `<use>`, `<image>`...) disparaît AVEC son
contenu ; tout attribut absent (`on*`, `style`, `href`/`xlink:href`,
`class`...) disparaît seul, la balise porteuse étant conservée si elle
est autorisée. Appelé à CHAQUE rendu (`_render_image`), jamais
seulement à l'écriture — même défense en profondeur que
`html.escape` sur les autres kinds.
- **Retour** : le fragment SVG nettoyé, sûr à insérer tel quel dans le
  HTML rendu.
- **Exceptions** : aucune.