# Moteur en WebAssembly : page de test, contrat et mesures

- **Date** : 2026-11-02
- **Étape** : 0b
- **Statut** : en cours
- **Exécutant** : sous-agent general-purpose, dans un worktree isolé

## Objectif

Le même moteur (`engine/`, `engine.h`) compilé en WebAssembly tourne dans un
Web Worker d'une page web minimale servie sur le réseau local. Il donne les
mêmes résultats que le moteur natif sur les 32 positions de référence, et une
page de mesure produit les chiffres qui permettront de trancher entre PWA et
Android natif (`docs/etape-0.md`, section 0b).

## Consignes

1. **Compilation** : `make engine-wasm` compile le moteur avec Emscripten, dans
   l'image `emscripten/emsdk:3.1.64` (déjà téléchargée ; version figée),
   en C générique (pas de SIMD), sans threads, `-j2`. Sorties dans
   `build/wasm/`. Les données (`gnubg.weights` ou `gnubg.wd`, bases `.bd`,
   table d'équité) viennent de `build/data/` produit par `make engine`, et sont
   chargées une fois (système de fichiers virtuel d'Emscripten ou équivalent
   simple). Recompilation minimale si rien n'a changé. Cible visible dans
   `make help`.
2. **Interface JavaScript minimale** au-dessus d'`engine.h` (par exemple
   `bestMoves`, `cubeDecision`, `evaluate`, `reference`), qui renvoie les mêmes
   objets JSON que `engine-cli`. Réutiliser le code de mise en JSON
   d'`engine-cli` plutôt que de le réécrire, si c'est simple.
3. **Même suite de contrat** (ADR 0007, point 7) : rejouer les 32 positions de
   référence aux niveaux 0 et 2 plis avec le build WebAssembly, sous Node (dans
   l'image Emscripten, qui contient Node, ou une image Node figée), avec le
   même comparateur `tests/reference/compare.py` et la même tolérance. Le plus
   simple : un petit programme Node qui imite l'interface en ligne de commande
   d'`engine-cli`, et une option du comparateur pour choisir le programme
   interrogé. Test lancé par `make test` (`tests/test_wasm_reference.sh`).
4. **Page de test `web/`** (HTML, CSS et JavaScript sans framework ni étape de
   build) : moteur chargé dans un Web Worker, jamais sur le fil d'affichage ;
   saisie d'un Position ID, d'un Match ID et des dés ; bouton « Meilleur coup » ;
   affichage du résultat et du temps de calcul. Textes en français, identifiants
   en anglais.
5. **Page de mesure** (dans `web/`) : sur une série de positions de référence,
   temps du meilleur coup à 0 et 2 plis et de la décision de videau à 2 plis
   (médiane et maximum), temps de chargement du moteur, taille totale
   téléchargée (non compressée et compressée gzip), mémoire WebAssembly
   utilisée. Un bouton « Copier les résultats » met un rapport texte dans le
   presse-papiers, que Pierre collera dans la conversation. La page compare
   elle-même aux seuils de `docs/etape-0.md`.
6. **`make deploy-web`** sert `web/` et `build/wasm/` sur le réseau local
   (serveur dans Docker, rien sur le PC ; types MIME corrects dont
   `application/wasm`), et affiche l'adresse exacte à ouvrir depuis le
   téléphone (IP du PC sur le réseau local). Le serveur s'arrête par Ctrl+C.
   Mettre à jour la cible `deploy` si pertinent.
7. **`make bench`** : la même mesure que la page, sous Node, sur le PC, pour un
   premier ordre de grandeur (le chiffre qui compte reste celui du téléphone).
8. **Guide de test** pour Pierre : `docs/guide-test-etape-0.md` (document
   temporaire de l'étape 0), pas à pas : préparer le PC, lancer
   `make deploy-web`, ouvrir l'adresse sur le Fairphone 4 (même Wi-Fi), faire un
   essai de meilleur coup, lancer la page de mesure, copier le rapport et le
   coller dans la conversation. Phrases courtes, aucune connaissance technique
   supposée, que faire si la page ne s'ouvre pas (pare-feu, réseau).

Contraintes :
- respecter `CLAUDE.md` et les ADR 0004, 0005, 0007 : simplicité, pas de
  framework, identifiants en anglais, commentaires et textes en français, tout
  outil dans Docker ;
- ne pas modifier `engine/gnubg/` ni les références ; toute adaptation du
  moteur passe par `engine/compat/` ou le code d'Ustagammon ;
- signaler chaque nouvelle dépendance et sa licence dans `CREDITS.md`
  (Emscripten : MIT/NCSA) ;
- `make lint` et `make test` doivent passer ; commits petits, en français, avec
  la ligne `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>` ;
- ne pas pousser ni créer de merge request ;
- ne rien simuler : les mesures viennent d'exécutions réelles.

Rapport attendu : ce qui a été fait, commandes de vérification, taille des
fichiers téléchargés, mesures `make bench` sur le PC, résultat de la suite de
contrat en WebAssembly (écart maximal), difficultés, écarts au plan.

## Critères de réussite

- `make engine-wasm` puis `make test` : les 32 positions concordent en
  WebAssembly avec la même tolérance qu'en natif.
- `make deploy-web` affiche une adresse ; la page donne le meilleur coup d'une
  position de référence avec son temps de calcul (vérifié dans un navigateur
  sans interface si possible, sinon par une requête HTTP sur les fichiers).
- `make bench` produit un rapport.
- `make lint` et `make test` passent.

## Résultat

À remplir à la clôture.