refactor: move mission flow state into game store

docs/technical/game-flow.md

@@ -0,0 +1,187 @@
+# Game Flow - La Fabrik
+
+## Étapes du jeu
+
+```
+intro → start-intro → naming → bienvenue → star-move → mission2 → searching_problem → preparation → outOfFabrik
+```
+
+---
+
+## Détail des étapes
+
+### 1. `intro` (initial)
+
+- État initial au chargement du jeu
+- Aucune action, juste une étape de départ
+- Transition automatique vers `start-intro`
+
+### 2. `start-intro`
+
+- **Déclenchement** : Auto-transition depuis `intro` quand la scène est chargée
+- **Action** : Joue l'audio d'intro (`intro`)
+- **Attente** : Attend que l'audio se termine
+- **Transition** : Vers `naming` quand l'audio se termine
+
+### 3. `naming`
+
+- **Déclenchement** : Quand l'audio d'intro se termine
+- **Action** : Affiche un input pour demander le prénom du joueur
+- **Attente** : L'utilisateur entre son prénom et valide
+- **Transition** : Vers `bienvenue` quand l'utilisateur valide
+
+### 4. `bienvenue`
+
+- **Déclenchement** : Quand l'utilisateur valide son prénom
+- **Actions** :
+  - Affiche "Bienvenue {prénom} !" à l'écran
+  - Joue l'audio de bienvenue
+- **Attente** : Attend que l'audio se termine
+- **Transition** : Vers `star-move` quand l'audio se termine
+
+### 5. `star-move`
+
+- **Déclenchement** : Quand l'audio de bienvenue se termine
+- **Action** : Active le mouvement du joueur (`setCanMove(true)`)
+- **État** : Le joueur peut maintenant se déplacer librement
+- **Zone** : La détection de zone devient active (ZoneDetection)
+
+### 6. `mission2`
+
+- **Déclenchement** : Quand le joueur entre dans la zone `fabrikExit` (position: `[-5, 25, -15]`)
+- **Actions** :
+  - Stocke `activityCity: false` dans le store Zustand
+  - Joue l'audio `alertCentral`
+- **État** : Les objets avec hook `useActivityCity()` détectent le changement et jouent leurs animations
+- **Attente** : Le joueur atteint la zone de trigger pour `searching_problem`
+
+### 7. `searching_problem`
+
+- **Déclenchement** : Quand le joueur entre dans la zone `searchingProblemZone` (position: `[-5, 25, -30]`)
+- **Actions** :
+  - Joue l'audio `searchingProblem`
+  - Affiche l'objet "central" (position: `[1, 15, -45]`)
+- **Attente** : Le joueur interagit avec l'objet "central"
+
+### 8. `preparation`
+
+- **Déclenchement** : Quand le joueur interagit avec l'objet "central"
+- **Actions** :
+  - Bloque le mouvement (`setCanMove(false)`)
+  - Cache l'objet "central"
+
+### 9. `outOfFabrik`
+
+- **Déclenchement** : (non implémenté pour le moment)
+- **Action** : Transition vers l'étape finale
+
+---
+
+## Fichiers clés
+
+| Fichier                                 | Rôle                                                      |
+| --------------------------------------- | --------------------------------------------------------- |
+| `src/stores/gameStore.ts`               | Store Zustand pour l'état global du jeu                   |
+| `src/stateManager/GameStepManager.ts`   | Synchronise avec le store Zustand                         |
+| `src/components/game/GameFlow.tsx`      | Gère les transitions automatiques et la lecture audio     |
+| `src/components/ui/IntroUI.tsx`         | Affiche l'input pour le prénom et le message de bienvenue |
+| `src/components/zone/ZoneDetection.tsx` | Détecte quand le joueur entre dans une zone               |
+| `src/components/3d/CentralObject.tsx`   | Objet interactif "central" pour la mission 2              |
+| `src/data/audioConfig.ts`               | Chemins des fichiers audio                                |
+| `src/data/zones.ts`                     | Configuration des zones de transition                     |
+| `src/hooks/useActivityCity.ts`          | Hook pour détecter le changement d'activité de la ville   |
+
+---
+
+## Configuration audio
+
+```typescript
+// src/data/audioConfig.ts
+export const AUDIO_PATHS = {
+  intro: "/sounds/fa.mp3",
+  bienvenue: "/sounds/fa.mp3",
+  alertCentral: "/sounds/fa.mp3",
+  searchingProblem: "/sounds/fa.mp3",
+};
+```
+
+---
+
+## Configuration des zones
+
+```typescript
+// src/data/zones.ts
+export const ZONES: Zone[] = [
+  {
+    id: "fabrikExit",
+    position: [-5, 25, -15],
+    radius: 10,
+    height: 20,
+    targetStep: "mission2",
+  },
+  {
+    id: "searchingProblemZone",
+    position: [-5, 25, -30],
+    radius: 10,
+    height: 20,
+    targetStep: "searching_problem",
+  },
+];
+```
+
+---
+
+## Store Zustand
+
+```typescript
+// src/stores/gameStore.ts
+interface GameState {
+  step: GameStep;
+  activityCity: boolean;
+  playerName: string;
+  canMove: boolean;
+  setStep: (step: GameStep) => void;
+  setActivityCity: (value: boolean) => void;
+  setPlayerName: (name: string) => void;
+  setCanMove: (canMove: boolean) => void;
+}
+```
+
+---
+
+## Hooks personnalisés
+
+### useActivityCity
+
+Permet aux objets 3D de réagir au changement d'activité de la ville :
+
+```typescript
+import { useActivityCity } from "@/hooks/useActivityCity";
+
+function MyAnimatedObject() {
+  const activityCity = useActivityCity(); // true par défaut, false en mission2
+
+  // L'animation se déclenche quand activityCity change à false
+  // Utiliser useEffect pour réagir au changement
+}
+```
+
+---
+
+## Debug
+
+En mode debug (`?debug` dans l'URL), on peut voir :
+
+- **Game Step** : L'étape actuelle dans le panneau lil-gui
+- **Player Position** : Position X, Y, Z du joueur en temps réel
+- **Zone Visualization** : Anneaux visuels au sol pour les zones + cylindres transparents
+
+---
+
+## Notes techniques
+
+- Le mouvement du joueur est bloqué tant que `canMove` est `false`
+- Le store Zustand (`useGameStore`) est la source principale de vérité
+- `GameStepManager` synchronise automatiquement avec le store Zustand lors des transitions
+- Les transitions via les zones utilisent `GameStepManager.transitionTo()` qui met à jour le store
+- L'audio utilise un callback `onEnded` pour déclencher les transitions automatiques

docs/technical/mission-flow.md

@@ -0,0 +1,79 @@
+# Mission Flow
+
+This document describes the mission intro and mission 2 prototype flow after it was merged into the current architecture.
+
+## Source Of Truth
+
+Mission flow state lives in the global game store:
+
+```txt
+src/managers/stores/useGameStore.ts
+```
+
+The store owns the `missionFlow` slice:
+
+```ts
+missionFlow: {
+  step: GameStep;
+  activityCity: boolean;
+  playerName: string;
+  canMove: boolean;
+  dialogMessage: string | null;
+}
+```
+
+This keeps global gameplay state in Zustand instead of splitting it across a separate mission store or a gameplay manager.
+
+## Managers Boundary
+
+Managers stay responsible for local runtime services:
+
+- `AudioManager` owns audio elements, audio pools, music playback, category volume, and stereo pan.
+- `InteractionManager` owns transient focused/nearby/held interaction handles.
+
+Mission progression is not owned by a manager. Components update the store through explicit actions such as `setFlowStep`, `setCanMove`, `showDialog`, and `hideDialog`.
+
+## Runtime Components
+
+- `src/components/game/GameFlow.tsx` reacts to `missionFlow.step` and triggers one-off side effects such as intro audio and movement unlocks.
+- `src/components/zone/ZoneDetection.tsx` reads the camera position and moves the flow to a target step when the player enters a configured zone.
+- `src/components/three/interaction/CentralObject.tsx` and `VillageoisHelperObject.tsx` expose temporary interactive mission objects.
+- `src/pages/page.tsx` mounts mission HTML overlays: `IntroUI`, `BienvenueDisplay`, and `DialogMessage`.
+- `src/world/player/PlayerController.tsx` reads `missionFlow.canMove` as an additional movement lock.
+
+## Step Sequence
+
+The prototype currently uses these steps:
+
+```ts
+"intro" |
+  "start-intro" |
+  "naming" |
+  "bienvenue" |
+  "star-move" |
+  "mission2" |
+  "searching" |
+  "helped" |
+  "manipulation" |
+  "outOfFabrik";
+```
+
+These steps are mission-flow prototype states. They do not replace `mainState` or the repair mission step machine used by `RepairGame`.
+
+## Zone Configuration
+
+Zone triggers live in:
+
+```txt
+src/data/zones.ts
+```
+
+Each zone has an id, position, radius, height, and `targetStep`. `ZoneDetection` marks a zone as triggered after the first activation so the same zone does not replay its transition every frame.
+
+## Rules
+
+- Keep mission flow state in `useGameStore.missionFlow`.
+- Do not reintroduce `GameStepManager` for global state transitions.
+- Do not create a second Zustand store for mission flow unless the state becomes independent from game progression.
+- Keep side effects such as audio playback in components or service managers, but keep the state transition itself in the store.
+- Keep per-frame values such as camera position and zone distance checks out of Zustand.

docs/technical/zustand.md

@@ -59,6 +59,7 @@ Rule of thumb:
 The store exposes:
 
 - `mainState`: the active game phase
+- `missionFlow`: intro and mission 2 prototype state
 - `intro`: intro-specific state
 - `bike`: e-bike mission state
 - `pylone`: power grid mission state
@@ -66,6 +67,8 @@ The store exposes:
 - `outro`: ending state
 - actions for direct updates and progression updates
 
+The `missionFlow` slice contains the prototype step, player name, movement lock, city activity flag, and temporary dialog message. It is in the main game store because it is global gameplay state used by UI, world components, and the player controller.
+
 The mission steps currently use this sequence:
 
 ```ts
@@ -141,6 +144,8 @@ For repair missions, it mounts the reusable `RepairGame` component with a missio
 
 Mission-specific behavior stays in `src/data/gameplay/repairMissions.ts`: each mission can define its broken nodes, placeholder targets, scan duration, and reassembly duration without adding mission branches to `RepairGame`.
 
+The intro and mission 2 prototype flow is documented separately in `docs/technical/mission-flow.md`. It intentionally uses the same `useGameStore` source of truth instead of a dedicated `GameStepManager` or a second Zustand store.
+
 That means the scene can progressively move toward this pattern:
 
 ```tsx
@@ -171,8 +176,9 @@ Current overlays:
 - `Crosshair`: player aiming helper
 - `InteractPrompt`: interaction prompt
 - `RepairMovementLockIndicator`: player-facing indicator shown while repair steps temporarily disable movement
+- Mission flow overlays such as `IntroUI`, `BienvenueDisplay`, and `DialogMessage` are mounted by `src/pages/page.tsx` because they are route-level HTML overlays rather than persistent game HUD elements.
 
-`src/pages/page.tsx` should stay thin and mount only the canvas and `GameUI`.
+`src/pages/page.tsx` should stay thin and mount the canvas, persistent `GameUI`, and route-level overlays.
 
 ## Regression Rules