Plan 0b : résultat, documentation de la suite WebAssembly

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/guide-test-etape-0.md

@@ -61,7 +61,9 @@ Comptez un quart d'heure.
 
 Si vous en avez le temps, refaites la mesure une deuxième fois (rechargez la
 page de mesure) et collez aussi ce second rapport : cela montre si les temps
-sont stables.
+sont stables. Si les deux navigateurs sont installés, faites la mesure dans
+Chrome **et** dans Firefox : sur le PC, Firefox s'est montré nettement plus
+lent, et le rapport indique le navigateur utilisé.
 
 ## Si la page ne s'ouvre pas
 

docs/plans/2026-11-02-moteur-webassembly.md

@@ -89,4 +89,69 @@ contrat en WebAssembly (écart maximal), difficultés, écarts au plan.
 
 ## Résultat
 
-À remplir à la clôture.
+**Statut : terminé** (2026-11-02, branche `wasm-travail`). Tous les critères
+de réussite sont tenus ; reste la mesure sur le Fairphone 4 par Pierre
+(`docs/guide-test-etape-0.md`).
+
+Ce qui a été fait :
+
+- `make engine-wasm` (`engine-wasm/wasm.mk`) compile dans
+  `emscripten/emsdk:3.1.64` les mêmes sources que le natif (liste commune
+  `engine/sources.mk`), plus `engine-cli/main.c`, en C générique, sans
+  threads, `-O3 -ffast-math`. Les données de `build/data/` sont embarquées
+  dans `engine.data` (`--preload-file`, système de fichiers virtuel, `/data`).
+  Recompilation nulle si rien n'a changé.
+- Interface JavaScript (`web/engine-wasm.mjs`) : le module appelle
+  `engine_init` une fois, puis `main` d'engine-cli pour chaque commande
+  (`callMain`) ; la sortie est exactement le JSON d'engine-cli, sans code de
+  mise en JSON dupliqué. Seule modification du C : `main` n'appelle pas
+  `engine_shutdown` sous Emscripten. Fonctions `bestMove`, `cubeDecision`,
+  `evaluate`, `reference`.
+- Suite de contrat : `tests/test_wasm_reference.sh` (lancé par `make test`)
+  rejoue les 32 positions à 0 et 2 plis sous Node avec
+  `engine-wasm/engine-cli.mjs`, qui imite engine-cli ; `compare.py --cli`
+  accepte désormais une commande avec arguments. Résultat : **2 598 nombres
+  comparés, écart maximal 9,53e-4** (le même cas `opening-64-match` qu'en
+  natif), tolérance 2e-3. Comparé directement au natif : mêmes classements,
+  mêmes décisions, écart maximal 2,3e-6.
+- `web/` : page de test (`index.html`), page de mesure (`bench.html`),
+  Worker en module ES (`engine-worker.mjs`), client (`engine-client.mjs`),
+  mesure partagée avec Node (`benchmark.mjs`). Aucun framework, aucune étape
+  de build.
+- `make deploy-web` : serveur HTTP de Python dans l'image `build-c` (aucune
+  nouvelle image), adresse LAN affichée (route par défaut), Ctrl+C l'arrête
+  (vérifié). `make deploy` renvoie vers `make deploy-web`. `make bench` :
+  même mesure sous Node.
+
+Vérification de la page : Chromium 130 et Firefox 131 sans interface (image
+`mcr.microsoft.com/playwright:v1.48.2-noble`, utilisée une fois, hors du
+dépôt), ouverts sur l'adresse LAN `http://192.168.1.21:8080/` (contexte non
+sécurisé, comme le téléphone) : meilleur coup de `middlegame-1` à 2 plis
+(`24/14`, 305 ms Chromium, 2 433 ms Firefox), mesure complète, bouton de copie
+fonctionnel. Types MIME vérifiés par curl : `application/wasm`,
+`text/javascript` pour les `.mjs`.
+
+Mesures sur le PC (i5-2450M, 2011) :
+
+| Mesure (max sur les positions) | Node 18 | Chromium 130 | Firefox 131 | Seuil |
+| --- | --- | --- | --- | --- |
+| Meilleur coup 0 pli | 2 ms | 5 ms | 14 ms | 300 ms |
+| Meilleur coup 2 plis (médiane / max) | 107 / 454 ms | 87 / 316 ms | 693 / 2 341 ms | 3 000 ms |
+| Videau 2 plis (médiane / max) | 27 / 109 ms | 21 / 103 ms | 158 / 902 ms | 3 000 ms |
+| Chargement du moteur | 82 ms | 178 ms | 204 ms | |
+| Mémoire WebAssembly | 51,9 Mo | 51,9 Mo | 51,9 Mo | |
+
+Taille téléchargée : 9,0 Mo non compressée, **7,3 Mo compressée gzip** (seuil
+40 Mo), dont `engine.data` 8,7 Mo (7,2 Mo gzip), `engine.wasm` 180 Ko
+(78 Ko gzip), `engine.mjs` 73 Ko (20 Ko gzip).
+
+Points d'attention : Firefox sans interface est environ 7 fois plus lent que
+Chromium sur le même PC, à vérifier sur le téléphone (le guide demande les
+deux navigateurs). La mémoire de 52 Mo vient surtout des bases de fin de
+partie copiées en mémoire et du cache d'évaluation de gnubg ; les données
+existent en plus une fois côté JavaScript (système de fichiers virtuel).
+
+Écarts au plan : aucun sur le fond. Fichiers en `.mjs` (modules ES partagés
+entre navigateur et Node sans `package.json`) ; seuils jugés sur le maximum,
+la médiane étant donnée en plus ; la taille compressée est calculée par la page
+(CompressionStream) car le serveur de test ne compresse pas.

tests/reference/README.md

@@ -232,8 +232,13 @@ comparateur `compare.py` (Python 3, dans l'image Docker de la chaîne C) lance
 build/engine-cli --ply N reference POSITION_ID MATCH_ID [DÉS]
 ```
 
-qui produit un objet de même structure que `plies["<n>"]` : `evaluation`,
-puis `moves` (avec les dés) ou `cube` (sans). Le classement des coups suit la
+La même suite est rejouée sur le moteur compilé en WebAssembly
+(`tests/test_wasm_reference.sh`), avec le même comparateur et la même
+tolérance : `--cli "node engine-wasm/engine-cli.mjs"` interroge, sous Node
+dans l'image Emscripten, le même programme compilé en WebAssembly.
+
+Le programme interrogé produit un objet de même structure que
+`plies["<n>"]` : `evaluation`, puis `moves` (avec les dés) ou `cube` (sans). Le classement des coups suit la
 méthode de `hint` décrite plus haut (`engine_best_moves` dans
 `engine/engine.c`). Pour voir tous les nombres comparés :
 `BUILD_C_IMAGE=ustagammon/build-c:2 bash tests/test_engine_reference.sh --details`.