# GAB-004 · SessionProgressHeader — « Header de progression compact »

**Archétype / renderer_key :** `text_cta` (cartographie) · **module :** EdTechPlayEngine
**Critère validé :** changer le JSON change le header sans modifier le HTML.

## Pack (structure officielle par-GAB)
```
GAB-004/
  renderer.html            ← moteur header de progression (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
```

## Champs requis (instance, à plat)
`gab_id` · `session_progress_id` · `title` · `current_index` · `total_steps` · `progress_percent`

Optionnels : `icon`, `step_label_template` (variables `{current}` et `{total}`), `cta_label`.

## Ce qui vient du JSON vs HTML
- **JSON** : titre de session, icône, étape courante, total étapes, pourcentage barre, libellé template, libellé CTA.
- **HTML** : layout header, barre de progression, génération dynamique des dots, bouton CTA structurel, animation `dot-pulse`.

## Comportement moteur
- Les dots sont **générés dynamiquement** depuis `total_steps` — jamais listés en dur dans l'instance.
- Cliquer un dot appelle `renderStep(n)` : recalcule le % affiché, met à jour les classes `done`/`current`.
- Le CTA avance d'une étape (simulation PlayEngine) et affiche un panel de confirmation.
- `init(ext)` permet l'injection externe — priorité `arguments.length && ext` sur `window.GAB_INSTANCE`.

## Garde-fous
- **BLOCKED** si `title`, `current_index`, `total_steps` ou `progress_percent` absent.
- `total_steps >= 2` (header sans intérêt pour session à une seule étape).
- `current_index` dans `[1, total_steps]` (vérifié en QA, non enforced en JS pour ne pas bloquer les cas limites).
- Zéro ombre noire (DS V2) : `box-shadow` colorées uniquement (`rgba(123,97,255,...)`, `rgba(178,60,224,...)`).

## QA à vérifier
1. Modifier `title`/`current_index`/`total_steps` → rendu change sans toucher au HTML (critère d'or).
2. `title` absent → BLOCKED propre.
3. `current_index = 1` → aucun dot `done`, premier dot `current`, barre à `progress_percent%`.
4. `current_index = total_steps` → tous dots précédents `done`, dernier dot `current`.
5. Clic CTA → avance d'une étape + panel de confirmation.
6. Responsive 375/768/1024 — dots wrappent, pas de débordement.

## Source
`INDEX-300-playengine-GAB-001-005-PLAYABLE.html` (stage `data-tpl="4"`, handler `phGo`, classes `.progress-header`, `.progress-dots`).

## external_refs / dependencies
- Fait partie du lot `LOT-playengine-GAB-001-005` (GAB-001 à GAB-005).
- Utilisé conjointement avec **GAB-003** (SessionStepPlayerShell) : ce header se place au-dessus du shell step.
- Référencé négativement par **GAB-008** (événement ponctuel de sauvegarde) et **KIT-043** (résumé de fin de session) — ces GABs couvrent des cas distincts.