0.1.0-0-pre.1

docs/000-README.md

@@ -0,0 +1,17 @@
+<!-- file: docs/000-README.md -->
+<!-- version: 1 -->
+
+# Documentation games.sasedev
+
+## Architecture
+
+- [`architecture/001-WORKSPACE_ARCHITECTURE.md`](architecture/001-WORKSPACE_ARCHITECTURE.md) — workspace, générations de moteur, jeux, assets et Android.
+- [`architecture/002-ANDROID_ARCHITECTURE.md`](architecture/002-ANDROID_ARCHITECTURE.md) — séparation Rust/SDL3/Java/JNI et modules Android.
+
+## Règles
+
+Voir [`../RULES.md`](../RULES.md).
+
+## Validation
+
+- [`validation/001-VALIDATION_GATES.md`](validation/001-VALIDATION_GATES.md) — gates manuelles de la baseline.

docs/architecture/001-WORKSPACE_ARCHITECTURE.md

@@ -0,0 +1,56 @@
+<!-- file: docs/architecture/001-WORKSPACE_ARCHITECTURE.md -->
+<!-- version: 1 -->
+
+# Architecture du workspace
+
+## Vue générale
+
+```text
+games.sasedev/
+├── crates/
+│   ├── engines/
+│   │   ├── engine-v1-common/
+│   │   ├── engine-v1-platform-api/
+│   │   └── engine-v1-sdl/
+│   └── games/
+│       ├── game-reflex-poc/
+│       └── game-snake-poc/
+├── assets/
+│   ├── common/
+│   ├── game-reflex-poc/
+│   └── game-snake-poc/
+├── Android/
+│   ├── common/
+│   ├── game-reflex-poc/
+│   └── game-snake-poc/
+├── docs/
+├── deltas/
+├── prompts/
+└── scripts/
+```
+
+## Générations du moteur
+
+Une génération `engine-vN` est une ligne de compatibilité. Un jeu peut rester sur `engine-v1` pendant qu'un nouveau jeu expérimente `engine-v2`. Les anciens jeux sont ensuite migrés individuellement.
+
+Les subdivisions sont exprimées par crates afin de ne pas forcer un jeu à dépendre de capacités inutiles. La baseline sépare déjà :
+
+- `engine-v1-common` : types et comportements génériques indépendants des plateformes ;
+- `engine-v1-platform-api` : contrats abstraits des services plateforme ;
+- `engine-v1-sdl` : frontière d'intégration SDL3, volontairement minimale dans la baseline.
+
+## Jeux
+
+Chaque jeu est une crate indépendante sous `crates/games/`. Un jeu ne duplique pas une crate moteur. Il sélectionne explicitement la génération qu'il consomme.
+
+## Assets
+
+Les assets sont extérieurs aux crates. Le packaging compose :
+
+```text
+assets/common/
++
+assets/<game>/
+```
+
+Le runtime devra conserver une distinction logique entre ressources communes et ressources spécifiques afin d'éviter les collisions silencieuses.

docs/architecture/002-ANDROID_ARCHITECTURE.md

@@ -0,0 +1,42 @@
+<!-- file: docs/architecture/002-ANDROID_ARCHITECTURE.md -->
+<!-- version: 1 -->
+
+# Architecture Android
+
+## Principe
+
+Android est un frontend de plateforme autour du jeu natif Rust/SDL3. Java est retenu comme langage de glue par défaut.
+
+```text
+Android application
+├── Java common layer
+│   ├── SaseGameActivity
+│   ├── NativeBridge
+│   └── futurs Ads/Billing/Haptics managers
+├── Java game-specific layer
+├── SDL3 Android AAR
+├── native Rust game library
+├── common assets
+└── game-specific assets
+```
+
+SDL3 documente un shim Java/JNI et recommande de dériver sa propre activité de `SDLActivity`. L'utilisation de l'AAR SDL3 doit être privilégiée lorsque l'intégration concrète démarre afin d'éviter de recopier les sources SDL dans chaque jeu.
+
+## Modules Gradle
+
+`Android/common` est destiné à devenir une Android Library réutilisable. Les modules `Android/game-*` deviennent des applications distinctes produisant chacune leur APK/AAB.
+
+Le squelette initial ne fige volontairement pas la version d'Android Gradle Plugin ni celle de SDL3 : ces dépendances seront introduites dans le premier delta Android réellement exécutable, avec versions vérifiées au moment de l'intégration.
+
+## JNI
+
+Le contrat JNI doit rester petit. Les services envisagés sont notamment :
+
+- affichage d'une publicité récompensée ;
+- affichage d'un interstitiel ;
+- achats intégrés ;
+- partage Android ;
+- haptique ;
+- événements lifecycle utiles au moteur.
+
+Une rupture interne de `engine-v1` vers `engine-v2` ne doit pas imposer une nouvelle couche Java si ce contrat reste compatible.

docs/rules/FILE_CONTRACTS.md

@@ -0,0 +1,17 @@
+<!-- file: docs/rules/FILE_CONTRACTS.md -->
+<!-- version: 1 -->
+
+# Contrats des fichiers principaux
+
+- `README.md` présente le dépôt et ses entrées principales.
+- `RULES.md` indexe les règles normatives.
+- `ROADMAP.md` suit les objectifs futurs et leur état.
+- `CHANGELOG.md` conserve l'historique synthétique inversement chronologique.
+- `docs/000-README.md` indexe la documentation détaillée.
+- `docs/rules/` contient les règles durables.
+- `docs/architecture/` contient les décisions et descriptions d'architecture.
+- `deltas/` contient un document par livraison ou correctif versionné.
+- `prompts/` peut contenir les prompts de reprise de session lorsqu'ils deviennent utiles.
+- `scripts/` contient des audits en lecture seule et des outils du dépôt.
+- `assets/` contient les ressources runtime communes et spécifiques aux jeux ; aucune ressource runtime n'est placée dans une crate Rust.
+- `Android/` contient le projet Gradle multi-module et son code Java commun/spécifique.

docs/rules/RULES_DOCUMENTATION.md

@@ -0,0 +1,14 @@
+<!-- file: docs/rules/RULES_DOCUMENTATION.md -->
+<!-- version: 1 -->
+
+# Règles de documentation
+
+- **DOC-001** — La documentation structurée réside sous `docs/`.
+- **DOC-002** — `docs/000-README.md` est l'entrée de navigation documentaire.
+- **DOC-003** — Les documents normatifs résident sous `docs/rules/`.
+- **DOC-004** — Les documents d'architecture résident sous `docs/architecture/`.
+- **DOC-005** — Les documents de validation résident sous `docs/validation/`.
+- **DOC-006** — Les documents internes sont en français ; code, symboles et extraits techniques conservent leur langue naturelle.
+- **DOC-007** — Les tableaux Markdown suivent le format contrôlé par `scripts/audit_markdown_tables.py`.
+- **DOC-008** — Deux lignes blanches consécutives sont interdites hors blocs de code.
+- **DOC-009** — Un delta décrit les changements de sa version et ne devient pas un substitut au `CHANGELOG.md` ou aux règles durables.

docs/rules/RULES_GENERAL.md

@@ -0,0 +1,37 @@
+<!-- file: docs/rules/RULES_GENERAL.md -->
+<!-- version: 1 -->
+
+# Règles générales du projet
+
+## Portée
+
+Les règles `GEN-*` s'appliquent à l'ensemble du dépôt.
+
+## Hiérarchie normative
+
+- **GEN-RULE-001** — `RULES.md` est l'index normatif racine et ne duplique pas les règles détaillées.
+- **GEN-RULE-002** — Les règles sont cumulatives.
+- **GEN-RULE-003** — Toute exception est locale, bornée, justifiée et traçable.
+- **GEN-RULE-004** — Une décision non validée reste une question ouverte et n'est pas transformée en règle par supposition.
+- **GEN-RULE-005** — Une validation n'est déclarée réussie que si elle a réellement été exécutée.
+
+## Noms et fichiers texte
+
+- **GEN-FILE-001** — Les noms de fichiers et répertoires sont en anglais, sans accent ni espace, sauf contrainte externe.
+- **GEN-FILE-002** — Tout fichier texte qui supporte les commentaires commence par son chemin relatif puis par une version entière de fichier.
+- **GEN-FILE-003** — Pour un script avec shebang, le shebang reste en première ligne et les métadonnées suivent immédiatement.
+- **GEN-FILE-004** — La version interne d'un fichier augmente à chaque enregistrement modifiant son contenu et ne diminue jamais.
+- **GEN-FILE-005** — Les fichiers texte se terminent par exactement une fin de ligne lorsque leur format le permet.
+
+## Langues
+
+- **GEN-LANG-001** — Code, identifiants, commentaires de code et rustdocs sont en anglais.
+- **GEN-LANG-002** — La documentation Markdown interne est rédigée en français, sauf nécessité externe explicite.
+
+## Travail et validation
+
+- **GEN-WORK-001** — Une tranche de travail traite un périmètre cohérent et validable.
+- **GEN-WORK-002** — Une tranche planifiée comme trop volumineuse doit être découpée avant exécution.
+- **GEN-WORK-003** — Une erreur introduite par une tranche est corrigée dans cette tranche ou explicitement reportée.
+- **GEN-WORK-004** — Une erreur métier ou architecturale n'est pas masquée par une exception globale de lint ou de test.
+- **GEN-WORK-005** — Les audits du dépôt sont en lecture seule sur les fichiers contrôlés.

docs/rules/RULES_PROJECT.md

@@ -0,0 +1,51 @@
+<!-- file: docs/rules/RULES_PROJECT.md -->
+<!-- version: 1 -->
+
+# Règles spécifiques games.sasedev
+
+## Workspace et crates
+
+- **GAME-WS-001** — Un seul workspace Cargo racine contient les crates Rust du dépôt.
+- **GAME-WS-002** — Toutes les crates Rust résident sous `crates/`.
+- **GAME-WS-003** — Les crates moteur résident sous `crates/engines/` et les crates jeu sous `crates/games/`.
+- **GAME-WS-004** — Une crate hérite par défaut de `workspace.package.version`.
+- **GAME-WS-005** — Une crate arrivée à maturité peut porter sa propre version SemVer lorsqu'une décision documentée rend son cycle autonome nécessaire.
+- **GAME-WS-006** — Les dépendances tierces communes sont centralisées sous `[workspace.dependencies]` et consommées avec `workspace = true` lorsqu'elles sont partagées.
+
+## Générations du moteur
+
+- **GAME-ENGINE-001** — Une génération incompatible de moteur reçoit un nom explicite `engine-vN-*`.
+- **GAME-ENGINE-002** — `engine-v2` n'est pas créé pour une évolution mineure ; il représente une rupture d'API ou d'architecture suffisamment forte pour justifier une coexistence avec `engine-v1`.
+- **GAME-ENGINE-003** — Plusieurs générations de moteur peuvent coexister afin de migrer les jeux progressivement.
+- **GAME-ENGINE-004** — Un jeu déclare explicitement la génération de moteur qu'il consomme.
+- **GAME-ENGINE-005** — Une génération de moteur n'est supprimée qu'après migration, retrait ou archivage de tous ses consommateurs actifs.
+
+## Assets
+
+- **GAME-ASSET-001** — Aucun asset de jeu n'est stocké dans une crate Rust.
+- **GAME-ASSET-002** — Les assets sont stockés sous `assets/`.
+- **GAME-ASSET-003** — `assets/common/` contient uniquement les ressources réellement mutualisées.
+- **GAME-ASSET-004** — Chaque jeu peut posséder `assets/<game>/` pour ses ressources spécifiques.
+- **GAME-ASSET-005** — Le packaging de chaque plateforme assemble les assets communs et spécifiques sans créer de copie source durable dans une crate.
+- **GAME-ASSET-006** — Les chemins logiques d'assets doivent éviter les collisions entre espace commun et espace jeu.
+
+## Android
+
+- **GAME-ANDROID-001** — L'intégration Android réside sous `Android/` et reste extérieure au workspace Rust.
+- **GAME-ANDROID-002** — Java est la langue Android commune par défaut ; Kotlin n'est pas requis.
+- **GAME-ANDROID-003** — `Android/common/` contient la couche réutilisable : activité SDL dérivée, bridge natif, publicité, billing, haptique et services génériques selon les besoins.
+- **GAME-ANDROID-004** — `Android/<game>/` contient uniquement la configuration et les extensions spécifiques au jeu : package, manifeste, ressources Android, identifiants et Java spécifique.
+- **GAME-ANDROID-005** — Le code Java commun ne dépend pas d'une génération particulière du moteur Rust lorsque le contrat plateforme peut rester stable.
+- **GAME-ANDROID-006** — Le contrat JNI est volontairement petit, stable et orienté services plateforme.
+- **GAME-ANDROID-007** — SDL3 peut être consommé via son AAR officiel afin d'éviter de dupliquer ses sources Java/C dans chaque application.
+
+## Plateformes
+
+- **GAME-PLATFORM-001** — Le gameplay ne dépend pas directement d'Android, Desktop ou Web.
+- **GAME-PLATFORM-002** — Les entrées physiques sont traduites en actions de jeu abstraites.
+- **GAME-PLATFORM-003** — Les services Ads, Billing, Share, Haptics, Leaderboard et stockage en ligne sont consommés derrière des contrats plateforme.
+
+## POC
+
+- **GAME-POC-001** — Les premiers POC servent à valider l'architecture et doivent rester volontairement petits.
+- **GAME-POC-002** — Un POC ne justifie pas l'introduction prématurée d'un ECS, moteur physique ou backend complet s'il n'en a pas besoin.

docs/rules/RULES_RUST.md

@@ -0,0 +1,45 @@
+<!-- file: docs/rules/RULES_RUST.md -->
+<!-- version: 1 -->
+
+# Règles Rust générales
+
+## Base
+
+- **RUST-BASE-001** — L'édition Rust est Rust 2024.
+- **RUST-BASE-002** — Chaque `lib.rs` et `main.rs` active `missing_docs`, `unreachable_pub` et interdit `unsafe_code`.
+- **RUST-BASE-003** — Les lints communs sont déclarés au workspace et hérités par les crates.
+- **RUST-BASE-004** — Le code `unsafe` est interdit sauf future exception normative extrêmement ciblée et justifiée.
+- **RUST-BASE-005** — Tout fichier Rust possède les en-têtes `// file: ...` et `// version: N`.
+
+## Documentation et API
+
+- **RUST-DOC-001** — Tout élément `pub` ou `pub(crate)` possède une rustdoc utile au point de déclaration.
+- **RUST-DOC-002** — Toute réexportation visible depuis le crate-root possède une rustdoc adjacente.
+- **RUST-DOC-003** — La façade d'une crate doit permettre de consommer son API sans dépendre des chemins internes de modules.
+
+## Imports et façade
+
+- **RUST-IMPORT-001** — Les éléments partagés appartenant à la crate sont consommés via `crate::Item` après réexport au crate-root.
+- **RUST-IMPORT-002** — Les autres crates consomment l'API via `owner_crate::Item` et non via des modules internes.
+- **RUST-IMPORT-003** — Aucun `pub mod` n'est utilisé pour exposer indirectement une arborescence interne.
+- **RUST-IMPORT-004** — Les glob imports sont interdits.
+- **RUST-IMPORT-005** — Les alias de réexport destinés à masquer des collisions de noms sont interdits ; les symboles reçoivent un nom canonique non ambigu.
+
+## Contrôle de flux et erreurs
+
+- **RUST-FLOW-001** — Les retours sont explicites ; le lint Clippy `implicit_return` est refusé.
+- **RUST-FLOW-002** — `unwrap()` et `expect()` sont interdits dans le code de production.
+- **RUST-FLOW-003** — L'opérateur `?` est interdit ; les chemins d'erreur restent explicites.
+- **RUST-FLOW-004** — `panic!` n'est pas utilisé pour une erreur métier récupérable.
+
+## Formatage
+
+- **RUST-FMT-001** — `rustfmt.toml` racine est canonique.
+- **RUST-FMT-002** — `cargo fmt --all -- --check` fait partie des gates.
+- **RUST-FMT-003** — La largeur maximale canonique est 160 caractères.
+
+## Tests
+
+- **RUST-TEST-001** — Les tests unitaires restent proches de la crate ou du module testé.
+- **RUST-TEST-002** — Les tests d'intégration résident sous `tests/` de la crate concernée.
+- **RUST-TEST-003** — Les tests ne rendent pas artificiellement publique une API privée.

docs/rules/VERSION_WORKFLOW.md

@@ -0,0 +1,75 @@
+<!-- file: docs/rules/VERSION_WORKFLOW.md -->
+<!-- version: 1 -->
+
+# Versionnement, maturité et livraisons
+
+## SemVer canonique
+
+Le projet utilise SemVer et les labels de maturité normalisés suivants :
+
+```text
+X.Y.Z-0-pre.N
+X.Y.Z-0-pre.N.fix.M
+X.Y.Z-1-alpha.N
+X.Y.Z-1-alpha.N.fix.M
+X.Y.Z-2-beta.N
+X.Y.Z-2-beta.N.fix.M
+X.Y.Z-3-rc.N
+X.Y.Z-3-rc.N.fix.M
+X.Y.Z
+```
+
+`N` et `M` sont des entiers positifs sans zéro initial.
+
+## Sens des niveaux
+
+- `0-pre.N` : construction initiale, architecture et fonctionnalités encore très mouvantes ;
+- `1-alpha.N` : périmètre fonctionnel principal établi mais encore incomplet ou instable ;
+- `2-beta.N` : fonctionnalités attendues largement présentes, priorité à la stabilisation et aux tests ;
+- `3-rc.N` : candidat de publication, aucune évolution non indispensable ;
+- `X.Y.Z` : version stable.
+
+## Correctifs
+
+Un suffixe `.fix.M` corrige la prerelease immédiatement précédente sans changer son objectif fonctionnel. Exemple :
+
+```text
+0.1.0-0-pre.4
+0.1.0-0-pre.4.fix.1
+0.1.0-0-pre.4.fix.2
+0.1.0-0-pre.5
+```
+
+Après une version stable, un correctif produit normalement un nouveau patch SemVer, par exemple `0.1.1`, et non `0.1.0.fix.1`.
+
+## Version workspace et versions autonomes
+
+Les crates héritent par défaut de `workspace.package.version`. Une crate mature peut adopter sa propre version lorsque son contrat, sa compatibilité ou sa distribution justifie un cycle autonome. Cette décision est documentée dans le delta qui l'introduit.
+
+## Livraisons
+
+La livraison normale est une archive delta. Le nom canonique est :
+
+```text
+games-sasedev-<semver>-delta.zip
+```
+
+Le delta contient uniquement les fichiers ajoutés ou modifiés relativement à la base déclarée, plus le document de delta correspondant. La toute première livraison constitue nécessairement une baseline et son delta contient l'ensemble des fichiers initiaux.
+
+## Deltas
+
+Les documents sont rangés sous :
+
+```text
+deltas/X.Y.Z/<prerelease-or-rel>.md
+```
+
+Exemples :
+
+```text
+deltas/0.1.0/0-pre.1.md
+deltas/0.1.0/0-pre.1.fix.1.md
+deltas/0.1.0/1-alpha.1.md
+deltas/0.1.0/3-rc.2.md
+deltas/0.1.0/rel.md
+```

docs/validation/001-VALIDATION_GATES.md

@@ -0,0 +1,17 @@
+<!-- file: docs/validation/001-VALIDATION_GATES.md -->
+<!-- version: 1 -->
+
+# Gates de validation
+
+Baseline Rust et documentation :
+
+```bash
+cargo fmt --all -- --check
+python3 scripts/audit_rust_workspace_rules.py
+python3 scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs deltas prompts
+cargo check --workspace
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace
+```
+
+Le build Android n'est pas une gate de `0.1.0-0-pre.1` : le projet Gradle exécutable et l'intégration SDL3/NDK sont planifiés pour une prerelease dédiée.