From 850de27e90cce31d52044e24fdd810d72a925d80 Mon Sep 17 00:00:00 2001 From: Pierre MARTIN Date: Mon, 2 Nov 2026 19:00:28 +0100 Subject: [PATCH] =?UTF-8?q?Plan=20de=20l'=C3=A9tape=200b=20:=20moteur=20en?= =?UTF-8?q?=20WebAssembly?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 --- docs/feuille-de-route.md | 2 +- docs/plans/2026-11-02-moteur-webassembly.md | 92 +++++++++++++++++++++ 2 files changed, 93 insertions(+), 1 deletion(-) create mode 100644 docs/plans/2026-11-02-moteur-webassembly.md diff --git a/docs/feuille-de-route.md b/docs/feuille-de-route.md index c63633b..1f359d6 100644 --- a/docs/feuille-de-route.md +++ b/docs/feuille-de-route.md @@ -16,7 +16,7 @@ automatique aux références, tolérance 0,002 (0a.4). | Sous-étape | Contenu | État | Plan | | --- | --- | --- | --- | -| 0b | Moteur en WebAssembly, page de test dans un Web Worker, `make deploy-web`, `make bench` | ⏳ | | +| 0b | Moteur en WebAssembly, page de test dans un Web Worker, `make deploy-web`, `make bench` | 🔄 | `plans/2026-11-02-moteur-webassembly.md` | | Mesures | Pierre relève les mesures sur le Fairphone 4 | ⏳ | | | Décision | Socle PWA ou Android natif, consigné dans un ADR — validation de Pierre | ⏳ | | | 0c | Android natif (NDK, Gradle en ligne de commande, `make deploy` via adb) | ⏸ si 0b échoue | | diff --git a/docs/plans/2026-11-02-moteur-webassembly.md b/docs/plans/2026-11-02-moteur-webassembly.md new file mode 100644 index 0000000..b4f7f3b --- /dev/null +++ b/docs/plans/2026-11-02-moteur-webassembly.md @@ -0,0 +1,92 @@ +# 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 ` ; +- 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.