fix: shadow caster index, torus winding, per-frame device poll ; close stage 15

Bug fixes found while validating stage 15:
- demo: set_shadow_caster(Some(0)) selected the default +Z light (packed
  index 0 from Lights::new()); the demo's warm directional light is packed
  at index 1. The shadow camera then looked down -Z, so misaligned objects
  occluded each other (cone/torus rendered black). Use index 1.
- primitives::torus: index winding was flipped ([a,c,b]); the outer surface
  (outward normals, CCW from outside) was culled and only the dark interior
  stayed visible. Reversed to [a,b,c]/[b,d,c] so it is CCW from outside.
- app: call device.poll() each frame in about_to_wait; without it wgpu
  async callbacks (on_submitted_work_done, map_async) never fire in the
  windowed loop.

Docs:
- conf: clarify the embedded-shader fallback is expected/harmless and that
  SHADOW_SHADER_PATH is kept for API compatibility only.
- README item 15: runtime-verified headless.
- DRAFT.md: emptied to a completion summary per convention (full stage-15
  plan preserved in git history).

docs/DRAFT.md

@@ -1,159 +1,45 @@
 # DRAFT — Étape suivante
 
-> 📅 **Plan de l'Étape 15 (2026-09-19).** L'Étape 14 (shadow mapping) est **FAIT & vérifié** (voir
-> historique git + ROADMAP 4.2). Cette étape est une **« grosse étape »** : elle réunit les acquis en
-> un **exemple final interactif** et pose deux briques réutilisables — une **bibliothèque de meshes
-> primitifs** et un **module d'input unifié** (clavier / souris / gamepad). Elle relance aussi deux
-> items de la ROADMAP : `2.2` (primitifs) et `2.3` (input), prérequis de l'exemple final (Phase 5).
->
-> Source de vérité = code + README.md. Ce document est vidé à la complétion de chaque étape.
+> 📅 **Étape 15 — TERMINÉE (2026-09-20).** Document vidé conformément à la convention
+> (« ce document est vidé à la complétion de chaque étape »). Le plan détaillé (objectifs,
+> décisions D1–D9, détail d'implémentation, périmètre) est archivé dans l'historique git du
+> présent fichier — `git log -- docs/DRAFT.md`.
 
----
+## Bilan de l'Étape 15 (archive)
 
-## Objectif de l'Étape 15
+**Objectif atteint** : un démonstrateur `demo` interactif cumulant les étapes 8-14 — un sol texturé
+damier + 6 primitives (cube, sphère UV, icosphère, cylindre, cône, tore) texturées, éclairées
+(multi-lumières + spot, Étapes 12-13), projetant des **ombres** (Étape 14), et pilotées par une
+**caméra orbitale** au clavier/souris (glisser = orbite, molette = zoom, `R` = reset, `1`/`2`/`3` =
+présettes) via un nouveau **module d'input unifié** — le tout dans le workflow déclaratif
+`AppBuilder` + `AppHandler`, sans importer wgpu.
 
-Produire un **démonstrateur `demo`** interactif qui cumule tout le travail des étapes 8-14 :
-un sol + plusieurs **primitives** (cube, icosphère, cylindre, cône) **texturées**, **éclairées**
-(multi + spot, Étapes 12-13), projetant des **ombres** (Étape 14), et survolées par une **caméra
-orbitale** pilotée au **clavier/souris** via un nouveau module d'input unifié — le tout dans le
-workflow déclaratif `AppBuilder` + `AppHandler`, sans importer wgpu.
+**Trois volets livrés :**
+- **15.A — `math::primitives`** : générateurs de `Geometry` prêts à l'emploi (`cube`, `plane`,
+  `uv_sphere`, `icosphere`, `cylinder`, `cone`, `torus`) + 6 tests. Le `cube_geometry` des exemples
+  (`cube.rs`, `spot_test.rs`) a été factorisé vers `math::cube(1.0)`.
+- **15.B — `core::input`** : `InputState` unifié (clavier `KeyCode` / souris position+delta+molette,
+  sémantique pressed/held/released) branché dans `App` (`app.input` public, rotation
+  `begin_frame`/`end_frame` autour de `update`) + 5 tests. Gamepad **reporté** (D7) — champ réservé.
+- **15.C — `demo` + caméra orbitale** : `resources::CameraController` (yaw/pitch/distance/target,
+  `apply_to`) + exemple `demo` (sol + 6 primitives + lumières + ombres + caméra orbitale).
 
-Trois volets, à faire en sous-étapes de façon **incrémentale** (chaque volet compilable/testable seul) :
+**Livraison** : ROADMAP 2.2 (primitifs) et 2.3 (input) cochées (gamepad `[~]` partiel) ; README items
+13-15 ajoutés ; `cargo fmt --all -- --check` propre ; build workspace + exemples ; 28 tests unitaires
++ doctests au vert ; `demo` vérifié au runtime (headless).
 
-- **15.A — `math::primitives`** : générateurs de `Geometry` prêts à l'emploi.
-- **15.B — `core::input`** : `InputState` unifié (clavier/souris/gamepad) branché dans `App`.
-- **15.C — `demo`** : exemple final = primitives + textures + lumières + ombres + caméra orbitale.
+**Corrections de bugs découvertes en cours de route :**
+- *Ombres du `demo`* : `set_shadow_caster(Some(0))` désignait la lumière directionnelle **+Z par
+  défaut** préchargée par `Lights::new()` (index 0 packé) au lieu de la lumière chaude du demo
+  (index 1) → la caméra d'ombre regardait −Z et des objets non-alignés s'occluaient mutuellement
+  (tore/cône noircis). Corrigé en `Some(1)`.
+- *Tore noir* : le winding du tore (`primitives::torus`) était inversé (`[a, c, b]`), la face externe
+  était cullée et seul l'intérieur (normales vers l'extérieur → N·L ≤ 0) restait visible. Corrigé en
+  `[a, b, c]` + `[b, d, c]` (CCW vu de l'extérieur).
+- *`App::run`* : ajout d'un `device.poll()` par frame — sans lui, les callbacks asynchrones wgpu
+  (`on_submitted_work_done`, `map_async`) ne firent jamais dans la boucle de production.
+- *Docs* : `STANDARD_SHADER_PATH` pointait vers un fichier absent (le vrai shader est embarqué via
+  `include_str!`) ; le fallback est attendu et inoffensif — doc corrigée.
 
----
-
-## Décisions (D1…Dn) — à confirmer au fil de l'étape
-
-- **D1 — Emplacement des primitives : `math::primitives`** (à côté de `math::geometry`). Les
-  primitives **produisent une `Geometry`** (purement CPU, sans GPU) ; les ranger dans `math` préserve
-  la cohérence avec `Geometry`/`GeometryError` (`math/geometry.rs`). Exposées via `math::primitives::*`.
-  *Alternative* : `resources::primitives` (discoverabilité près de `Mesh`) — **rejetée** car on reste
-  en mathématiques pures avant tout upload GPU.
-- **D2 — API des primitives** : chaque générateur renvoie une **`Geometry` complète** (positions +
-  normales + UVs + indices, pas de couleurs → défaut blanc opaque). Signatures proposées :
-  - `cube(size: f32) -> Geometry` (arête `size`, normales/UVs par face, 24 sommets / 36 indices)
-  - `plane(width: f32, depth: f32, seg_x: u32, seg_z: u32) -> Geometry` (normales +Y, UVs étirés)
-  - `uv_sphere(radius: f32, sectors: u32, stacks: u32) -> Geometry` (normales sphériques + UV lat/long)
-  - `icosphere(radius: f32, subdivisions: u32) -> Geometry` (subdivision d'icosaèdre ; normales = position normalisée)
-  - `cylinder(radius: f32, height: f32, sectors: u32) -> Geometry` (couvercle/haut/bas + flanc)
-  - `cone(radius: f32, height: f32, sectors: u32) -> Geometry` (sommet + base ouverte/fermée)
-  - `torus(major: f32, minor: f32, major_segments: u32, minor_segments: u32) -> Geometry` *(bonus)*
-  Chaque fonction documente les conventions de repère (axe Y vers le haut) et l'orientation des
-  normales (pertinent pour l'éclairage car le culling reste désactivé par défaut).
-- **D3 — Factorisation du `cube_geometry` des exemples** : remplacer le helper local de `cube.rs`
-  (et le `shadow_test`/`spot_test` s'ils en ont un) par `math::primitives::cube(1.0)`. Pas de
-  changement visuel (mêmes normales/UVs) → non-régression vérifiable.
-- **D4 — Emplacement de l'input : `core::input`** (à côté de `context.rs`/`frame.rs`/`renderer.rs`).
-  `InputState` est **CPU** (consomme les événements winit) ; il n'est **pas** dans WGSL (langage de
-  shader côté GPU, sans I/O) — D4a. Un éventuel uniform `InputUniforms` consultable en WGSL (ex.
-  debug/gizmo) est **hors périmètre** pour l'instant, gardé en note pour une étape ultérieure.
-- **D5 — Modèle d'état `InputState`** : sémantique **pressed / held / released** par frame, plus
-  souris (position, delta, boutons, molette) et gamepad (v1 minimale). Rotation par
-  `begin_frame()` (à chaque `about_to_wait`, avant `AppHandler::update`) et `end_frame()` (après
-  render), permettant de dériver `pressed`/`released` depuis les événements et de remettre les deltas
-  à zéro proprement.
-- **D6 — Exposition dans `App`** : `App` possède un `InputState` ; `app.input()` (lecture) /
-  `app.input_mut()` (écriture) disponibles dans `setup`/`update`/`render`. Le `event_handler`
-  (winit 0.30) **forwarde** les `WindowEvent` concernés (KeyboardInput, MouseInput, CursorMoved,
-  MouseWheel, CursorLeft/Entered) et les `DeviceEvent` (MouseMotion, boutons de gamepad si
-  activés) vers `InputState::handle(...)`. `KeyboardInput` demande `listen_device_events` si on veut
-  le delta souris hors capture — à vérifier selon la config winit 0.30.
-- **D7 — Gamepad (v1 minimale / optionnelle)** : winit fournit les `DeviceEvent::GamepadButtonChanged` /
-  `GamepadAxisChanged` (virtuels) ; on les capture **si présent** dans l'API (`Rc`/`Vec` par slot ou
-  index), sans abstraction complète de mapping. Si le support winit 0.30 s'avère trop fragile, on
-  **reporte** le gamepad (item ROADMAP `2.3` reste alors partiellement `[ ]`) et on livre d'abord
-  clavier/souris — l'exemple final n'a besoin **que** du clavier + souris.
-- **D8 — Caméra orbitale** : **contrôleur** `CameraController { yaw, pitch, distance, target }` qui
-  met à jour la `Camera` active (position recomputée sphériquement autour de `target`, `with_perspective`
-  inchangée) depuis `InputState`. Le **cline multi-caméras (`set_active_camera`, ROADMAP 2.1) n'est PAS
-  requis** pour l'étape : on pilote la caméra active unique. 2.1 reste un item à part plus tard (ou est
-  optionnel ici si le temps le permet).
-- **D9 — Exemple `demo`** : scène statique de primitives (sol = `plane` texturé damier ; cube,
-  icosphère, cylindre, cône posés dessus, chacun texturé procéduralement) + lumière directionnelle
-  ombre-porteuse (Étape 14) + point + spot (Étapes 12-13). `update` fait lentement tourner la scène
-  (comme `cube`) **et** met à jour la caméra orbitale via l'input (glisser = orbite, molette = zoom,
-  touches = reset / présettes / bascule light). Un petit helper de **texture procédurale**
-  (damier/couleurs) évite tout asset disque (réutilise le pattern `checkerboard_rgba` de `cube.rs`).
-
----
-
-## Détail d'implémentation
-
-### 15.A — `math::primitives` (bibliothèque de meshes prédéfinis)
-
-Fichier : `lib/src/math/primitives.rs` (+ `pub mod primitives;` dans `math/mod.rs`).
-
-- Algorithmes procéduraux classiques ; chaque sortie est une `Geometry` validée
-  (`Geometry::validate` ne doit pas renvoyer d'erreur — invariant testé).
-- Conventions : axe **Y vers le haut**, origine centrée (sauf `plane` éventuellement ancré),
-  normales **orientées vers l'extérieur**, UVs [0,1]² aussi continus que possible.
-- `cube` : quotient le code de `cube_geometry` de `cube.rs` (mêmes faces/normales/UVs/indices).
-
-Tests (dans `math/primitives.rs` ou un `#[cfg(test)]`) :
-- comptes attendus : cube → 24 sommets / 36 indices ; uv_sphere → `(sectors+1)*(stacks+1)` sommets ;
-- `icosphere` : subdivision 0 → icosaèdre (12 sommets / 20 faces / 60 indices), refinement augmente ;
-- normales de longueur == positions, normes ≈ 1 (tolérance), indices dans les bornes ;
-- `plane(width, depth, 1, 1)` → 4 sommets / 6 indices, normales +Y.
-
-### 15.B — `core::input` (module d'input unifié)
-
-Fichier : `lib/src/core/input.rs` (+ `pub mod input;` et `pub use input::InputState;` dans
-`core/mod.rs` si pertinent).
-
-Structures :
-- `struct InputState { keys: KeyStates, mouse: MouseState, gamepad: GamepadState }`
-- `KeyStates` : ensembles `pressed/held/released` sur une clé
-  (`winit::keyboard::Key`/`VirtualKeyCode` selon la version winit 0.30 — à trancher en D-impl) ;
-- `MouseState` : `position: (f32, f32)`, `delta: (f32, f32)`, `scroll: (f32, f32)`,
-  boutons `MouseButton` avec sémantique pressed/held/released ;
-- `GamepadState` : (v1 minimale) tableaux boutons/axes par index, optionnels.
-- `GamepadState` peut être factorable/ignoré si winit ne livre pas proprement (D7).
-
-Méthodes publiques :
-- `begin_frame()` / `end_frame()` — rotation des états, remise à zéro des deltas ;
-- `handle(event: &winit::event::WindowEvent)` / `handle_device(event: &impl)` —
-  dispatch interne (kbd/mouse/scroll/gamepad) ;
-- requêtes : `key_pressed/held/released(k)`, `mouse_button_*`, `mouse_position()/delta()/scroll()`.
-
-Branchement (`app.rs`) :
-- le `AppRunner` (window_event, ~l.293) forwarde les événements concernés vers `app.input_mut()`,
-  et à chaque `about_to_wait` (l.283) appelle `input_mut().begin_frame()` avant
-  `handler.update()`, puis `input_mut().end_frame()` après la frame.
-- `App` expose `input()` / `input_mut()`.
-
-### 15.C — Caméra orbitale + exemple final `demo`
-
-- `COMBO` : ajouter `OrbitalCamera` (dans `resources/camera.rs` ou un controleur proche) —
-  `pub struct CameraController { pub yaw: f32, pub pitch: f32, pub distance: f32, pub target: Vec3 }`
-  + `fn apply_to(&self, cam: &mut Camera)` (repositionne `cam.position` en sphériques).
-- Exemple `lib/examples/demo.rs` (workflow déclaratif, comme `cube`/`shadow_test`) :
-  - `setup` : textures procédurales par mesh, `primitives::*`, matériaux `standard`,
-    lumières directionnelle (ombre-porteuse via `set_shadow_caster`) + point + spot, caméra par défaut ;
-  - `update` : lire `app.input()`, mettre à jour `CameraController` (glisser/déplacer la souris =
-    yaw/pitch ; molette = distance ; `R` = reset ; touches `1/2/3` = présettes de vue), appliquer à
-    la caméra active, rotation lente des primitives ;
-  - doc du fichier en anglais (convention README/exemples), commentaires internes au besoin.
-
-### Livrables & checklist finale
-
-- [x] 15.A `math::primitives` + tests (build + `cargo test`)
-- [x] 15.B `core::input` + boucle `App` + tests légers
-- [x] 15.C caméra orbitale + exemple `demo` vérifié au runtime
-- [x] Factorisations exemples (primitives::cube) sans régression visuelle
-- [x] `cargo fmt --all -- --check` propre, build workspace + exemples + tests
-- [x] ROADMAP : cocher `2.2` et `2.3` (ou marquer le gamepad `[~]` partiel si reporté) ;
-      README : ajouter les items roadmap N°13-15 (primitives, input, démo)
-- [ ] Fin d'étape : vider ce `DRAFT.md` (bandeau bilan archivé)
-
----
-
-## Périmètre hors-étape (reporté / refusé)
-
-- `set_active_camera` multi-caméras (ROADMAP 2.1) — sauf si trivial, sinon item séparé.
-- Uniform `InputUniforms` consultable en WGSL (debug/gizmo shader) — note pour plus tard.
-- GPU-driven (Phase 3), batching matériau (4.3), LOD, HDR/tone mapping — étapes ultérieures.
-- Gamepad complet (mapping abstrait) — v1 minimale seulement (D7).
+**Hors périmètre (reporté)** : `set_active_camera` multi-caméras (2.1), `InputUniforms` WGSL
+(debug/gizmo), GPU-driven (Phase 3), batching matériau (4.3), LOD, HDR/tone mapping, gamepad complet.