# Plan v0.3.0 — baseline Snake et premier POC Web direct ## But de la version `0.3.0` ouvre la série de POC `0.3.x`. La version doit rendre Snake suffisamment portable pour servir de jeu-sonde et valider un premier host de bout en bout : le navigateur Web direct. La version doit rester assez petite pour être fermée dans la session qui l'ouvre. Si une tranche devient trop lourde, elle est scindée ; si le scope global ne tient plus, la partie non indispensable est reportée à une version suivante. ## Base et décisions acquises Base stable : `0.2.0`. Décisions issues du cadrage `0-pre.1` : - Snake reste le jeu-sonde principal ; - le premier host de `0.3.0` est Web navigateur direct ; - Tauri Android est reporté à `0.3.1` ; - le gameplay reste dans `game-snake-poc` ; - le chemin Web utilise Cargo, `wasm-bindgen` et Vite/TypeScript, sans orchestrateur Python ; - le host navigateur possède un shell HTML piloté par Vite/TypeScript, avec Bootstrap 5 pour le layout/les contrôles et un Canvas dédié au rendu du jeu ; Bootstrap ne porte aucune règle de gameplay ; - aucune abstraction n'est extraite avant qu'un besoin partagé réel soit observé. ## Scope La version couvre : - nettoyage de la baseline Snake et de ses dépendances de plateforme ; - adaptation WASM dédiée à Snake ; - frontend Web avec shell HTML responsive, Bootstrap 5, Canvas, clavier et contrôles directionnels tactiles ; - resize/lifecycle adaptés au navigateur ; - branchement des assets, du logging et de la provenance runtime nécessaires au POC ; - maintien du runner Desktop SDL3 comme témoin de non-régression ; - documentation des duplications observées et des extractions réellement justifiées. Hors périmètre : Tauri Android/Desktop Snake, Android natif multi-ABI, réseau realtime, WebTransport/QUIC, Uroburas, ads, billing, auth, leaderboard et nouveau moteur. ## Prévision souple Les numéros ci-dessous sont des repères de progression, pas un contrat rigide. Une découverte peut insérer un fix, scinder une tranche ou décaler les numéros suivants sans forcer la fermeture. ### `0-pre.1` — cadrage Audit de la baseline, requirements, choix du host Web, sizing et validations prévues. Le présent plan manquant à la livraison initiale est ajouté par `0-pre.1.fix.1`. ### `0-pre.1.fix.1` — plan et règles de suivi Créer `docs/plans/`, formaliser le caractère vivant du plan, corriger le contrat des archives taggées et rendre explicite qu'une session est planifiée pour fermer au minimum la version concrète ouverte. ### `0-pre.2` — baseline Snake portable Nettoyer les dépendances inutiles/spécifiques au launcher, stabiliser la frontière gameplay/input et confirmer les tests Snake ainsi que le runner Desktop SDL3. Livraison candidate : `engine-v1-platform-api` est retiré des crates de gameplay Snake et Reflex où il n'est pas consommé ; les launchers qui utilisent réellement les capacités plateforme conservent leur dépendance. Le contrat Snake est fixé sur `EngineGame`, `InputState`, les quatre actions directionnelles et `EngineScene`, sans SDL3, DOM, Canvas ni API plateforme dans la crate de gameplay. Aucun adapter WASM n'est introduit avant `0-pre.3`. Gate : audits statiques, `cargo check --workspace`, tests ciblés Snake et vérification du graphe de dépendances des crates de gameplay. Un smoke Desktop n'est requis que si le runtime SDL ou son mapping est modifié. ### `0-pre.3` — adaptation Snake WASM Introduire `game-snake-poc-wasm`, adapter WASM minimal dédié à Snake. La crate possède `SnakeState`, le `FixedStepRunner` et une direction logique en attente consommée au prochain `tick()`. Elle expose à `wasm-bindgen` les quatre directions, le score, la longueur et la scène normalisée nécessaire au futur Canvas, sans SDL3, Tauri, DOM, frontend ni `engine-v1-platform-api`. Livraison candidate : la crate est membre du workspace et la distribution statique vérifie sa présence. Le bridge reste volontairement spécifique à Snake ; aucune abstraction commune avec `game-reflex-poc-wasm` n'est extraite avant observation d'une duplication réellement problématique. Gate : audits statiques, `cargo check --workspace`, Clippy ciblé, tests de l'adapter, build `wasm32-unknown-unknown`, génération `wasm-bindgen --target web` dans `../builds/sasedev-games/` et graphe de dépendances. Aucun build Vite/Bootstrap ni smoke navigateur n'est requis avant `0-pre.4`. ### `0-pre.4` — frontend Web/Vite, shell Bootstrap 5 et contrôles Créer `Web/game-snake-poc/`, package Vite/TypeScript autonome consommant les bindings `game-snake-poc-wasm` générés hors dépôt. Le frontend reprend le template des applications Desk KSP pour sa structure HTML/Sass/TypeScript et ses dépendances npm pertinentes : Bootstrap 5, thème Bootswatch Pulse, Font Awesome, SimpleBar, `resize-observer-polyfill` et `sass-embedded`, sans dépendances Tauri. Le rendu reste dans un Canvas et les règles de gameplay restent dans Rust/WASM. Brancher flèches clavier, `WASD`/`ZQSD`, quatre boutons directionnels tactiles/pointer, chargement/erreur, score et longueur. Livraison candidate : le shell utilise `frontend/main.html`, `frontend/sass/` et `frontend/ts/` sur le modèle KSP ; SimpleBar porte le scroll de la zone centrale `app-content.app-scrollable.h-100[data-simplebar]`, bornée par `app-main` entre header et footer fixes ; le Canvas conserve le ratio logique Snake `12 / 20`, suit sa taille CSS et le `devicePixelRatio`, le frontend cadence `tick()` sans avancer la simulation au moment d'une entrée et Vite écrit `dist/`/cache uniquement sous `../builds/sasedev-games/game-snake-poc-web/`. Aucun CDN, SDL3, Tauri ni duplication de gameplay n'est introduit. Le lifecycle complet, les assets, le logging et la provenance restent réservés à `0-pre.5`. Gate : audits statiques, build WASM + `wasm-bindgen`, `npm run build` du package Web direct et smoke navigateur couvrant Canvas, clavier, contrôles tactiles/pointer et comportement responsive du shell. Suivi `0-pre.4.fix.1` : la validation utilisateur de `0-pre.4` a confirmé le fonctionnement clavier/pointer sous `vite dev`, mais a révélé trois défauts de candidate : `baseUrl` supprimé par TypeScript 7, omission de SimpleBar/`resize-observer-polyfill` du template repris et Canvas carré incompatible avec la grille logique `12 × 20`. Le fix retire `baseUrl`, rétablit le scroll shell KSP-derived et passe le plateau au ratio `3 / 5` avant réexécution de la gate frontend. Suivi `0-pre.4.fix.2` : la validation de `fix.1` a confirmé les gates Rust/WASM et les audits, mais `npm run build` a encore révélé deux erreurs TypeScript strictes : l'alias `@snake-wasm` résolvait le JavaScript généré sans sélectionner sa déclaration `.d.ts`, et le narrowing du contexte Canvas 2D n'était pas conservé dans le callback `requestAnimationFrame`. Le fix sépare explicitement la résolution de typage (`.d.ts`) de la résolution runtime Vite (`.js`) et capture le contexte 2D validé dans une constante non nullable. Suivi `0-pre.4.fix.3` : la validation de `fix.2` confirme la gate Rust/WASM, le build Vite production et le ratio Canvas corrigé. Le smoke révèle toutefois que le scroll SimpleBar ne reproduit pas encore le comportement du shell KSP. La comparaison avec `ksp-app-*-desk` montre que `data-simplebar` doit porter sur la zone centrale `app-content app-scrollable h-100`, enfant d'un `app-main` borné, et non sur `app-main` lui-même. Le fix aligne la structure HTML/Sass sur ce contrat sans initialisation manuelle spécifique. Validation `0-pre.4.fix.3` : le build Vite reste propre et le smoke utilisateur confirme le comportement attendu du shell, y compris le scroll SimpleBar, le Canvas portrait et les contrôles. `0-pre.4` est donc fermé et `0-pre.5` peut porter l'intégration plateforme complète. ### `0-pre.5` — intégration plateforme complète Fermer resize/lifecycle, assets, logging et provenance runtime du POC ; vérifier que Desktop SDL reste intact. Livraison candidate : le host suspend la simulation sur `visibilitychange`/`pagehide` et reprend sans rattrapage massif ; un `ResizeObserver` redessine sans tick artificiel. Vite package `assets/common/data/runtime.json` vers `common/data/runtime.json` et `assets/game-snake-poc/data/game.json` vers `game/data/game.json`, puis le frontend charge/valide ces deux sondes avant le démarrage. Les diagnostics navigateur passent par un module TypeScript structuré local. `game-snake-poc-wasm` consomme `engine-v1-platform-api` pour une provenance `Web/Wasm/Browser`, complétée par la classe d'appareil et le profil d'entrée réellement observés. Aucun de ces contrats ne fuit dans `game-snake-poc`. Gate : audits statiques, `cargo check --workspace`, Clippy workspace strict, tests `engine-v1-platform-api` et `game-snake-poc-wasm`, build WASM + `wasm-bindgen`, build Vite, smoke navigateur couvrant assets/provenance/lifecycle/resize/inputs/SimpleBar, puis smoke `game-snake-poc-desktop` pour la non-régression SDL3. Suivi `0-pre.5.fix.1` : la validation de `0-pre.5` confirme les gates Rust/WASM et le build Vite production, mais le smoke `vite dev` reste bloqué sur le chargement des assets. Les targets `vite-plugin-static-copy` utilisent des sources absolues sans `rename.stripBase`, ce qui ne garantit pas les routes runtime canoniques. Le fix impose `stripBase: true` aux deux targets afin que dev et build exposent exactement `/common/data/runtime.json` et `/game/data/game.json`. Validation `0-pre.5.fix.1` : les audits, `cargo check`, Clippy workspace strict, les tests plateforme/WASM, le build WASM, `wasm-bindgen`, le build Vite et le smoke navigateur passent. Les assets affichent `snake / engine-v1`, la provenance observée est `web / browser / wasm / desktop / keyboard-mouse`, les contrôles clavier/souris fonctionnent et le runner Desktop SDL3 démarre puis s'arrête proprement après 411 frames. Aucun défaut structurel supplémentaire n'est identifié. ### `0-pre.6` — correction/extraction seulement si prouvée Tranche conditionnelle. Elle n'existe que si les POC précédents révèlent une duplication réelle, une frontière mal placée ou un défaut nécessitant une correction structurante avant stabilisation. Sinon elle est omise. Décision après `0-pre.5.fix.1` : aucun besoin d'extraction/correction structurante n'est observé ; `0-pre.6` est omise et la version entre directement en beta. ### `2-beta.1` — validation large Scope feature-complete. La tranche ne crée aucun nouveau comportement : elle bascule la version workspace et le package Web au jalon `0.3.0-2-beta.1`, enregistre la validation de `0-pre.5.fix.1` et exécute la gate large de frontière de phase. Celle-ci comprend audits, formatage/check/Clippy, tests workspace complets, build + smoke Desktop Snake en release, build WASM Snake en release, `wasm-bindgen`, build Vite production et smoke du `dist` via `npm run preview`. Aucun nouveau scope. Validation : la gate est acceptée par l'utilisateur. Les audits sont propres, les tests workspace totalisent 34 tests réussis sans échec, le binaire Desktop Snake release démarre et s'arrête proprement après 144 frames, et le bundle Web/WASM release est construit puis servi par `vite preview` sans défaut remonté. ### `2-beta.2` — consolidation documentaire et transmission Réconcilier l'état réellement validé avec la documentation durable et le plan actif, mettre à jour `ROADMAP.md`, enregistrer `2-beta.1` dans l'historique et préparer le prompt de `0.3.1` à partir de cet état. La synthèse destinée au `CHANGELOG.md` est consolidée ici, mais l'entrée n'est écrite qu'en RC conformément à `DOC-CHG-002` et `DOC-CHG-003`. Livraison candidate : synthèse durable de la baseline Web Snake `0.3.0`, matrice RC spécifique, roadmap `0.3.0` classée réalisée, audit `pre.1` réconcilié avec le contrat des archives taggées et prompt `003-V0_3_1_START_PROMPT.md`. Aucun code ni comportement runtime n'est modifié. Cette tranche est une responsabilité obligatoire du cycle même si son numéro doit être décalé par des fixes ou une beta supplémentaire. La documentation spécifique à une fonctionnalité reste mise à jour dans la tranche qui introduit cette fonctionnalité ; `2-beta.2` réalise la consolidation transversale, elle ne sert pas à reporter toute la documentation en fin de version. Gate : cohérence docs/plan/deltas/`CHANGELOG.md`/`ROADMAP.md`/history/prompt, audits documentaires, `cargo check --workspace` pour le bump de version et `npm run build` pour confirmer la version frontend. Suivi `2-beta.2.fix.1` : la gate mécanique de `2-beta.2` passe, mais la revue humaine juge le prompt `0.3.1` trop synthétique pour éviter des rappels de workflow au cours de la prochaine session. Le fix enrichit ce prompt, formalise une structure durable de prompts, précise le timing prompt/RC/CHANGELOG/ROADMAP/history et introduit une politique non cérémonielle pour `README.md`/`USAGE.md`. Le fix est strictement documentaire et conserve donc la version technique `0.3.0-2-beta.2`. Suivi `2-beta.2.fix.2` : la revue du prompt enrichi valide son niveau de contexte, mais précise la gouvernance des commandes afin d'éviter des validations trop larges ou répétitives. Le fix rend obligatoires `cargo fmt`, `cargo check --workspace` et Clippy workspace strict dès que Rust ou ses dépendances changent, garde les tests ciblés comme norme, réserve le test workspace complet à quelques jalons planifiés, limite `cargo tree` aux changements/diagnostics de dépendances, sélectionne les audits Python selon les fichiers touchés, impose les sous-shells pour les changements de répertoire et rappelle que Tauri possède Vite via `cargo tauri dev/build`. Ce correctif reste strictement documentaire et ne modifie aucune version technique. Validation `2-beta.2.fix.2` : l'audit Markdown ciblé passe (`5` tables, `189` fichiers) et la revue utilisateur autorise l'ouverture de la RC. Aucune autre gate n'est attribuée à ce correctif strictement documentaire. ### `3-rc.1` — candidate gelée Reproductibilité, validation finale de la candidate et derniers défauts strictement nécessaires à la publication. Le prompt suivant préparé pendant la consolidation est vérifié/complété si l'état RC apporte une information nouvelle. Aucun nouveau POC ni nouvelle capability. Livraison candidate : passage des versions techniques au jalon `0.3.0-3-rc.1`, entrée RC du `CHANGELOG.md`, enregistrement de `2-beta.2.fix.2` dans `history/`, revue finale du prompt `0.3.1` et gel explicite du scope. Le prompt est jugé suffisamment complet et ne reçoit aucun changement sémantique supplémentaire dans cette tranche. Gate RC : appliquer intégralement `docs/testing/004-V0_3_0_RC_VALIDATION_MATRIX.md`. Le test workspace complet est volontairement exécuté à ce jalon final ; aucun `cargo tree` n'est requis en l'absence de changement de dépendances. Validation `3-rc.1` : les audits statiques, `cargo check --workspace`, Clippy workspace strict et la suite workspace complète passent avec 34 tests réussis. Le binaire Desktop Snake release démarre puis s'arrête proprement après 926 frames. Le build WASM release, `wasm-bindgen`, le build Vite production et `vite preview` passent également. Aucun défaut nécessitant un correctif RC n'est remonté. ### `0.3.0` — release stable Promotion mécanique de l'état RC validé. La release ne change ni gameplay, ni architecture, ni dépendance ; elle fixe les versions stables, ajoute l'entrée stable du `CHANGELOG.md`, enregistre la validation RC sous `history/0.3.0/3-rc.1.md` et clôt le plan `0.3.0`. Le prompt `0.3.1` reste inchangé après sa revue RC. ## Suivi et ajustements Le plan est révisé lorsqu'un résultat réel modifie la trajectoire. Un changement de numérotation n'est pas un problème ; une responsabilité importante ne doit en revanche pas être comprimée artificiellement pour respecter le forecast initial. La session ne doit pas être planifiée pour s'arrêter à `pre.2`, `pre.4` ou beta : ces identifiants sont des tranches de la même version. Si `0.3.0` devient trop grande, le scope non indispensable est déplacé vers `0.3.1+` afin de préserver une version complète par session. ## Version suivante envisagée `0.3.1` reste le candidat pour le second host Snake, Tauri Android, en réutilisant la baseline Web/WASM réellement validée par `0.3.0`.