ki-fwi/docs/adr/0002-phaser-hors-budget-initial.md

# ADR 0002 — Phaser 4 et l'écart au budget JS

- **Statut :** accepté, avec mesure à compléter en session 4
- **Date :** 2026-07-27
- **Session :** 0 — cadre et données

## Contexte

Le playbook OKI §2.7 fixe un budget non négociable de **170 Ko de JS initial compressé**.
Le mode arcade « Ranmasé » demande de la physique, des particules et du *game feel* : le
faire en DOM coûterait plus cher en travail et en performance qu'un moteur éprouvé.

Le pack d'origine prescrivait « Phaser 5 ». **Phaser 5 n'existe pas.** Vérification faite
au démarrage de la session :

```
$ npm view phaser version
4.2.1
```

La branche courante est Phaser 4 — 4.0 « Caladan » (avril 2026), 4.1 « Salusa »,
4.2 « Giedi » — avec un moteur WebGL réécrit en *render nodes*. Partir de Phaser 3 aurait
été partir d'une branche en fin de vie.

## Décision

Utiliser **`phaser@^4`** (4.2.1 au moment de la décision), et assumer un **écart documenté**
au budget JS, borné par quatre conditions :

1. Phaser n'est **jamais** dans le chemin critique. Import dynamique dans la route
   `(jeu)/ranmase` uniquement, jamais au layout racine.
2. Le shell reste **≤ 170 Ko gzip**, Phaser exclu. Le budget n'est pas relâché : il est
   mesuré à part.
3. L'entrée dans la scène passe derrière un **écran de chargement designé** (playbook P5,
   en KA avec le tambour `ka`), pas derrière une page blanche.
4. Rendu `AUTO` (WebGL avec repli canvas), DPR plafonné à **1,5**,
   `powerPreference: 'low-power'`, cible **30 fps stables sur Mali-G52**.

## Conséquences

- Le budget d'entrée du site (≤ 2 Mo) et les Core Web Vitals (LCP < 2,5 s, INP < 200 ms,
  CLS < 0,05) restent mesurés **sur l'accueil et sur une fiche**, pages qui ne chargent
  jamais Phaser.
- Un utilisateur qui ne joue jamais au mode arcade ne télécharge jamais Phaser. Les quatre
  autres modes sont en Svelte pur (ADR 0003).
- La session 4 doit renseigner ici la **mesure réelle** du bundle Phaser en gzip et le
  relevé de fps sur mobile d'entrée de gamme.

### Mesures — à compléter en session 4

| Mesure | Cible | Relevé (2026-07-27) |
|---|---|---|
| Shell JS initial, Phaser exclu (gzip) | ≤ 170 Ko | **78 Ko** ✅ |
| Bundle Phaser seul (gzip) | information | **348 Ko** — sous le seuil de réexamen de 450 Ko |
| Phaser dans le chemin critique de l'accueil | absent | **absent**, vérifié sur le HTML prérendu ✅ |
| Poids total du build | ≤ 2 Mo | **1,4 Mo** ✅ |
| fps scène Ranmasé sur Mali-G52 | ≥ 30 stables | **non mesuré** — demande un appareil réel |

Le total JS du site atteint 426 Ko gzip, mais 348 Ko ne sont téléchargés qu'à l'entrée dans
`/je/ranmase/`. Un visiteur de l'encyclopédie ne les voit jamais.

### Correction apportée à cet ADR par la mise en œuvre

Cet ADR prescrivait un « DPR plafonné à 1,5 » via l'option `resolution`. **Cette option
n'existe pas dans Phaser 4** : `pixelRatio` y est une information matérielle en lecture
seule, et `resolution` avait déjà été neutralisée en Phaser 3.

L'objectif est atteint autrement, et mieux : le tampon de rendu est fixé à **480 × 640**,
étiré en CSS par le mode `FIT`. Le GPU dessine donc toujours 480 × 640 pixels, quel que
soit le DPR de l'appareil — c'est-à-dire un plafond dur, là où `resolution` n'aurait donné
qu'un plafond relatif.

`powerPreference: 'low-power'` existe bien, sous la clé `render`.

## Condition de réexamen

Si la mesure de session 4 montre que Phaser dépasse ~450 Ko gzip, ou que les 30 fps ne
sont pas tenus sur mobile d'entrée de gamme, la scène « Ranmasé » est réécrite en DOM/CSS
avec une boucle rAF maison — le playbook P3 (« DOM d'abord, WebGL seulement où ça paie »)
reprend alors la main. Les quatre autres modes n'en dépendent pas : le jeu reste entier.