# GAB-309 · DocumentLearningImageAnalysis — « Analyser une image »

**Archétype / renderer_key :** `annotation_media` (cartographie) · **module :** EdTechDocumentLearning
**Critère validé :** changer le JSON change les zones, modes et feedbacks sans modifier le HTML.

## Pack (structure officielle par-GAB)
```
GAB-309/
  renderer.html            ← moteur annotation image (ne pas modifier par instance)
  instance.example.json    ← SOURCE DE VÉRITÉ (contenu réel, à plat)
  schema.contract.json     ← contrat de validation
  README-contract.md       ← ce fichier
```

## Archétype
GAB-309 est un écran d'**annotation de zones sur image** avec deux modes d'interaction :
- **Observer** : l'élève clique des zones pour révéler les faits visibles (composition, symboles).
- **Interpréter** : mode bloquant tant que les faits n'ont pas été observés (garde-fou pédagogique).

Chaque zone peut être une zone normale (feedback positif si cliquée en mode observe) ou un **piège** (is_trap:true, ex. zone OCR floue — déclenche un avertissement, jamais une réponse inventée).

## Champs requis (instance, à plat)
`gab_id` · `image_analysis_id` · `zones[]{zone_id,kind,emoji,style,feedback_observe,is_trap}` · `mode_labels{observe,interpret}`

Optionnels : `title`, `image_ref{src,alt,caption}`, `observe_instruction`, `interpret_guard`, `min_zones_for_success`, `use_when`, `do_not_use_when`, `accessibility`, `child_safety`.

## Ce qui vient du JSON vs HTML
- **JSON** : libellés des boutons de mode, instruction observe, message interpret_guard, chaque zone (position CSS, emoji, kind, feedback, is_trap), nombre minimal de zones à trouver, listes use_when/do_not_use_when.
- **HTML** : moteur de rendu, gestion des événements, styles DS V2, structure scène/mode-row/panel, slot-chips.

## Garde-fous (child_safety)
- **Anti-invention** : les zones et feedbacks sont extraits du prototype HTML source — aucun contenu pédagogique inventé.
- **Zone OCR (is_trap:true)** : déclenche un panel warn avec ⚠, jamais une réponse devant le texte illisible.
- **Mode interpréter** : bloque le clic sur toute zone et affiche `interpret_guard` — force l'observation préalable.
- **BLOCKED** si `image_analysis_id` absent / `zones` vides / `mode_labels` incomplet.

## _TODO (contenus manquants à compléter avant déploiement)
- `image_ref.src` : chemin de l'image réelle (valeur `_TODO:assets/image-demo-309.jpg` dans l'exemple).
- `image_ref.alt` : description textuelle de l'image réelle (accessibilité obligatoire).
- `image_ref.caption` : légende ou titre de l'image si disponible.

Ces trois champs portent le préfixe `_TODO` dans l'instance exemple — l'instance reste structurellement valide mais doit être complétée pour tout déploiement pédagogique réel.

## QA à vérifier
1. Modifier un `feedback_observe` → rendu change sans toucher au HTML (critère d'or).
2. `zones:[]` → BLOCKED propre.
3. Clic zone `is_trap:true` en mode observe → panel warn ⚠, zone non cochée.
4. Clic zone en mode interpréter → panel warn `interpret_guard`.
5. Trouver `min_zones_for_success` zones non-piège → `foot` mis à jour.
6. Responsive 375/768/1024.

## Source
`INDEX-300-documentlearning-GAB-306-310-PLAYABLE.html` (stage `data-tpl="309"`, handlers `d309Mode`, `d309Zone`).

## external_refs / dependencies
- GAB-308 (DocumentLearningChartAnalysis) : cité dans `do_not_use_when` ("graphique → 308") — même lot, même module.
- DS V2 palette : violet `#7B61FF`, mint `#1FCBB0`, gold `#FFB73D`, coral `#FF6B7E`, sky `#4DA8FF` — aucune ombre rgba(0,0,0,…).