games/docs/plans/002-V0_3_1_TAURI_ANDROID_SNAKE_PLAN.md

Plan v0.3.1 — second host Snake Tauri Android

But de la version

0.3.1 doit terminer un second host Snake réellement exécutable sous Tauri Android en réutilisant la baseline Web/WASM validée par 0.3.0, puis conserver ce host comme POC de référence plutôt que comme voie de production des jeux Android.

La version ne doit ni déplacer le gameplay hors de game-snake-poc, ni créer un second adapter Snake, ni transformer immédiatement les similitudes Web/Tauri en framework générique.

Base stable : 0.3.0.

Cadrage : ../studies/024-V0_3_1_TAURI_ANDROID_SNAKE_AUDIT.md.

Décisions acquises

• la nouvelle crate sera crates/apps/game-snake-poc-tauri ;
• 0.3.1 valide uniquement sa cible Android et en fait un POC de référence, pas une distribution jeu Android de production ;
• game-snake-poc reste inchangé sauf défaut réellement découvert ;
• game-snake-poc-wasm reste l'unique adapter Snake WASM et recevra seulement la généralisation de provenance nécessaire au second host ;
• le frontend Tauri part du comportement réellement validé dans Web/game-snake-poc, avec adaptation de lifecycle et logging ;
• lib.rs est une façade/reexport et tauri.rs reste l'assemblage Tauri ;
• le tracing frontend utilise @fltsci/tauri-plugin-tracing ;
• les hooks Tauri possèdent le build frontend/WASM ;
• aucun nouveau chemin de build n'est piloté par Python ;
• README.md et USAGE.md seront créés avec l'app : architecture pour le premier, prérequis/commandes/smokes pour le second ;
• cargo tauri android init/dev/build sont les commandes mobiles de référence ;
• SimpleBar et resize-observer-polyfill ne sont pas ajoutés au host Tauri sans besoin démontré ;
• la voie Android de production reste le host natif SDL3/Java/JNI tant qu’un besoin fonctionnel démontré ne justifie pas Tauri ;
• Tauri Android peut rester utile comme référence comparative, notamment pour évaluer plus tard les saisies texte/WebView, mais ce besoin n’est pas considéré comme acquis ;
• une future variante Tauri Desktop reste conditionnée à un avantage explicite, notamment une monétisation WebView/publicitaire techniquement et contractuellement viable.

Scope

La version couvre :

• création de la crate/app Tauri Snake ;
• initialisation de la cible Android par Tauri ;
• pipeline Rust/WASM + Vite/TypeScript possédé par Tauri sans Python ;
• consommation de game-snake-poc-wasm ;
• shell Canvas, contrôles touch et comportement responsive nécessaires au jeu ;
• assets communs et spécifiques Snake ;
• lifecycle mobile/WebView ;
• provenance Android / Wasm / TauriWebView ;
• tracing Rust/Tauri/frontend ;
• politique de sortie/Back conforme au moteur ;
• build/package et smoke sur AVD/appareil disponible aux jalons prévus ;
• comparaison du code Web direct/Tauri après fonctionnement réel afin de décider s'il existe une extraction commune justifiée.

Hors scope : Tauri Desktop Snake comme cible validée, iOS, Android SDL3 multi-ABI additionnel, réseau realtime, Uroburas, intégration ads effective, billing, auth et leaderboard.

Positionnement produit après validation du host minimal

Le smoke 0-pre.2.fix.3 a confirmé que Tauri Android fonctionne techniquement, mais aussi que son outillage ajoute une couche de complexité propre au host : combinaison JDK/Gradle imposée par la version Tauri, projet Android généré et chaîne WebView/WASM supplémentaire alors que le POC Android natif SDL3 fonctionne déjà.

Décision de 0-pre.3 :

• terminer 0.3.1 afin d’obtenir un POC Tauri Android jouable et documenté ;
• conserver game-snake-poc-tauri comme POC de référence et banc de comparaison ;
• ne pas utiliser Tauri Android comme template de nouvelles applications de jeu ;
• privilégier SDL3 natif pour Android ;
• ne rouvrir la question Tauri Android que pour un besoin concret que SDL3 ne couvre pas proprement, par exemple une saisie texte complexe après test réel des possibilités SDL ;
• évaluer séparément Tauri Desktop seulement si la WebView apporte un avantage produit mesurable, notamment une voie publicitaire exploitable.

Cette décision ne réduit pas le critère de qualité de 0.3.1 : le POC de référence doit rester jouable, reproductible et suffisamment complet pour permettre une comparaison technique utile.

Prévision souple

0-pre.1 — cadrage et règles

Audit complet de l'archive stable, règles, baseline Web/WASM, Tauri Reflex, références Desk KSP accessibles, environnement Android historique et commandes Tauri mobiles actuelles.

Livraison : étude 024, présent plan, correction des règles Tauri Android, clarification PlatformFamily, index documentaires et ouverture de la version technique 0.3.1-0-pre.1.

Aucun scaffold Tauri Snake n'est créé. Tranche validée par la gate utilisateur du 2026-09-20.

0-pre.2 — host Tauri Android minimal

Créer game-snake-poc-tauri avec :

• manifest Cargo/build script/config Tauri/capabilities ;
• lib.rs façade, tauri.rs assemblage et modules propriétaires minimaux ;
• point d'entrée run() mobile annoté #[cfg_attr(mobile, tauri::mobile_entry_point)] dans le module propriétaire puis réexporté par lib.rs ;
• frontend Vite/TypeScript minimal ;
• bridge tracing initialisé ;
• hooks de build natifs, sans Python ;
• cible Android initialisée via Tauri ;
• chargement du même adapter game-snake-poc-wasm après généralisation minimale de provenance ;
• README.md et USAGE.md initiaux.

La tranche vise un premier démarrage Tauri Android minimal, pas encore toute la finition input/lifecycle.

État candidat livré : crate game-snake-poc-tauri, bridge Rust/Tauri, hooks WASM/Vite sans Python, frontend minimal, tracing frontend/Rust et provenance partagée Android / TauriWebView / Wasm. L'initialisation générée cargo tauri android init reste volontairement locale et fait partie de la gate utilisateur, car gen/ n'est pas un artefact source distribué.

Gate utilisateur : audits, Cargo workspace strict, test ciblé de l'adapter WASM, non-régression du build Web direct, cargo tauri android init puis cargo tauri android dev sur un AVD ou appareil disponible. cargo tauri android build reste reporté aux phases finales sauf besoin diagnostique.

Le premier smoke 0-pre.2 a révélé deux défauts bornés : build.rs échouait sous Clippy strict à cause de la rustdoc manquante, et Java 25 ne pouvait pas exécuter le wrapper Gradle 8.14.3 généré par Tauri CLI 2.11.3. 0-pre.2.fix.1 a tenté de migrer localement le scaffold généré vers Gradle 9 ; cette approche est abandonnée à partir de 0-pre.2.fix.2 car la branche stable Tauri 2.11.x n'a pas encore publié cette migration et le projet ne doit pas maintenir un fork implicite des templates Android Tauri. 0-pre.2.fix.3 fixe JDK 17 comme baseline Android reproductible pour la chaîne officielle Gradle 8.14.3 + AGP 8.11.0 et impose la régénération de tout gen/android touché par la tentative fix.1. Le Gradle global de la machine ne fait pas partie du contrat reproductible.

0-pre.3 — shell Snake, Canvas, input et assets

Réutiliser sélectivement le host Web validé :

• rendu Canvas et session fixed-step ;
• shell responsive pertinent ;
• contrôles directionnels touch/pointer et clavier lorsque disponible ;
• resize/orientation ;
• assets canoniques communs + Snake ;
• absence de dépendances Web-only inutiles.

Aucune extraction commune n'est réalisée uniquement pour éviter quelques fichiers similaires pendant la mise au point.

0-pre.4 — lifecycle, provenance, tracing et sortie mobile

Stabiliser :

• background/foreground et reprise sans rattrapage massif ;
• rotation/resize ;
• provenance Android / Wasm / TauriWebView + device/input observés ;
• tracing Rust/Tauri/frontend ;
• sorties applicatives conformes à EngineGame::quit_requested sans détourner le Back système Android ;
• smokes AVD et, si disponible, appareil réel.

Cette tranche doit rendre le second host fonctionnel de bout en bout et suffisamment stable pour être conservé comme POC de référence.

État candidat 0-pre.4 : la boucle Tauri dispose maintenant de pause/resume, remet à zéro son accumulateur à la reprise, suit visibilitychange, pagehide/pageshow et ResizeObserver, et journalise les transitions via le tracing frontend. Le Back Android n’est pas intercepté : Snake conserve la politique moteur par défaut Exit, identique au comportement système Tauri du host mono-page. Le D-pad sous le Canvas est conservé comme limite ergonomique documentée plutôt que d’élargir cette version à un système swipe/overlay.

La gate AVD 0-pre.4 est propre. Le smoke supplémentaire sur Galaxy S9+ ARM64 a confirmé compilation aarch64-linux-android, installation, Canvas, assets, WASM, touch et lifecycle visible/hidden via un tunnel ADB USB. Deux écarts ont été observés : le HMR utilisait encore un port WebSocket séparé, défaut local corrigé par 0-pre.4.fix.1, et le Back système a déclenché un abort natif FORTIFY: pthread_mutex_lock called on a destroyed mutex pendant le teardown de l'Activity/WebView. Les logs placent cet abort après visibility hidden et avant pagehide, sans runtime disposed.

0-pre.4.fix.1 ne tente pas de migrer manuellement Tauri/Wry ni de patcher gen/android. Le smoke résout tauri 2.11.5 avec wry 0.55.1; les versions Wry postérieures comportent des changements Android de lifecycle et de synchronisation, mais elles ne doivent pas être forcées derrière la pile stable Tauri actuelle sans intégration upstream. Le crash Back réel reste donc une limite externe du POC à retester avec l'APK autonome 2-beta.1.

0-pre.5 — extraction conditionnelle

Créer uniquement si l'état 0-pre.4 montre une duplication réellement durable entre Web/game-snake-poc et le frontend Tauri et si l'extraction garde une valeur au-delà du seul POC Android de référence.

Une extraction possible doit rester bornée à une responsabilité clairement partagée, par exemple projection/rendu Canvas, mapping input Web ou helpers d'assets. Lifecycle et logging restent host-specific s'ils divergent réellement.

Si aucune extraction n'est justifiée, cette tranche est omise.

2-beta.1 — validation large et packaging Android

Prévoir :

• audits statiques applicables ;
• cargo fmt --all -- --check ;
• cargo check --workspace ;
• Clippy workspace strict ;
• suite workspace complète à ce jalon planifié ;
• build WASM release et bindings ;
• cargo tauri android build ;
• APK de validation du POC de référence ;
• AAB uniquement si une valeur de validation supplémentaire est démontrée, pas par automatisme de distribution ;
• install/smoke AVD ;
• install/smoke appareil ARM64 réel si disponible ;
• vérification que les outputs restent hors racine du dépôt lorsqu'ils sont configurables par le projet.

2-beta.2 — consolidation documentaire conditionnelle

Réserver seulement si les validations beta demandent une consolidation substantielle de README.md, USAGE.md, architecture, matrice de validation ou plan. Ne pas créer cette tranche par cérémonial.

3-rc.1 — candidate gelée

Gel fonctionnel, reproductibilité, packaging Android RC et validation finale selon les règles RC applicables. Aucun nouveau framework ni nouveau host.

0.3.1 — release stable

Promotion mécanique de la RC validée : versions stables, changelog, history et clôture du plan. Aucun ajout fonctionnel.

Inventaire environnement requis avant 0-pre.2

La gate 0-pre.1 doit recevoir au minimum :

rustc --version
cargo --version
cargo tauri --version
rustup target list --installed
node --version
npm --version
wasm-bindgen --version
java -version
printf 'JAVA_HOME=%s\nANDROID_HOME=%s\n' "$JAVA_HOME" "$ANDROID_HOME"
adb version
adb devices -l
emulator -list-avds

L'absence d'un outil ne doit pas être masquée. Elle devient un prérequis concret de 0-pre.2 ou motive un fix borné de 0-pre.1.

La gate 0-pre.1 validée le 2026-09-20 a confirmé Rust 1.94.1, Tauri CLI 2.11.3, Node 24.21.0, npm 11.19.0, wasm-bindgen 0.2.128, OpenJDK 25.0.4.1, ANDROID_HOME=/home/sinus/DEV/AndroidSDK, un appareil ARM64 réel et trois AVD disponibles. JAVA_HOME était vide et Java 25 était résolu depuis le PATH. Les smokes 0-pre.2 ont confirmé que Tauri sélectionne lui-même le NDK side-by-side sous $ANDROID_HOME/ndk/<version>. Le JBR de l'Android Studio local est également Java 25 ; il n'est donc pas compatible avec Gradle 8.14.3. Pour 0.3.1, JAVA_HOME doit pointer vers JDK 17 pendant cargo tauri android init/dev/build.

Critères de fermeture de 0.3.1

La version peut entrer en RC lorsque :

• Snake est jouable dans le WebView Tauri Android sans gameplay dupliqué et le host est explicitement positionné comme POC de référence ;
• le même adapter WASM sert Web direct et Tauri Android avec provenance exacte ;
• lifecycle/input/assets/tracing/Back ont un comportement explicite et validé ;
• le chemin de build ne dépend d'aucun orchestrateur Python ;
• le packaging Tauri Android est reproductible ;
• les smokes prévus sur cible Android ont été exécutés ;
• aucune extraction commune non prouvée n'a été introduite ;
• la documentation opérateur et architecture reflète l'état réel.

Version suivante

0.3.2 devient une évaluation conditionnelle de Tauri Desktop + Snake. Elle n’est ouverte que si la WebView Desktop apporte un bénéfice explicite, notamment une piste de monétisation publicitaire viable ; la factorisation WebView reste interdite sans deux consommateurs réellement retenus.