0.3.0-0-pre.4

2026-09-20 13:14:40 +02:00
parent c7ccf57723
commit c4b68b8a60
27 changed files with 1195 additions and 48 deletions
--- a/docs/development/010-SNAKE_WEB_FRONTEND.md
+++ b/docs/development/010-SNAKE_WEB_FRONTEND.md
@@ -0,0 +1,130 @@
+<!-- file: docs/development/010-SNAKE_WEB_FRONTEND.md -->
+<!-- version: 1 -->
+
+# Frontend du POC Snake Web direct
+
+## Rôle
+
+`Web/game-snake-poc/` est le premier host navigateur direct du projet. Il reste un package frontend autonome, extérieur au workspace Cargo, et consomme les bindings générés de `game-snake-poc-wasm`.
+
+La séparation est volontaire :
+
+```text
+game-snake-poc
+        ↓
+game-snake-poc-wasm
+        ↓ wasm-bindgen
+Web/game-snake-poc
+        ↓
+HTML + Sass/Bootstrap 5 + TypeScript + Canvas
+```
+
+Le frontend ne réimplémente aucune règle de Snake. Il traduit uniquement les entrées navigateur, cadence les appels à `tick()` et dessine la scène portable exposée par le bridge WASM.
+
+## Baseline frontend KSP
+
+Le shell reprend volontairement la structure frontend utilisée par les applications Desk KSP :
+
+```text
+Web/game-snake-poc/
+├── frontend/
+│   ├── main.html
+│   ├── sass/
+│   │   ├── _app.scss
+│   │   ├── _bootswatch.scss
+│   │   ├── _fontawesome.scss
+│   │   ├── _variables.scss
+│   │   └── main.scss
+│   └── ts/
+│       ├── game.ts
+│       ├── input.ts
+│       └── main.ts
+├── package.json
+├── tsconfig.json
+└── vite.config.ts
+```
+
+Les dépendances npm utiles sont alignées sur cette baseline : Bootstrap 5, Font Awesome, `sass-embedded`, TypeScript, Vite et les types nécessaires. Les dépendances propres à Tauri, SimpleBar ou au tracing frontend KSP ne sont pas importées car elles n'ont aucun rôle dans ce host navigateur direct.
+
+Le thème reprend la baseline Bootstrap/Bootswatch Pulse des apps Desk KSP, avec un header, un footer et une carte de contenu adaptés au jeu. Cette réutilisation reste une convention de présentation du POC ; elle ne crée aucune dépendance entre les dépôts KSP et games.sasedev.
+
+## Shell HTML et présentation
+
+Le document `frontend/main.html` fournit :
+
+- un header de statut inspiré du template Desk KSP ;
+- un Canvas carré responsive pour le rendu du jeu ;
+- les indicateurs de score, longueur et état de chargement ;
+- quatre boutons directionnels tactiles ;
+- une zone d'erreur de démarrage ;
+- un footer léger commun au shell.
+
+Bootstrap 5 et Font Awesome sont installés comme dépendances npm et intégrés au build Vite/Sass. Aucun CDN n'est nécessaire au POC local.
+
+Le Sass spécifique reste limité au shell, au Canvas et au pavé directionnel. Le gameplay ne dépend ni de Bootstrap, ni de Font Awesome, ni du DOM.
+
+## Entrées
+
+Le frontend accepte :
+
+- les flèches du clavier ;
+- `WASD` ;
+- `ZQSD` ;
+- les quatre boutons directionnels tactiles/pointer.
+
+Une entrée appelle uniquement `left()`, `right()`, `up()` ou `down()` sur `SnakeWasmGame`. La simulation continue d'avancer exclusivement via `tick()`.
+
+## Rendu Canvas
+
+Le frontend lit la couleur de fond et les rectangles normalisés exposés par `game-snake-poc-wasm`. Les coordonnées sont multipliées par la taille physique courante du Canvas.
+
+Le Canvas suit sa taille CSS et le `devicePixelRatio` du navigateur. Cette tranche couvre le resize visuel nécessaire au shell ; la gestion complète du lifecycle navigateur reste prévue par `0-pre.5`.
+
+## Build
+
+Depuis la racine du dépôt, construire d'abord l'adapter WASM et ses bindings :
+
+```bash
+cargo build -p game-snake-poc-wasm --target wasm32-unknown-unknown
+wasm-bindgen ../builds/sasedev-games/target/wasm32-unknown-unknown/debug/game_snake_poc_wasm.wasm \
+  --target web \
+  --out-dir ../builds/sasedev-games/game-snake-poc-web/wasm \
+  --out-name game_snake_poc_wasm
+```
+
+Puis installer et construire le frontend :
+
+```bash
+cd Web/game-snake-poc
+npm install
+npm run build
+```
+
+Vite place son cache et le `dist/` sous :
+
+```text
+../builds/sasedev-games/game-snake-poc-web/
+```
+
+Le dépôt ne reçoit donc ni bindings WASM générés, ni `dist/`, ni cache Vite.
+
+## Smoke navigateur
+
+Après génération du WASM :
+
+```bash
+cd Web/game-snake-poc
+npm run dev
+```
+
+Ouvrir `http://127.0.0.1:1434/main.html` et vérifier :
+
+1. le statut passe à `Prêt` sans erreur ;
+2. Snake est visible dans le Canvas ;
+3. les flèches clavier déplacent Snake ;
+4. `WASD` et `ZQSD` produisent les mêmes directions ;
+5. les quatre boutons tactiles/pointer fonctionnent ;
+6. le shell KSP-derived et le Canvas restent utilisables sur une largeur mobile et Desktop ;
+7. score et longueur restent visibles et évoluent avec l'état WASM.
+
+Le lifecycle complet, les assets, le logging structuré et la provenance runtime appartiennent à `0-pre.5`.