refactor: move mission flow state into game store

Merge remote-tracking branch 'origin/develop' into feat/mission-2
# Conflicts: # package-lock.json # package.json # src/App.tsx # src/components/three/interaction/CentralObject.tsx # src/components/three/interaction/VillageoisHelperObject.tsx # src/managers/GameStepManager.ts # src/stateManager/AudioManager.ts # src/world/World.tsx # src/world/player/PlayerController.tsx
2026-05-11 18:02:00 +02:00 · 2026-05-11 17:46:42 +02:00 · 2026-05-11 15:33:18 +00:00 · 2026-05-11 17:32:47 +02:00 · 2026-05-11 17:31:14 +02:00 · 2026-05-11 15:23:31 +00:00
950 changed files with 26547 additions and 1706 deletions
@@ -11,7 +11,7 @@ You are working on **La Fabrik**, an interactive 3D web experience built with Re
 ## Current Implementation

 - Stack: React 19, Three.js, `@react-three/fiber`, `@react-three/drei`, `@react-three/rapier`, TypeScript, Vite
- No external global state library is used.
+- Zustand is used for shared game progression state.
 - Current singleton-style services are limited to:
  - `InteractionManager`
  - `AudioManager`
@@ -24,7 +24,8 @@ You are working on **La Fabrik**, an interactive 3D web experience built with Re

 ## Current Architecture Rules

- Scene objects live in `src/world/` and `src/components/3d/`.
+- Scene objects live in `src/world/` and `src/components/three/`.
+- Shared 3D components are grouped by domain under `src/components/three/models/`, `src/components/three/interaction/`, `src/components/three/gameplay/`, and `src/components/three/world/`.
 - HTML overlays live in `src/components/ui/`.
 - Shared static config lives in `src/data/`.
 - Debug tooling lives in `src/utils/debug/` and `src/hooks/debug/`.
@@ -58,19 +58,18 @@ if (debug.active) {
 r3f-perf is loaded only in debug mode to avoid dependency issues in production:

 ```tsx
-// src/utils/debug/DebugPerf.tsx
 import { Suspense, lazy } from "react";
-import { Debug } from "@/utils/debug/Debug";
+import { useShowDebugPerf } from "@/hooks/debug/useShowDebugPerf";

 const Perf = lazy(() => import("r3f-perf").then((m) => ({ default: m.Perf })));

 export function DebugPerf() {
-  const debug = Debug.getInstance();
-  if (!debug.active) return null;
+  const showDebugPerf = useShowDebugPerf();
+  if (!showDebugPerf) return null;

  return (
    <Suspense fallback={null}>
-      <Perf position="top-left" />
+      <Perf position="top-right" />
    </Suspense>
  );
 }
@@ -89,6 +88,9 @@ Usage in Canvas:

 - All debug UI goes through `Debug.getInstance()` — never inline `if (isDev)` checks
 - r3f-perf is always lazy-imported, never a hard dependency in scene components
- Debug folders should be organized by domain (Lighting, PostFX, Player, Zone)
+- Debug folders should be organized by domain (Lighting, Player, Zone, Interaction)
+- Global debug controls include camera mode, scene mode, `R3F Perf`, and `Debug Overlay`
+- Interaction-specific controls such as interaction spheres belong in the `Interaction` folder
+- HTML debug panels should be grouped under `src/components/ui/debug/DebugOverlayLayout.tsx`
 - Debug panel must not affect production builds — it simply doesn't mount when `?debug` is absent
 - Clean up debug folders in `destroy()` when relevant
@@ -28,14 +28,17 @@ export class SomeManager {

 ## Managers in this project

-| Manager            | File                                   | Role                                                                                                       |
-| ------------------ | -------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `GameManager`      | `src/stateManager/GameManager.ts`      | Single source of truth. Owns phase, zone, mission, input lock, dialogue. Has `subscribe()` + `getState()`. |
-| `CinematicManager` | `src/stateManager/CinematicManager.ts` | GSAP timelines. Locks/unlocks input via GameManager.                                                       |
-| `AudioManager`     | `src/stateManager/AudioManager.ts`     | Music, SFX, spatial audio. Reads phase from GameManager.                                                   |
-| `ZoneManager`      | `src/stateManager/ZoneManager.ts`      | Zone entry/exit detection, LOD triggers. Notifies GameManager of zone changes.                             |
+| Manager              | File                                 | Role                                                                          |
+| -------------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
+| `AudioManager`       | `src/managers/AudioManager.ts`       | Music and SFX playback.                                                       |
+| `InteractionManager` | `src/managers/InteractionManager.ts` | Focus, nearby, trigger, grab, and hand-grab interaction state.                |
+| `GameManager`        | target-state only                    | Future single source of truth for phase, zone, mission, input lock, dialogue. |
+| `CinematicManager`   | target-state only                    | Future GSAP timeline orchestrator.                                            |
+| `ZoneManager`        | target-state only                    | Future zone entry/exit detection and LOD triggers.                            |

-## GameManager is the orchestrator
+## Target-State GameManager
+
+`GameManager` does not exist in the current implementation. The following pattern is target-state guidance only and should not be applied until the manager exists in code.

 ```ts
 export class GameManager {
@@ -51,7 +54,7 @@ export class GameManager {
 }
 ```

-Components and hooks access other managers **through GameManager only**:
+When a `GameManager` exists, components and hooks should access other managers through it:

 ```ts
 // Correct
@@ -61,7 +64,7 @@ GameManager.getInstance().cinematic.play("intro");
 CinematicManager.getInstance().play("intro");
 ```

-## Subscribe pattern (GameManager only)
+## Target-State Subscribe Pattern

 ```ts
 private listeners = new Set<() => void>()
@@ -76,9 +79,9 @@ private emit(): void {
 }
 ```

-Every `set*()` method calls `this.emit()` to notify subscribers.
+In that target-state manager, every `set*()` method calls `this.emit()` to notify subscribers.

-## React bridge hook
+## Target-State React Bridge Hook

 ```ts
 // hooks/useGameState.ts
@@ -96,8 +99,8 @@ export function useGameState() {

 ## Rules

- Max 4 managers total
- Only `GameManager` holds durable state with `subscribe()`
- Other managers are side-effect handlers — they do not store persistent state
- Always call `destroy()` on cleanup (App unmount)
- Never create manager instances with `new` — always use `.getInstance()`
+- Do not add a `GameManager` unless the feature requires a real shared gameplay state owner.
+- Current managers may be imported directly until the target-state orchestrator exists.
+- Keep singleton managers limited to side-effect services or shared interaction state.
+- Always call `destroy()` on cleanup when a manager owns external resources.
+- Never create manager instances with `new` — always use `.getInstance()`.
@@ -66,21 +66,6 @@ import { RigidBody, CuboidCollider } from "@react-three/rapier";
 - `type="dynamic"` for movable objects
 - Player uses `type="dynamic"` with `lockRotations`

-## Postprocessing
-
-```tsx
-import { EffectComposer, Bloom, Vignette } from "@react-three/postprocessing";
-
-<EffectComposer>
-  <Bloom intensity={0.5} luminanceThreshold={0.9} />
-  <Vignette offset={0.3} darkness={0.5} />
-</EffectComposer>;
-```
-
- Always wrap in `<EffectComposer>`
- Keep effects minimal for performance
- Disable heavy effects on low-end devices via Debug panel
-
 ## What NOT to do

 - Do not use `new THREE.Scene()` or `new THREE.WebGLRenderer()` — R3F handles this
@@ -3,6 +3,7 @@

 *.glb filter=lfs diff=lfs merge=lfs -text
 *.gltf filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text

 # Textures
 *.png filter=lfs diff=lfs merge=lfs -text
@@ -21,4 +22,4 @@

 # Video (cinematics)
 *.mp4 filter=lfs diff=lfs merge=lfs -text
-*.webm filter=lfs diff=lfs merge=lfs -text
+*.webm filter=lfs diff=lfs merge=lfs -text
@@ -74,12 +74,12 @@ jobs:

      - name: 📏 Check bundle size
        run: |
-          # Get bundle size in KB
-          SIZE=$(du -k dist | cut -f1)
+          # Check generated app assets only; public/ model files are runtime assets copied to dist.
+          SIZE=$(du -k dist/assets | cut -f1)
          echo "Bundle size: ${SIZE}KB"

-          # Threshold: 1000KB (configurable)
-          THRESHOLD=1000
+          # Threshold: 5000KB (configurable)
+          THRESHOLD=5000

          if [ "$SIZE" -gt "$THRESHOLD" ]; then
            echo "❌ Bundle size ${SIZE}KB exceeds threshold ${THRESHOLD}KB"
@@ -1,9 +1,14 @@
 # Dependencies
 node_modules/
+.venv/
+backend/.venv/
+__pycache__/
+*.pyc

 # Build
 dist/
 dist-ssr/
+.vite/
 *.local

 # Environment
@@ -37,4 +42,4 @@ Thumbs.db

 # 3D Assets Cache (drei, GLTFJSX)
 .drei/
-.glitchdrei-cache/
+.glitchdrei-cache/
@@ -24,7 +24,6 @@ Built with React, Three.js, and Vite. Runs in the browser, no installation requi
 | [@react-three/fiber](https://docs.pmnd.rs/react-three-fiber/getting-started/introduction) |
 | [@react-three/drei](https://pmndrs.github.io/drei)                                        |
 | [@react-three/rapier](https://rapier.rs/docs/)                                            |
-| [@react-three/postprocessing](https://github.com/pmndrs/postprocessing)                   |
 | [GSAP](https://gsap.com/docs/v3/Installation/)                                            |

 ### Performance & Effects
@@ -48,75 +47,63 @@ la-fabrik/
 │   └── sounds/
 │
 └── src/
-    ├── world/                              # Single persistent 3D world
-    │   ├── World.tsx                       # Main scene composition
-    │   ├── Map.tsx                         # Base map, always mounted
+    ├── world/                              # Persistent 3D world composition
+    │   ├── World.tsx                       # Active scene composition
+    │   ├── GameMap.tsx                     # Map loading and progressive rendering
+    │   ├── GameMapCollision.tsx            # Collision-only octree source
    │   ├── Lighting.tsx                    # Ambient, directional, point lights
-    │   ├── Environment.tsx                 # HDRI, fog, sky
-    │   ├── PostFX.tsx                      # Bloom, SSAO, chromatic aberration
-    │   ├── zones/                          # Spatial zones — LOD per zone
-    │   │   ├── WorkshopZone.tsx
-    │   │   ├── PowerGridZone.tsx
-    │   │   ├── FarmZone.tsx
-    │   │   ├── SchoolZone.tsx
-    │   │   └── ResidentialZone.tsx
+    │   ├── Environment.tsx                 # Scene background / sky model
+    │   ├── GameMusic.tsx                   # Game scene music lifecycle
+    │   ├── debug/                          # Debug-only test scene
+    │   │   └── TestMap.tsx
    │   └── player/
-    │       ├── FPSController.tsx           # PointerLockControls + Rapier movement
-    │       └── Crosshair.tsx
+    │       ├── Player.tsx                  # Player rig composition
+    │       ├── PlayerCamera.tsx            # Player camera mount
+    │       └── PlayerController.tsx        # Pointer lock movement and inputs
    │
    ├── components/
-    │   ├── 3d/                             # Shared reusable 3D elements
-    │   │   └── InteractiveObject.tsx       # Raycasting + outline wrapper
+    │   ├── three/                          # Shared R3F components by domain
+    │   │   ├── gameplay/                   # Core repair gameplay prototype
+    │   │   ├── handTracking/               # R3F hand tracking debug models
+    │   │   ├── interaction/                # Trigger, grab, focus wrappers
+    │   │   ├── models/                     # GLTF model components
+    │   │   └── world/                      # Environment-specific 3D objects
    │   └── ui/                             # HTML overlays — outside Canvas
-    │       ├── NarrativeOverlay.tsx        # Floating dialogues
-    │       ├── MissionHUD.tsx              # Current objective
-    │       ├── MapHUD.tsx                  # Minimap
-    │       ├── CinematicBars.tsx           # GSAP black bars
-    │       └── LoadingScreen.tsx           # Asset progress
+    │       ├── Crosshair.tsx
+    │       ├── debug/                       # Debug-only HTML overlay panels
+    │       │   ├── DebugOverlayLayout.tsx
+    │       │   ├── GameStateDebugPanel.tsx
+    │       │   └── HandTrackingDebugPanel.tsx
+    │       ├── HandTrackingVisualizer.tsx
+    │       └── InteractPrompt.tsx
    │
-    ├── stateManager/                       # All logic, state, orchestration
-    │   ├── GameManager.ts                  # Single source of truth: phase, zone, mission
-    │   ├── CinematicManager.ts             # GSAP timelines, camera lock/unlock
-    │   ├── AudioManager.ts                 # Music, SFX, spatial audio
-    │   └── ZoneManager.ts                  # Zone detection, LOD triggers
+    ├── managers/                           # Current singleton-style services
+    │   ├── AudioManager.ts                 # Music and SFX playback
+    │   └── InteractionManager.ts           # Focus, nearby, grab state
    │
-    ├── hooks/                              # React hooks — thin wrappers on managers
-    │   ├── useGameState.ts                 # Subscribes to GameManager
-    │   ├── useZoneDetection.ts
-    │   ├── useInteraction.ts
-    │   ├── useCinematic.ts
-    │   ├── useAudio.ts
-    │   └── useLOD.ts
+    ├── hooks/                              # React hooks by domain
+    │   ├── debug/                          # Debug state and GUI folders
+    │   ├── docs/                           # Docs language context access
+    │   ├── editor/                         # Editor loading and history
+    │   ├── gameplay/                       # Repair gameplay helpers
+    │   ├── handTracking/                   # Webcam/WebSocket hand tracking
+    │   ├── interaction/                    # Interaction manager subscriptions
+    │   └── three/                          # Three.js/R3F helpers
    │
    ├── data/
-    │   ├── zones.ts                        # { id, position, radius, missionId }
-    │   ├── dialogues.ts                    # Narrative scripts, PNJ states
-    │   └── missions.ts                     # Mission definitions, steps
-    │
-    ├── shaders/
-    │   └── hologram/
-    │       ├── vertex.glsl
-    │       └── fragment.glsl
+    │   ├── interaction/                    # Interaction tuning
+    │   ├── player/                         # Player tuning
+    │   ├── gameplay/                       # Repair gameplay static config
+    │   └── world/                          # Environment and lighting config
    │
    ├── utils/
-    │   ├── EventEmitter.ts                 # Simple typed pub/sub utility
-    │   ├── Sizes.ts                        # Viewport size tracking
-    │   ├── Time.ts                         # Animation frame timing utility
-    │   └── debug/                          # Dev-only tools and scene inspection
-    │       ├── Debug.ts                    # Global lil-gui manager
-    │       ├── DebugPerf.tsx               # r3f-perf overlay mounted in Canvas
-    │       ├── isDebugEnabled.ts           # Debug query-string helper
-    │       └── scene/
-    │           ├── DebugHelpers.tsx        # Grid + axes helpers shown in debug mode
-    │           └── DebugCameraControls.tsx # Free debug camera for map inspection
-    ├── hooks/
-    │   └── debug/
-    │       ├── useCameraMode.ts
-    │       ├── useDebugFolder.ts
-    │       ├── useDebugStore.ts
-    │       └── useSceneMode.ts
-    │
-    ├── App.tsx                             # Canvas bootstrap
+    │   ├── core/                           # Logger and generic utilities
+    │   ├── debug/                          # Dev-only tools and scene inspection
+    │   ├── editor/                         # Editor-only parsing utilities
+    │   ├── map/                            # Map loading and validation
+    │   └── three/                          # Three.js helpers
+    ├── types/                              # Shared TypeScript domain types
+    ├── App.tsx                             # App bootstrap and route switch
    └── main.tsx
 ```

@@ -0,0 +1,91 @@
+# Hand Tracking Backend
+
+Remote-compatible Python backend for La-Fabrik hand tracking.
+
+The browser captures webcam frames, downsizes them, sends JPEG frames to this backend over WebSocket, and receives hand landmarks plus closed-fist state.
+
+## Setup
+
+```bash
+python3.11 -m venv backend/.venv
+source backend/.venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -r backend/requirements.txt
+python backend/download_model.py
+```
+
+## Run
+
+Run the Vite frontend and the Python backend in two separate terminals.
+
+Terminal 1:
+
+```bash
+npm run dev
+```
+
+Terminal 2:
+
+```bash
+source backend/.venv/bin/activate
+python -m backend.main
+```
+
+The WebSocket endpoint is:
+
+```txt
+ws://localhost:8000/ws
+```
+
+## Health Check
+
+```txt
+http://localhost:8000/health
+```
+
+## Message Flow
+
+Client sends a compressed frame:
+
+```json
+{
+  "type": "frame",
+  "timestamp": 1234567890,
+  "width": 320,
+  "height": 240,
+  "image": "base64-jpeg"
+}
+```
+
+Server responds with detected hands:
+
+```json
+{
+  "type": "hands",
+  "timestamp": 1234567890,
+  "hands": [
+    {
+      "x": 0.5,
+      "y": 0.3,
+      "z": 0.1,
+      "landmarks": [
+        {
+          "x": 0.48,
+          "y": 0.32,
+          "z": 0.02
+        }
+      ],
+      "handedness": "Right",
+      "isFist": true,
+      "score": 0.92
+    }
+  ]
+}
+```
+
+## Notes
+
+- The backend does not read `cv2.VideoCapture(0)`.
+- This keeps local development and production behavior aligned.
+- Each browser connection sends its own webcam frames.
+- The backend rate-limits frames per connection and drops work when a client is already being processed.
@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+from uuid import uuid4
+
+from fastapi import WebSocket
+
+
+@dataclass
+class ClientConnection:
+    id: str
+    websocket: WebSocket
+    is_processing: bool = False
+    last_frame_at: float = 0.0
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class ConnectionManager:
+    def __init__(self) -> None:
+        self._connections: dict[str, ClientConnection] = {}
+
+    @property
+    def count(self) -> int:
+        return len(self._connections)
+
+    async def connect(self, websocket: WebSocket) -> ClientConnection:
+        await websocket.accept()
+        connection = ClientConnection(id=str(uuid4()), websocket=websocket)
+        self._connections[connection.id] = connection
+        return connection
+
+    def disconnect(self, connection: ClientConnection) -> None:
+        self._connections.pop(connection.id, None)
+
+    async def send(self, connection: ClientConnection, payload: dict[str, Any]) -> None:
+        await connection.websocket.send_json(payload)
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from pathlib import Path
+from urllib.request import urlretrieve
+
+
+MODEL_URL = "https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task"
+MODEL_PATH = Path(__file__).with_name("hand_landmarker.task")
+
+
+def download_model() -> None:
+    if MODEL_PATH.exists():
+        print(f"Model already exists at {MODEL_PATH}")
+        return
+
+    print("Downloading MediaPipe Hand Landmarker model...")
+    urlretrieve(MODEL_URL, MODEL_PATH)
+    print(f"Model downloaded to {MODEL_PATH}")
+
+
+if __name__ == "__main__":
+    download_model()
@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import base64
+import math
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import cv2
+import mediapipe as mp
+import numpy as np
+from mediapipe.tasks import python
+from mediapipe.tasks.python import vision
+
+
+@dataclass(frozen=True)
+class HandData:
+    x: float
+    y: float
+    z: float
+    landmarks: list[dict[str, float]]
+    handedness: str
+    is_fist: bool
+    score: float
+
+    def to_payload(self) -> dict[str, float | str | bool | list[dict[str, float]]]:
+        return {
+            "x": self.x,
+            "y": self.y,
+            "z": self.z,
+            "landmarks": self.landmarks,
+            "handedness": self.handedness,
+            "isFist": self.is_fist,
+            "score": self.score,
+        }
+
+
+class HandTracker:
+    def __init__(self, max_hands: int = 2) -> None:
+        model_path = Path(__file__).with_name("hand_landmarker.task")
+        if not model_path.exists():
+            raise FileNotFoundError(
+                "Missing hand_landmarker.task. Run `python backend/download_model.py`.",
+            )
+
+        base_options = python.BaseOptions(model_asset_path=str(model_path))
+        options = vision.HandLandmarkerOptions(
+            base_options=base_options,
+            running_mode=vision.RunningMode.IMAGE,
+            num_hands=max_hands,
+        )
+        self._detector = vision.HandLandmarker.create_from_options(options)
+
+    def detect_from_base64_jpeg(self, image_base64: str) -> list[HandData]:
+        image_data = base64.b64decode(image_base64, validate=True)
+        image_buffer = np.frombuffer(image_data, dtype=np.uint8)
+        frame = cv2.imdecode(image_buffer, cv2.IMREAD_COLOR)
+        if frame is None:
+            raise ValueError("Invalid JPEG frame")
+
+        rgb_frame = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+        mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb_frame)
+        result = self._detector.detect(mp_image)
+        return self._to_hands(result)
+
+    def close(self) -> None:
+        self._detector.close()
+
+    def _to_hands(self, result: vision.HandLandmarkerResult) -> list[HandData]:
+        hands: list[HandData] = []
+        if not result.hand_landmarks or not result.handedness:
+            return hands
+
+        for landmarks, handedness_categories in zip(
+            result.hand_landmarks,
+            result.handedness,
+        ):
+            palm_center = self._average_points(
+                [landmarks[0], landmarks[5], landmarks[9], landmarks[13], landmarks[17]],
+            )
+            is_fist = self._is_fist(landmarks)
+            handedness = handedness_categories[0]
+
+            hands.append(
+                HandData(
+                    x=palm_center["x"],
+                    y=palm_center["y"],
+                    z=palm_center["z"],
+                    landmarks=[
+                        {"x": point.x, "y": point.y, "z": point.z}
+                        for point in landmarks
+                    ],
+                    handedness=handedness.category_name,
+                    is_fist=is_fist,
+                    score=handedness.score,
+                ),
+            )
+
+        return hands
+
+    def _is_fist(self, landmarks: list[Any]) -> bool:
+        palm_center = self._average_points(
+            [landmarks[0], landmarks[5], landmarks[9], landmarks[13], landmarks[17]],
+        )
+        palm_size = self._calculate_distance(landmarks[0], landmarks[9])
+        if palm_size <= 0:
+            return False
+
+        folded_finger_count = sum(
+            self._calculate_distance(landmarks[index], palm_center) / palm_size < 1.05
+            for index in (8, 12, 16, 20)
+        )
+
+        return folded_finger_count >= 4
+
+    def _average_points(self, points: list[Any]) -> dict[str, float]:
+        return {
+            "x": sum(point.x for point in points) / len(points),
+            "y": sum(point.y for point in points) / len(points),
+            "z": sum(point.z for point in points) / len(points),
+        }
+
+    def _calculate_distance(self, point_a: Any, point_b: Any) -> float:
+        return math.sqrt(
+            (self._get_coordinate(point_a, "x") - self._get_coordinate(point_b, "x"))
+            ** 2
+            + (self._get_coordinate(point_a, "y") - self._get_coordinate(point_b, "y"))
+            ** 2
+            + (self._get_coordinate(point_a, "z") - self._get_coordinate(point_b, "z"))
+            ** 2,
+        )
+
+    def _get_coordinate(self, point: Any, axis: str) -> float:
+        if isinstance(point, dict):
+            return point[axis]
+
+        return getattr(point, axis)
+
+
+def now_ms() -> int:
+    return time.monotonic_ns() // 1_000_000
@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import asyncio
+from contextlib import asynccontextmanager
+from typing import Any
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import JSONResponse
+
+from backend.connection_manager import ClientConnection, ConnectionManager
+from backend.hand_tracker import HandTracker, now_ms
+
+
+MAX_FRAME_BYTES = 220_000
+MIN_FRAME_INTERVAL_SECONDS = 0.08
+
+manager = ConnectionManager()
+tracker: HandTracker | None = None
+detection_lock = asyncio.Lock()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    global tracker
+    tracker = HandTracker(max_hands=2)
+    yield
+    if tracker:
+        tracker.close()
+
+
+app = FastAPI(title="La-Fabrik Hand Tracking", lifespan=lifespan)
+
+
+@app.get("/health")
+async def health() -> JSONResponse:
+    return JSONResponse(
+        {
+            "status": "ok",
+            "connections": manager.count,
+        },
+    )
+
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket) -> None:
+    connection = await manager.connect(websocket)
+    await manager.send(connection, status_payload("connected"))
+
+    try:
+        while True:
+            message = await websocket.receive_json()
+            response = await handle_message(connection, message)
+            await manager.send(connection, response)
+    except WebSocketDisconnect:
+        manager.disconnect(connection)
+    except Exception as error:
+        await manager.send(connection, error_payload(str(error)))
+        manager.disconnect(connection)
+
+
+async def handle_message(
+    connection: ClientConnection,
+    message: dict[str, Any],
+) -> dict[str, Any]:
+    if message.get("type") != "frame":
+        return error_payload("Unsupported message type")
+
+    current_time = asyncio.get_running_loop().time()
+    if current_time - connection.last_frame_at < MIN_FRAME_INTERVAL_SECONDS:
+        return status_payload("rate_limited")
+
+    if connection.is_processing:
+        return status_payload("busy")
+
+    image = message.get("image")
+    if not isinstance(image, str):
+        return error_payload("Missing image payload")
+
+    if len(image) > MAX_FRAME_BYTES:
+        return error_payload("Frame payload too large")
+
+    if tracker is None:
+        return error_payload("Hand tracker is not ready")
+
+    if detection_lock.locked():
+        return status_payload("busy")
+
+    connection.last_frame_at = current_time
+    connection.is_processing = True
+    try:
+        async with detection_lock:
+            hands = await asyncio.to_thread(tracker.detect_from_base64_jpeg, image)
+        return {
+            "type": "hands",
+            "timestamp": now_ms(),
+            "hands": [hand.to_payload() for hand in hands],
+        }
+    finally:
+        connection.is_processing = False
+
+
+def status_payload(status: str) -> dict[str, str | int]:
+    return {
+        "type": "status",
+        "timestamp": now_ms(),
+        "status": status,
+    }
+
+
+def error_payload(message: str) -> dict[str, str | int | list[Any]]:
+    return {
+        "type": "error",
+        "timestamp": now_ms(),
+        "hands": [],
+        "message": message,
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=8000)
@@ -0,0 +1,5 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.6
+opencv-python-headless==4.10.0.84
+mediapipe==0.10.20
+numpy==1.26.4
@@ -0,0 +1,50 @@
+# Animation & 3D Components
+
+This document describes the 3D components that are currently used in the runtime.
+
+## Runtime Components
+
+| Domain      | Component            | Role                                                                  |
+| ----------- | -------------------- | --------------------------------------------------------------------- |
+| Interaction | `InteractableObject` | Focus detection through distance and raycasting                       |
+| Interaction | `TriggerObject`      | Press-to-trigger interactions, optional sound, optional spawned model |
+| Interaction | `GrabbableObject`    | Physics grab and hand-tracking grab behavior                          |
+| Model       | `ExplodableModel`    | Split/reassemble a GLTF model into separated parts                    |
+| Gameplay    | `RepairCaseModel`    | Repair case lid animation, proximity float, and wobble                |
+
+## Continuous Animation
+
+Use `useFrame` for per-frame 3D behavior. Current examples:
+
+- `GrabbableObject` updates held object velocity every frame.
+- `ExplodableModel` updates split part positions every frame.
+- `RepairCaseModel` updates proximity float and rotation wobble every frame.
+- `SkyModel` follows the camera position every frame.
+
+## Timeline Animation
+
+Use GSAP only for discrete timeline-style transitions. Current example:
+
+- `RepairCaseModel` animates the case lid between open and closed rotations.
+
+## GLTF Reuse
+
+Use `useClonedObject` when a GLTF scene is reused by a component instance. It memoizes `scene.clone(true)` and keeps clone creation out of render churn.
+
+## File Structure
+
+```txt
+src/components/three/
+├── gameplay/
+│   ├── RepairCaseModel.tsx
+│   ├── RepairGame.tsx
+│   └── RepairRepairingStep.tsx
+├── interaction/
+│   ├── GrabbableObject.tsx
+│   ├── InteractableObject.tsx
+│   └── TriggerObject.tsx
+├── models/
+│   └── ExplodableModel.tsx
+└── world/
+    └── SkyModel.tsx
+```
@@ -4,44 +4,139 @@ This document describes the code that exists today in the repository.

 ## Runtime Structure

- `src/App.tsx` mounts the `Canvas`, the 3D `World`, the debug perf overlay, and the HTML overlays.
+- `src/main.tsx` mounts React.
+- `src/App.tsx` mounts the TanStack `RouterProvider`.
+- `src/router.tsx` declares the top-level routes:
+  - `/` mounts the playable 3D scene, debug perf overlay, and HTML overlays.
+  - `/editor` mounts the map editor page.
 - `src/world/World.tsx` composes the active scene, including:
  - environment and lighting
  - debug helpers and debug camera mode
  - either the map scene or the debug physics test scene
  - the player rig when the active camera mode is `player`
- `src/world/Map.tsx` loads the main map model and builds the collision octree.
- `src/world/debug/TestScene.tsx` provides a debug-oriented interaction and physics scene.
- `src/world/player/PlayerComponent.tsx` mounts the camera and controller.
- `src/world/player/PlayerController.tsx` owns pointer lock movement, jump handling, and interaction input.
+- `src/hooks/world/useWorldSceneLoading.ts` owns the production scene loading state shared by `World`, `GameMap`, and the player octree readiness.
+- `src/world/GameMap.tsx` loads map nodes from `public/map.json`, resolves available models, renders them progressively, and shows fallback cubes for missing models.
+- `src/world/GameMapCollision.tsx` builds the player collision octree from dedicated collision nodes only.
+- `src/world/GameStageContent.tsx` is wrapped in Rapier `Physics` in the production game scene so stage gameplay objects can use physics without moving the map or player to Rapier. It now mounts reusable `RepairGame` instances for `bike`, `pylone`, and `ferme` mission states.
+- `src/world/debug/TestMap.tsx` provides a debug-oriented interaction and physics map with the existing grab/trigger/model-preview objects plus separate `Bike`, `Pylone`, and `Farm` repair playground zones.
+- `src/world/player/Player.tsx` mounts the camera and controller.
+- `src/world/player/PlayerController.tsx` owns pointer lock movement, jump handling, repair-step movement locking, and interaction input.
+
+## Physics Boundaries
+
+The project currently uses two collision layers with separate responsibilities:
+
+- `GameMapCollision` builds an octree used by the player controller for map collision.
+- The player octree must be built from a small collision-only subset of map nodes. It currently uses the `terrain` node only instead of traversing the full visible map, because building an octree from all rendered props can overload the browser renderer.
+- `GameStageContent` is wrapped in Rapier `Physics` for gameplay objects such as repair triggers, cases, grabbables, and future mission-specific objects.
+- `TestMap` owns its own Rapier `Physics` playground so repair gameplay can be tuned per mission state without depending on the production map layout.
+
+Keep the player and map octree outside the Rapier provider until there is a deliberate migration plan. This avoids mixing player movement rules with object physics before the gameplay systems need it.

 ## Interaction Model

- `src/stateManager/InteractionManager.ts` is the current interaction state source.
- `src/components/3d/InteractableObject.tsx` handles focus detection through distance and raycasting.
- `src/components/3d/TriggerObject.tsx` implements trigger-style interactions.
- `src/components/3d/GrabbableObject.tsx` implements hold-and-release interactions.
- `src/hooks/useInteraction.ts` exposes the interaction snapshot to React UI.
+- `src/managers/InteractionManager.ts` is the current interaction state source.
+- `src/components/three/interaction/InteractableObject.tsx` handles focus detection through distance and raycasting.
+- `src/components/three/interaction/TriggerObject.tsx` implements trigger-style interactions.
+- `src/components/three/interaction/GrabbableObject.tsx` implements hold-and-release interactions.
+- `src/hooks/interaction/useInteraction.ts` exposes the interaction snapshot to React UI.
 - `src/components/ui/InteractPrompt.tsx` shows the `E` prompt for trigger interactions.

 ## Audio

- `src/stateManager/AudioManager.ts` currently provides pooled one-shot sound playback.
- Trigger interactions may play audio directly through `AudioManager`.
+- `src/managers/AudioManager.ts` provides pooled one-shot playback, looped music playback, category volumes, and optional stereo pan for one-shot sounds.
+- Supported audio categories are `music`, `sfx`, and `dialogue`.
+- Trigger interactions may play SFX directly through `AudioManager`.
+
+## Settings Menu
+
+- `src/managers/stores/useSettingsStore.ts` stores settings for music volume, SFX volume, dialogue volume, subtitle visibility, subtitle language, repair runtime, and menu visibility.
+- `src/components/ui/GameSettingsMenu.tsx` renders the in-game options menu.
+- `src/components/ui/GameUI.tsx` mounts the settings menu as an HTML overlay outside the canvas.
+- `Esc` opens and closes the menu, and `src/world/player/PlayerController.tsx` ignores player input while the menu is open.
+- Volume changes are forwarded to `AudioManager` by category.
+
+## Dialogues And Subtitles
+
+- `public/sounds/dialogue/dialogues.json` is the runtime dialogue manifest.
+- Dialogue audio files live under `public/sounds/dialogue/`.
+- Subtitle files live under `public/sounds/dialogue/subtitles/{fr|en}/`.
+- The current subtitle model is one SRT file per voice and language.
+- `src/types/dialogues/dialogues.ts` contains the dialogue manifest types.
+- `src/utils/dialogues/dialogueManifestValidation.ts` validates manifest shape at runtime.
+- `src/utils/dialogues/loadDialogueManifest.ts` loads the manifest and SRT cues, with French fallback when the selected language is missing.
+- `src/utils/subtitles/parseSrt.ts` parses SRT blocks and timecodes.
+- `src/utils/dialogues/playDialogue.ts` plays dialogue audio and synchronizes the active subtitle against the audio element time.
+- `src/managers/stores/useSubtitleStore.ts` stores the currently displayed subtitle cue.
+- `src/components/ui/Subtitles.tsx` renders the subtitle overlay.
+- `src/world/GameDialogues.tsx` currently triggers dialogue entries that define a `timecode`.
+- Dialogue playback is queued so multiple dialogue requests do not overlap.
+
+## Cinematics
+
+- `public/cinematics.json` is the runtime cinematic manifest.
+- `src/types/cinematics/cinematics.ts` contains cinematic manifest types.
+- `src/utils/cinematics/cinematicManifestValidation.ts` validates manifest shape at runtime.
+- `src/utils/cinematics/loadCinematicManifest.ts` loads `/cinematics.json`.
+- `src/world/GameCinematics.tsx` triggers cinematics that define a global `timecode`.
+- Cinematics use GSAP timelines to animate the active camera position and look target.
+- `dialogueCues` on a cinematic trigger dialogue IDs at times relative to the cinematic start.
+- `src/managers/stores/useGameStore.ts` exposes `isCinematicPlaying`, used to lock player input during cinematics.

 ## Debug System

 - Debug mode is enabled with `?debug`.
 - `src/utils/debug/Debug.ts` owns the `lil-gui` instance and debug controls.
 - `src/hooks/debug/useCameraMode.ts` and `src/hooks/debug/useSceneMode.ts` subscribe to debug state.
- `src/utils/debug/DebugPerf.tsx` lazily mounts `r3f-perf` in debug mode.
- `src/utils/debug/scene/DebugHelpers.tsx` mounts debug helpers.
- `src/utils/debug/scene/DebugCameraControls.tsx` mounts the free debug camera.
+- `src/components/debug/DebugPerf.tsx` lazily mounts `r3f-perf` in debug mode.
+- `src/components/ui/debug/DebugOverlayLayout.tsx` mounts the compact HTML debug overlay when enabled from `lil-gui`.
+- `src/components/ui/debug/GameStateDebugPanel.tsx` exposes current game state, main/sub-state switching, previous/next step controls, and reset.
+- `src/components/ui/debug/HandTrackingDebugPanel.tsx` shows hand tracking status, usage, loaded glove model, hand count, and fist state while hand tracking is active.
+- `src/components/ui/SceneLoadingOverlay.tsx` displays the fullscreen loading state for 3D scenes, including the production game scene, debug physics scene, and editor scene.
+- `src/components/three/handTracking/HandTrackingGlove.tsx` places the rigged `gant_l` and `gant_r` models on detected hands in the debug physics scene.
+- `src/components/debug/scene/DebugHelpers.tsx` mounts debug helpers.
+- `src/components/debug/scene/DebugCameraControls.tsx` mounts the free debug camera.
+- `lil-gui` global debug controls include camera mode, scene mode, `R3F Perf`, and `Debug Overlay`; interaction-specific controls live in the `Interaction` folder.
+
+## 3D Component Domains
+
+- `src/components/three/models/` contains reusable model helpers such as `ExplodableModel`.
+- `src/components/three/interaction/` contains reusable interaction wrappers such as `InteractableObject`, `TriggerObject`, and `GrabbableObject`.
+- `src/components/three/handTracking/` contains R3F hand tracking debug models such as the glove overlays.
+- `src/components/three/gameplay/` contains the reusable production `RepairGame` flow, repair case, repair steps, and repair prompt components.
+- `src/components/three/world/` contains reusable world/environment objects such as `SkyModel`.
+
+## Editor System
+
+- `src/pages/editor/page.tsx` is the route-level editor page for `/editor`.
+- `src/components/editor/EditorControls.tsx` renders the HTML editor control panel.
+- `src/components/editor/EditorDialogueManifestPanel.tsx` edits `public/sounds/dialogue/dialogues.json`.
+- `src/components/editor/EditorCinematicManifestPanel.tsx` edits `public/cinematics.json`.
+- `src/components/editor/EditorSrtPanel.tsx` renders the dialogue SRT editor inside the editor control panel.
+- `src/components/editor/scene/EditorScene.tsx` composes the editor canvas scene, camera controls, lights, shortcuts, and map rendering.
+- `src/components/editor/scene/EditorMap.tsx` renders map nodes, fallback cubes, selection highlighting, and transform controls.
+- `src/controls/editor/FlyController.tsx` provides player-style editor navigation.
+- `src/hooks/editor/useEditorSceneData.ts` loads scene data and handles folder upload fallback.
+- `src/hooks/editor/useEditorHistory.ts` owns editor undo and redo state.
+- `src/utils/editor/loadEditorScene.ts` handles editor-only folder upload parsing.
+- `src/utils/map/loadMapSceneData.ts` is shared by the game scene and editor to load `public/map.json` and resolve model URLs.
+- `src/types/editor/editor.ts` contains the shared `MapNode`, `SceneData`, and `TransformMode` types.
+- `src/types/gameplay/repairMission.ts` contains shared repair mission ids, mission steps, and guards used across store, config, debug UI, and gameplay components.
+
+## Map Data
+
+- `public/map.json` is expected to be a `MapNode[]`.
+- Each map node `name` maps to `public/models/{name}/model.glb` when available, with `public/models/{name}/model.gltf` kept as fallback.
+- The editor renders a fallback cube for missing models.
+- The game scene renders fallback cubes for nodes whose model cannot be resolved.
+- The game scene currently uses `terrain` as the collision source for the player octree. Additional collision nodes should be explicit lightweight collision assets, not arbitrary visible decoration models.

 ## Current Limitations

- The repository is still a prototype, not the full intended game runtime.
- `src/world/debug/TestScene.tsx` is still part of the active scene composition.
- There is no central gameplay orchestrator such as `GameManager` yet.
- Missions, zones, cinematics, and dialogue systems are not implemented.
+- The repository is a prototype, not the full intended game runtime.
+- `src/world/debug/TestMap.tsx` is part of the active scene composition.
+- There is no central gameplay orchestrator such as `GameManager`.
+- Mission state exists in Zustand and the repair flow is implemented as a prototype for the current repair missions.
+- Cinematics and dialogues exist as prototype timecode-driven systems; dialogue branching and broader gameplay orchestration are still limited.
 - The player uses octree collision and simple movement rules, not a complete gameplay physics stack.
+- Editor save-to-server is implemented as a Vite dev-server plugin, not a production backend API.
@@ -0,0 +1,234 @@
+# Editor Technical Notes
+
+This document describes the map editor that exists in the current codebase.
+
+## Purpose
+
+The editor is a React route used to inspect and adjust the `public/map.json` scene data from inside the La-Fabrik app. It shares the same `MapNode` data format as the game scene and uses React Three Fiber for rendering.
+
+## Routing
+
+- `/` renders the playable La-Fabrik scene.
+- `/editor` renders the map editor.
+- `src/App.tsx` mounts TanStack Router through `RouterProvider`.
+- `src/router.tsx` defines the `/editor` route and imports `EditorPage` from `src/pages/editor/page.tsx`.
+
+## File Structure
+
+```txt
+src/
+├── pages/
+│   └── editor/
+│       └── page.tsx
+├── components/
+│   └── editor/
+│       ├── EditorControls.tsx
+│       ├── EditorCinematicManifestPanel.tsx
+│       ├── EditorDialogueManifestPanel.tsx
+│       ├── EditorSrtPanel.tsx
+│       └── scene/
+│           ├── EditorMap.tsx
+│           └── EditorScene.tsx
+├── controls/
+│   └── editor/
+│       └── FlyController.tsx
+├── hooks/
+│   └── editor/
+│       ├── useEditorHistory.ts
+│       └── useEditorSceneData.ts
+├── types/
+│   └── editor/
+│       └── editor.ts
+└── utils/
+    ├── dialogues/
+    │   └── loadDialogueManifest.ts
+    ├── editor/
+    │   └── loadEditorScene.ts
+    ├── map/
+    │   └── loadMapSceneData.ts
+    └── subtitles/
+        └── parseSrt.ts
+```
+
+## Responsibilities
+
+`src/pages/editor/page.tsx` is the route-level composition component. It owns route-specific state such as selected object, hovered object, transform mode, and player-mode toggle.
+
+`src/hooks/editor/useEditorSceneData.ts` loads the default map data and handles folder uploads.
+
+`src/hooks/editor/useEditorHistory.ts` owns editor undo and redo history.
+
+`src/components/editor/scene/EditorScene.tsx` composes the editor canvas scene, camera controls, lights, keyboard shortcuts, and `EditorMap`.
+
+`src/components/editor/scene/EditorMap.tsx` renders map nodes, fallback cubes, selection highlighting, and transform controls.
+
+`src/components/editor/EditorControls.tsx` renders the HTML control panel outside the canvas.
+
+`src/components/editor/EditorDialogueManifestPanel.tsx` renders the dialogue manifest editor. It loads `dialogues.json`, edits dialogue entries, previews selected dialogue playback, creates missing French SRT cues, and saves the manifest through a dev-server endpoint.
+
+`src/components/editor/EditorCinematicManifestPanel.tsx` renders the cinematic manifest editor. It loads `cinematics.json`, edits camera keyframes and dialogue cues, previews selected cinematics in the editor canvas, and saves the manifest through a dev-server endpoint.
+
+`src/components/editor/EditorSrtPanel.tsx` renders the dialogue subtitle editor inside the control panel. It loads the dialogue manifest, loads one SRT file per voice/language, validates cue structure, previews dialogue audio, and can save SRT files through a dev-server endpoint.
+
+`src/controls/editor/FlyController.tsx` provides editor movement controls for player-style navigation.
+
+`src/utils/map/loadMapSceneData.ts` is shared by the game map and editor. It loads `/map.json` and resolves available `public/models/{name}/model.glb` files first, then falls back to `public/models/{name}/model.gltf`.
+
+`src/utils/editor/loadEditorScene.ts` contains editor-only upload handling for user-selected folders.
+
+## Data Format
+
+The shared editor type lives in `src/types/editor/editor.ts`.
+
+```ts
+interface MapNode {
+  name: string;
+  type: string;
+  position: [number, number, number];
+  rotation: [number, number, number];
+  scale: [number, number, number];
+}
+```
+
+`public/map.json` is expected to be a `MapNode[]`.
+
+```json
+[
+  {
+    "name": "pylone",
+    "type": "Mesh",
+    "position": [0, 5, 0],
+    "rotation": [0, 1.57, 0],
+    "scale": [1, 1, 1]
+  }
+]
+```
+
+Each node `name` maps to a model folder:
+
+```txt
+public/
+├── map.json
+└── models/
+    └── pylone/
+        └── model.glb
+```
+
+If `model.glb` and `model.gltf` are both missing, the editor renders a fallback cube so the node can still be selected and transformed.
+
+## Editor Flow
+
+1. `EditorPage` mounts on `/editor`.
+2. `useEditorSceneData` calls `loadMapSceneData()`.
+3. `loadMapSceneData()` loads `/map.json` and available model URLs.
+4. If `/map.json` is missing, the page displays a folder-upload flow.
+5. `EditorScene` renders the grid, lights, camera controls, and map nodes.
+6. `EditorControls` exposes transform mode, history actions, export, save, and selection info.
+
+## Controls
+
+- Click: select a node.
+- `Esc`: clear selection.
+- `T`: translate mode.
+- `R`: rotate mode.
+- `S`: scale mode.
+- `Ctrl+Z` or `Cmd+Z`: undo.
+- `Ctrl+Y` or `Cmd+Y`: redo.
+- `WASD`, `ZQSD`, or arrow keys: move in player-controller mode.
+- `Space`: move upward in player-controller mode.
+- `Shift`: move downward in player-controller mode.
+
+## Saving And Exporting
+
+The editor supports two output paths:
+
+- Export JSON downloads the current `MapNode[]` as `map.json`.
+- Save to Server posts the current `MapNode[]` to `/api/save-map`.
+
+The dev-only `/api/save-map` endpoint is implemented by the Vite plugin in `vite.config.ts`. It writes to `public/map.json` and enforces a maximum payload size.
+
+## Dialogue SRT Editing
+
+Dialogue subtitle editing is part of the `/editor` side panel.
+
+Runtime dialogue files are grouped under `public/sounds/dialogue/`:
+
+```txt
+public/
+└── sounds/
+    └── dialogue/
+        ├── dialogues.json
+        └── subtitles/
+            ├── fr/
+            │   ├── narrateur.srt
+            │   ├── fermier.srt
+            │   └── electricienne.srt
+            └── en/
+                └── ...
+```
+
+The current model is one SRT file per voice and language. A dialogue entry references the cue it needs through `subtitleCueIndex`; it does not own a dedicated SRT file.
+
+`EditorSrtPanel` uses:
+
+- `loadDialogueManifest()` to read `/sounds/dialogue/dialogues.json`
+- `parseSrt()` to validate local textarea content and find active cues during audio preview
+- `/api/save-srt` to write edited SRT files during local development
+- `/api/validate-dialogues` to validate the manifest, linked audio, French SRT files, and referenced cue indexes
+
+SRT timecodes are relative to the dialogue audio file being previewed, not to the global game timeline.
+
+Missing English SRT files are warnings, not errors, because runtime loading falls back to French subtitles when the selected language is not available. Keep this behavior until the English translation workflow is ready.
+
+## Dialogue Manifest Editing
+
+`EditorDialogueManifestPanel` edits `public/sounds/dialogue/dialogues.json` in memory and persists it through `/api/save-dialogues`.
+
+The panel supports:
+
+- adding a dialogue entry
+- deleting a dialogue entry
+- editing `id`, `voice`, `audio`, `subtitleCueIndex`, and optional `timecode`
+- previewing the selected dialogue through `playDialogueById()`
+- creating a missing French SRT cue through `/api/save-srt`
+
+When a dialogue is added, the editor computes the next `subtitleCueIndex` for the selected voice from the manifest. The generated SRT cue is a valid placeholder block and should be edited later in the SRT panel.
+
+`/api/save-dialogues` is implemented in `vite.config.ts`. It validates manifest shape before writing to `public/sounds/dialogue/dialogues.json`.
+
+## Cinematic Manifest Editing
+
+`EditorCinematicManifestPanel` edits `public/cinematics.json` in memory and persists it through `/api/save-cinematics`.
+
+The manifest shape is:
+
+```ts
+interface CinematicDefinition {
+  id: string;
+  timecode?: number;
+  cameraKeyframes: CinematicCameraKeyframe[];
+  dialogueCues?: CinematicDialogueCue[];
+}
+```
+
+`cameraKeyframes` are relative to the cinematic start. At least two keyframes are required and keyframe times must increase.
+
+`dialogueCues` are also relative to the cinematic start and reference dialogue IDs from `dialogues.json`. They are used by `GameCinematics` to synchronize dialogue playback with camera timelines. A dialogue synchronized this way should not also define a global `timecode` in `dialogues.json`.
+
+The editor preview sends the selected `CinematicDefinition` to `EditorScene`, where GSAP animates the current editor camera. Orbit and fly controls are disabled during preview.
+
+`/api/save-cinematics` is implemented in `vite.config.ts`. It validates manifest shape before writing to `public/cinematics.json`.
+
+## Styling
+
+Editor styles are in `src/index.css` under the `/* Editor page */` section. Classes are prefixed with `editor-` to avoid collisions with the game UI.
+
+## Known Limitations
+
+- Uploaded model object URLs are not revoked after replacement or unmount.
+- Large `map.json` files are not virtualized, culled, or LOD-managed.
+- There is no snap-to-grid, duplication, material editing, or object creation workflow.
+- Save to Server is a Vite dev-server helper, not a production backend API.
+- SRT Save is also a Vite dev-server helper, not a production backend API.
+- Dialogue and cinematic manifest saves are Vite dev-server helpers, not production backend APIs.
+- Dialogue creation still uses placeholder audio paths until real MP3 files are added.
@@ -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
@@ -0,0 +1,138 @@
+# Hand Tracking Technical Notes
+
+This document describes the hand tracking system that exists in the current codebase.
+
+## Purpose
+
+Hand tracking started as a debug-stage interaction system used to test direct 3D object manipulation with a webcam. It allows a user to close their fist to grab a nearby object and move it in 3D space without relying on the center crosshair.
+
+It is now also available to the production repair flow when a mission reaches a hand-driven step.
+
+## Runtime Flow
+
+1. The browser captures webcam frames in `src/hooks/handTracking/useRemoteHandTracking.ts`.
+2. Frames are sent to the local Python backend over WebSocket.
+3. The backend runs MediaPipe hand landmark detection.
+4. The backend returns hand data including landmarks, handedness, score, center point, and `isFist`.
+5. React stores the latest snapshot in the hand tracking provider.
+6. `GrabbableObject` reads that snapshot each frame and uses fist state plus raycasting to grab objects.
+7. `HandTrackingGlove` reads the same snapshot and places the rigged `gant_l` and `gant_r` models on the detected hands when hand tracking is active.
+
+## Activation Rules
+
+Hand tracking is intentionally gated so the webcam and backend are not used all the time.
+
+The debug activation conditions are:
+
+- debug mode is active with `?debug`
+- scene mode is `physics`
+- the player is near an interaction, is holding an object, or is hand-holding an object
+
+This keeps hand tracking active while the player is inside an interaction zone, even if the camera is not aimed directly at the object.
+
+The production repair activation conditions are:
+
+- active `mainState` is `bike`, `pylone`, or `ferme`
+- the active mission step is `inspected`, `repairing`, `reassembling`, or `done`
+
+This keeps the webcam off during `waiting`, `fragmented`, and `scanning`, then enables hand input only when the repair flow is expected to use hands.
+
+In the current production repair flow, `inspected` uses a two-fists hold gesture to advance to `fragmented`. The hold must last one second and is independent from local object interaction distance once the mission is in the correct state. Keyboard input for the same transition is handled separately by the repair case trigger, so pressing `E` requires the case to be focused through the shared interaction system.
+
+## Backend
+
+The backend lives in `backend/` and exposes:
+
+- `GET /health` for health checks
+- `WS /ws` for frame input and hand tracking output
+
+The Python process uses MediaPipe and the local model file:
+
+```txt
+backend/hand_landmarker.task
+```
+
+The backend sends normalized hand coordinates and landmarks. The frontend treats the values as screen-space inputs, then maps them into world space with the active Three.js camera.
+
+## Frontend Data Shape
+
+The shared types live in `src/types/handTracking/handTracking.ts`.
+
+```ts
+interface HandTrackingHand {
+  x: number;
+  y: number;
+  z: number;
+  landmarks: HandTrackingLandmark[];
+  handedness: string;
+  isFist: boolean;
+  score: number;
+}
+```
+
+`x` and `y` are normalized camera coordinates. `z` is a relative depth value from MediaPipe, not an absolute world-space distance.
+
+## Grab Targeting
+
+The hand grab logic lives in `src/components/three/interaction/GrabbableObject.tsx`.
+
+The object is moved toward the visual center of the hand. That center is computed from the bounding box of all landmarks:
+
+```txt
+centerX = (minX + maxX) / 2
+centerY = (minY + maxY) / 2
+```
+
+Starting a grab uses a slightly wider virtual hit zone. Instead of raycasting only from one point, the code casts several rays around the hand center:
+
+- center
+- left
+- right
+- up
+- down
+
+If any ray hits the object while the object is within `INTERACTION_RADIUS`, the object enters hand-holding mode.
+
+## Depth Handling
+
+Because MediaPipe `z` is relative, the frontend captures the starting depth when the grab begins:
+
+```txt
+initialHandZ = hand.z
+initialHoldDistance = hit.distance
+```
+
+While holding, the object distance from the camera is adjusted by the change in hand depth:
+
+```txt
+holdDistance = initialHoldDistance + (hand.z - initialHandZ) * sensitivity
+```
+
+The final hold distance is clamped between the configured grab minimum and maximum distances to avoid unstable movement.
+
+## UI And Debug
+
+The current debug UI includes:
+
+- `HandTrackingDebugPanel` inside `DebugOverlayLayout` for status, usage, loaded glove model, server state, hand count, and fist state
+- `HandTrackingVisualizer` for the SVG landmark wireframe fallback
+- `HandTrackingGlove` for the left-hand `gant_l` and right-hand `gant_r` models in the R3F scene
+- `r3f-perf` for render performance
+- `lil-gui` for scene, camera, lighting, interaction, and grab controls
+
+The hand tracking debug panel is a compact HTML grid outside the canvas. `Model loaded` displays the successfully loaded glove models. The SVG hand wireframe is only a fallback while models are loading or if a glove model fails to load.
+
+## Glove Models
+
+The current glove MVP uses `public/models/gant_l/model.gltf` and `public/models/gant_r/model.gltf`, which contain GLTF skins and armatures. Each model is positioned, oriented, and scaled from palm landmarks, then each finger bone chain is rotated toward the matching MediaPipe landmark chain.
+
+The glove models are intentionally smaller than the raw SVG overlay so they do not dominate the camera view.
+
+## Known Limitations
+
+- Production usage is currently limited to repair mission steps that explicitly need hands.
+- MediaPipe depth is relative and can be noisy.
+- The virtual hit zone is an approximation based on multiple raycasts, not a real 3D collider.
+- There is no smoothing layer for hand position or depth yet.
+- The SVG hand visualization is a fallback, not the primary display when glove models load correctly.
+- Finger bone animation is an approximate landmark-to-bone mapping; it still needs calibration for per-model twist, offsets, and smoothing.
@@ -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.
@@ -5,7 +5,7 @@ This document describes the intended medium-term architecture for the project.
 ## Relationship To The Current Code

 - `docs/technical/architecture.md` is the source of truth for what exists now.
- This document is intentionally aspirational.
+- This document describes intended direction, not implemented behavior.
 - If this document conflicts with the current implementation, the current implementation wins.

 ## Goals
@@ -40,12 +40,12 @@ This document describes the intended medium-term architecture for the project.
  - performance overlay
  - scene helpers
  - free camera and calibration controls
-  - temporary test scenes used during development
+  - debug test scenes used during development

 ### UI Layer

 - `src/components/ui/` should contain player-facing HTML overlays.
- Expected future examples:
+- Candidate examples:
  - crosshair
  - loading flow
  - mission HUD
@@ -54,7 +54,7 @@ This document describes the intended medium-term architecture for the project.
 ### Gameplay Layer

 - As the project grows, gameplay state can move toward a clearer orchestration layer.
- Likely future concerns:
+- Likely concerns:
  - missions
  - zones
  - cinematics
@@ -67,4 +67,4 @@ This document describes the intended medium-term architecture for the project.
 - Prefer direct, working code over speculative scaffolding.
 - Shared types should stay close to their domain until they have multiple real consumers.
 - Avoid creating new managers or service layers without an active runtime need.
- Debug-only runtime paths should be clearly marked and easy to remove later.
+- Debug-only runtime paths should be clearly marked and easy to remove when obsolete.
@@ -0,0 +1,194 @@
+# Zustand Game State
+
+This document explains how Zustand is used in the current project.
+
+## Why Zustand Exists Here
+
+The project needs one shared source of truth for the player's progression through the experience.
+
+The current progression is split into main states:
+
+| Main state | Role                            |
+| ---------- | ------------------------------- |
+| `intro`    | Onboarding and opening sequence |
+| `bike`     | E-bike repair sequence          |
+| `pylone`   | Power grid sequence             |
+| `ferme`    | Vertical farm sequence          |
+| `outro`    | Ending sequence                 |
+
+Each main state can also own smaller sub state, such as the current mission step, dialogue audio, or completion flags.
+
+Zustand is useful because React and React Three Fiber components can subscribe only to the state slice they need. When that slice changes, only the subscribed components re-render.
+
+## Store Location
+
+The game progression store lives here:
+
+```txt
+src/managers/stores/useGameStore.ts
+```
+
+The store is placed under `src/managers/stores/` because it belongs to the gameplay orchestration layer, not to a specific visual component.
+
+## Managers vs Store
+
+Managers are responsible for local runtime objects and imperative behavior.
+
+Examples:
+
+- `AudioManager` owns audio elements and sound pools.
+- `InteractionManager` owns transient interaction handles and input-oriented behavior.
+
+Managers can read from or write to the Zustand store when their local behavior needs to affect global gameplay progression.
+
+The Zustand store is responsible for durable global state:
+
+- current main state
+- mission sub state
+- progression flags
+- dialogue/audio references
+- state transitions
+
+Rule of thumb:
+
+- manager = runtime objects, side effects, and local imperative logic
+- store = global gameplay state that UI or world components can subscribe to
+
+## Current Shape
+
+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
+- `ferme`: farm mission state
+- `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
+"locked" |
+  "waiting" |
+  "inspected" |
+  "fragmented" |
+  "scanning" |
+  "repairing" |
+  "reassembling" |
+  "done";
+```
+
+## Reading State In Components
+
+Use selectors to read only what the component needs.
+
+```tsx
+import { useGameStore } from "@/managers/stores/useGameStore";
+
+export function Example(): React.JSX.Element {
+  const mainState = useGameStore((state) => state.mainState);
+
+  return <p>Current state: {mainState}</p>;
+}
+```
+
+This is better than reading the whole store, because the component re-renders only when `mainState` changes.
+
+## Updating State
+
+Prefer explicit actions from the store.
+
+```ts
+const advanceGameState = useGameStore((state) => state.advanceGameState);
+
+advanceGameState();
+```
+
+For development and debug tooling, direct setters also exist:
+
+```ts
+const setMainState = useGameStore((state) => state.setMainState);
+
+setMainState("bike");
+```
+
+Direct setters are useful for debug panels, but production gameplay should prefer business actions such as `advanceGameState`, `completeBike`, or `completePylone`.
+
+Mission gameplay that can target `bike`, `pylone`, or `ferme` should prefer the generic mission actions:
+
+```ts
+const setMissionStep = useGameStore((state) => state.setMissionStep);
+const completeMission = useGameStore((state) => state.completeMission);
+
+setMissionStep("bike", "inspected");
+completeMission("bike");
+```
+
+This keeps reusable gameplay components such as repair flows from duplicating mission-specific branches like `setBikeState`, `setPyloneState`, and `setFermeState`.
+
+## World Integration
+
+`src/world/GameStageContent.tsx` subscribes to `mainState` and mounts stage-specific content.
+
+For repair missions, it mounts the reusable `RepairGame` component with a mission id:
+
+```tsx
+<RepairGame mission="bike" position={[8, 0, -6]} />
+```
+
+`RepairGame` reads the active mission step from the store and writes transitions through generic actions such as `setMissionStep` and `completeMission`. Shared repair ids, mission steps, and runtime guards live in `src/types/gameplay/repairMission.ts` so static mission config does not depend on the Zustand store. The production repair flow currently supports `waiting -> inspected -> fragmented -> scanning -> repairing -> reassembling -> done -> next mission` state transitions.
+
+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
+switch (mainState) {
+  case "intro":
+    return <IntroContent />;
+  case "bike":
+    return <BikeContent />;
+  case "pylone":
+    return <PyloneContent />;
+  case "ferme":
+    return <FarmContent />;
+  case "outro":
+    return <OutroContent />;
+}
+```
+
+In React Three Fiber, mounting and unmounting JSX controls what appears in the Three.js scene. When a state-specific component disappears from JSX, React removes it from the scene.
+
+## UI Integration
+
+`src/components/ui/GameUI.tsx` groups the HTML overlays used by the playable route.
+
+Current overlays:
+
+- `DebugOverlayLayout`: debug-only overlay shown with `?debug`, including the `GameStateDebugPanel` progression panel
+- `GameStateDebugPanel`: compact debug UI for viewing and switching main/sub states, stepping backward or forward, and resetting the store
+- `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 the canvas, persistent `GameUI`, and route-level overlays.
+
+## Regression Rules
+
+- Do not store per-frame values in Zustand.
+- Use `useRef` for high-frequency mutable values such as player velocity, temporary vectors, or animation-loop data.
+- Use selectors instead of reading the whole store in components.
+- Keep gameplay transitions inside store actions when possible.
+- Keep debug-only controls behind `?debug`.
+- Add new state only when a real runtime feature needs it.
+
+## Next Steps
+
+Move repair validation into mission data once each mission has distinct broken module nodes, replacement assets, and completion events.
@@ -0,0 +1,166 @@
+# Editor User Guide
+
+The map editor is available at `/editor`. It is a browser-based tool for inspecting and adjusting the objects listed in `public/map.json`.
+
+## Purpose
+
+Use the editor when you need to move, rotate, or scale existing map objects without editing JSON by hand.
+
+The editor reads the same map data as the runtime scene:
+
+- `public/map.json` contains the object list.
+- `public/models/{name}/model.glb` contains the matching 3D model for each object name. `model.gltf` is still supported as a fallback during migration.
+- Missing models are displayed as gray fallback cubes, so incomplete maps remain editable.
+
+## Map Node Format
+
+Each entry in `public/map.json` represents one object:
+
+| Field      | Description                                       |
+| ---------- | ------------------------------------------------- |
+| `name`     | Model folder name in `public/models/{name}`       |
+| `type`     | Object category                                   |
+| `position` | Object position as `[x, y, z]`                    |
+| `rotation` | Object rotation as `[x, y, z]`, expressed radians |
+| `scale`    | Object scale as `[x, y, z]`                       |
+
+## Editing Workflow
+
+1. Open `/editor` in the local app.
+2. Click an object in the scene to select it.
+3. Choose a transform mode: translate, rotate, or scale.
+4. Drag the transform gizmo in the 3D view.
+5. Check the JSON inspector if you need exact values.
+6. Use undo or redo if the transform is not correct.
+7. Export the JSON or save it to the dev server.
+
+## Controls
+
+| Action               | Input                      |
+| -------------------- | -------------------------- |
+| Select object        | Click object               |
+| Deselect             | `Esc` or click empty space |
+| Translate mode       | `T`                        |
+| Rotate mode          | `R`                        |
+| Scale mode           | `S`                        |
+| Undo                 | `Ctrl+Z`                   |
+| Redo                 | `Ctrl+Y`                   |
+| Locked view movement | `WASD`, `ZQSD`, arrows     |
+| Move up              | `Space`                    |
+| Move down            | `Shift`                    |
+
+## View Mode
+
+The `Lock view` action switches the editor into a movement mode closer to the runtime player camera. Use it to navigate larger scenes while keeping the transform tools available.
+
+## JSON Inspector
+
+The side panel includes a raw JSON inspector:
+
+- When no object is selected, it shows the full map node list.
+- When an object is selected, it highlights the JSON lines for that object.
+
+This is useful for checking numeric transform values before saving or exporting.
+
+## Saving Changes
+
+### Export JSON
+
+`Export JSON` downloads the current map node list as `map.json`. Use this when you want to manually replace `public/map.json`.
+
+### Save To Server
+
+`Save to server` is available only during local development. It writes the edited map back to `public/map.json` through the Vite dev-server endpoint.
+
+The button is hidden in production builds because production persistence is not implemented.
+
+## Editing Dialogue Subtitles
+
+The side panel also includes dialogue tools for the dialogue manifest and SRT subtitles.
+
+### Dialogue Manifest
+
+Use the `Dialogues` panel to edit `public/sounds/dialogue/dialogues.json` without opening the JSON file manually.
+
+Available actions:
+
+- `Reload` reloads the manifest from disk.
+- `Add` creates a local dialogue entry for the current voice and assigns the next available SRT cue index.
+- `Save` writes the manifest through the local Vite dev server.
+- `Preview dialogue` plays the selected dialogue and shows subtitles in the editor overlay.
+- `Create FR SRT cue` creates the matching French SRT cue if it is missing.
+- `Delete dialogue` removes the selected entry locally.
+
+After using `Add`, save the manifest to keep the new dialogue entry. The generated SRT cue is written immediately to the French SRT file, but the dialogue manifest is still only local until `Save` is clicked.
+
+New dialogue audio paths start as placeholders such as `/sounds/dialogue/new_dialogue_24.mp3`. Replace them with real MP3 paths before validating the final asset set.
+
+### SRT Editor
+
+Use the `SRT` panel to edit one subtitle file at a time.
+
+1. Choose a voice: `narrateur`, `fermier`, or `electricienne`.
+2. Choose a language: `FR` or `EN`.
+3. Edit the SRT text directly in the textarea.
+4. Use the audio preview to check the selected dialogue.
+5. Use `Set start`, `Set end`, `-100ms`, and `+100ms` to adjust the selected cue timing against the audio.
+6. Use `Save SRT` during local development, or `Export SRT` to download the file manually.
+
+Each SRT file belongs to one voice, not one dialogue. Cue indexes must match the `subtitleCueIndex` values referenced by the dialogue manifest.
+
+## Validating Dialogue Assets
+
+Use `Validate` in the SRT panel to check the dialogue manifest and linked assets.
+
+The validation checks:
+
+- `public/sounds/dialogue/dialogues.json`
+- referenced dialogue audio files
+- French SRT files
+- subtitle cue indexes referenced by the manifest
+
+Missing English SRT files are warnings, not errors, because the runtime falls back to French subtitles. This is intentional until the English translation workflow is ready.
+
+## Editing Cinematics
+
+Use the `Cinematics` panel to edit `public/cinematics.json`.
+
+Each cinematic contains:
+
+- an `id`
+- an optional global `timecode`
+- two or more camera keyframes
+- optional dialogue cues synchronized to the cinematic timeline
+
+Camera keyframes define:
+
+- `time`: seconds relative to the cinematic start
+- `position`: camera position `[x, y, z]`
+- `target`: point the camera looks at `[x, y, z]`
+
+Dialogue cues define:
+
+- `time`: seconds relative to the cinematic start
+- `dialogueId`: an entry from `public/sounds/dialogue/dialogues.json`
+
+Available actions:
+
+- `Reload` reloads the cinematic manifest from disk.
+- `Add` creates a new local cinematic with two camera keyframes.
+- `Save` writes `public/cinematics.json` through the local Vite dev server.
+- `Preview cinematic` plays the selected camera animation in the editor canvas.
+- `Add keyframe` and `Remove` edit the camera path.
+- `Add dialogue` and `Remove` edit dialogue cues linked to the cinematic.
+- `Delete cinematic` removes the selected cinematic locally.
+
+Cinematic dialogue cues are the preferred way to synchronize a dialogue with a cinematic. Avoid also giving the same dialogue a global `timecode`, or it can be triggered twice.
+
+## Current Limitations
+
+- The editor only modifies existing nodes.
+- It does not create or delete objects.
+- It does not edit model files or textures.
+- It does not provide production persistence.
+- Fallback cubes indicate missing models; they are editor placeholders, not exported assets.
+- SRT saving is a local Vite dev-server helper, not a production backend feature.
+- Dialogue and cinematic saves are local Vite dev-server helpers, not production backend features.
@@ -5,8 +5,10 @@ This document lists features that are implemented in the current codebase.
 ## Scene

 - Fullscreen React Three Fiber scene
- Main map scene loaded from `public/models/map/model.gltf`
- Debug physics test scene selectable from the debug panel
+- Main map scene loaded from `public/map.json` and matching `public/models/{name}/model.glb` or `model.gltf` assets
+- Minimal fullscreen scene loading overlay for 3D scenes, with a global progress bar used by the production map, debug physics scene, and editor scene
+- Debug physics test scene selectable from the debug panel, including grab/trigger tests, an animated model preview, and separate repair playground zones for `bike`, `pylone`, and `ferme`
+- Rapier physics context available for production stage gameplay objects
 - Ambient and directional lighting
 - Environment background setup

@@ -16,34 +18,95 @@ This document lists features that are implemented in the current codebase.
 - Pointer lock mouse look
 - Movement with `ZQSD`
 - Jumping
- Octree-based collision against the loaded map
+- Movement lock during active repair steps, with an on-screen indicator while keeping trigger interactions available
+- Octree-based collision against dedicated map collision nodes, currently scoped to `terrain`

 ## Interactions

 - Focus detection by distance and raycast
 - Trigger interactions activated with `E`
 - Grab interactions activated with the primary mouse button
+- Physics-backed gameplay objects can be mounted inside stage content without replacing player octree collision
 - Interaction prompt shown for trigger interactions

+## Repair Gameplay
+
+- Reusable production `RepairGame` mounted for `bike`, `pylone`, and `ferme` mission states
+- Debug physics playground mounts the same reusable `RepairGame` in `Bike`, `Pylone`, and `Farm` zones so each state can be tuned with isolated positioning before moving placement into the production map
+- Repair mission config shared through `src/data/gameplay/repairMissions.ts`, including per-mission broken nodes, placeholder targets, scan timing, and reassembly timing
+- Repair-game flow supports `waiting -> inspected -> fragmented -> scanning -> repairing -> reassembling -> done -> next mission` with `.webm` prompts, repair case spawn/opening/exit, focused repair-case view, movement lock indicator during active repair, repair-case trigger interaction, case placeholder traversal, snap-to-placeholder placement, broken-part deposit feedback, `E`, two-fists hold input, exploded and inverse reassembly transitions, completion particles, per-part scan visuals, persistent red broken-part markers, centered broken-part UI videos, multiple grabbable replacement choices, correct-part install validation feedback, and mission completion
+
 ## Audio

- One-shot sound playback for trigger interactions
- Simple per-sound pooling through `AudioManager`
+- Category-based volumes for music, SFX, and dialogue
+- Looped background music playback through `AudioManager`
+- One-shot sound playback for SFX and dialogue, with simple per-sound pooling
+- Optional stereo pan for one-shot sounds
+
+## Dialogue And Subtitles
+
+- Dialogue manifest in `public/sounds/dialogue/dialogues.json`
+- Dialogue audio loaded from `public/sounds/dialogue/`
+- One SRT subtitle file per voice and language
+- French subtitle fallback when the selected language file is missing
+- Runtime subtitle overlay with speaker-specific colors
+- Timecoded dialogue trigger support for dialogue entries that define `timecode`
+- Dialogue queueing to avoid overlapping dialogue playback
+
+## Cinematics
+
+- Cinematic manifest in `public/cinematics.json`
+- Timecoded cinematic trigger support
+- GSAP camera keyframe playback
+- Optional dialogue cues synchronized to cinematic timelines
+- Player input lock while a cinematic is active
+
+## Game Options Menu
+
+- `Esc` opens and closes the in-game options menu
+- Music, SFX, and dialogue volume sliders
+- Subtitle visibility toggle
+- Subtitle language choice between French and English
+- Repair runtime choice between local JavaScript and Python server mode
+- Quit action that clears browser-accessible cookies and returns to `/`

 ## Debug Tooling

 - `?debug` query param enables the debug panel
- `lil-gui` controls for camera mode, scene mode, and interaction spheres
+- `lil-gui` controls for camera mode, scene mode, `R3F Perf`, `Debug Overlay`, and interaction tuning
+- Compact debug overlay for game state controls and hand tracking status
+- Debug game-state mission switching unlocks locked repair missions at `waiting` for faster testing
 - Debug scene helpers
 - Free debug camera
 - `r3f-perf` overlay

+## Map Editor
+
+- `/editor` route for inspecting and editing `public/map.json`
+- Automatic loading of `public/map.json` when available
+- Folder upload fallback when `map.json` is missing
+- Rendering of available `public/models/{name}/model.glb` or `model.gltf` assets
+- Fallback cubes for nodes whose model is missing
+- Object selection by click
+- Transform modes for translate, rotate, and scale
+- Keyboard shortcuts for `T`, `R`, `S`, `Esc`, undo, and redo
+- Player-style navigation mode with `WASD`, `ZQSD`, arrow keys, `Space`, and `Shift`
+- JSON export for downloading the edited map
+- Dev-server save endpoint for writing changes back to `public/map.json`
+- SRT editor for dialogue subtitles
+- Audio preview and timing helpers for SRT cues
+- Dev-server save endpoint for SRT files
+- Dialogue manifest editor with preview and assisted French SRT cue creation
+- Cinematic manifest editor with camera keyframes, dialogue cues, and canvas preview
+- Dialogue manifest validation from the editor UI
+
 ## Not Implemented Yet

- mission system
+- complete mission system
 - zone system
- cinematic system
- dialogue system
+- full cinematic system beyond current timecode prototype
+- gameplay-triggered dialogue branches beyond current prototype triggers
 - loading flow
 - minimap and mission HUD
 - full production separation between gameplay and debug scenes
+- production backend persistence for editor saves
@@ -0,0 +1,110 @@
+# Main Feature
+
+This document explains the current repair-game flow in La-Fabrik.
+
+## What It Does
+
+The main feature is a reusable repair flow mounted in the production game scene. It lets the player approach the active mission object, inspect it, fragment it, scan the broken part, install the correct replacement, validate completion, and move to the next mission state.
+
+The current user flow is:
+
+1. Enter a mission state such as `bike`, `pylone`, or `ferme`.
+2. Move close to the active repair object in the game scene.
+3. Aim at the object and press the interaction key when prompted.
+4. The mission step moves from `waiting` to `inspected`.
+5. The repair case appears near the mission object, the player movement controls are locked, and the case can float when the player approaches it.
+6. Aim at the repair case and press `E`, or hold both fists closed for one second, to move from `inspected` to `fragmented`.
+7. The mission object uses an exploded-model transition, then moves to `scanning`.
+8. The scan visual moves across the fragmented model one part at a time and keeps a red marker plus the `cassé.webm` prompt centered on any configured broken part once it has been found.
+9. In `repairing`, the case opens in a larger focused view and several grabbable replacement parts appear on the case placeholders.
+10. Move the correct replacement part close to a placeholder. When released near a placeholder, it snaps into place with a short animation.
+11. Move each scanned broken part into a compatible placeholder so the damaged parts are stored in the case.
+12. Press `E` on the green install target to move to `reassembling`. Wrong parts turn the target red and cannot finish the repair.
+13. The exploded object animates back into its assembled form with completion particles, then moves to `done` and restores player movement controls.
+14. Press `E` on the completion target. The repair case closes, returns to the ground, disappears, then `completeMission` moves to the next mission or to `outro` after `ferme`.
+
+## Why It Matters
+
+This feature validates the repair loop before a full mission system exists. It tests whether repair objects, physical proximity, model selection, audio feedback, and exploded model visualization can work together in the 3D scene.
+
+## Current Behavior
+
+In `waiting`, the active mission renders its repair object and the `interagir.webm` prompt in the game scene. The interaction uses the shared focus/raycast interaction system, so the player still gets the normal `E` prompt.
+
+When the player inspects the object, `RepairGame` writes `inspected` through the generic mission store action. The repair case then appears from the mission config with a small pop animation, player movement is locked while the repair sequence is active, and a small HTML indicator confirms that movement is temporarily unavailable. When the player is close enough, the existing case model floats upward and rotates gently to signal interactivity.
+
+In `inspected`, `RepairGame` can also move to `fragmented`. Keyboard input goes through the shared focus/raycast interaction system on the repair case, so the player must be close enough and aim at the case before pressing `E`. The hand-tracking path still uses a two-fists hold gesture and is state-based, so it does not depend on being inside a local object interaction radius.
+
+In `fragmented`, the repair object is rendered with `ExplodableModel`, then automatically advances to `scanning`. In `scanning`, the exploded model remains visible, a blue scan visual moves from part to part, and a red halo/wire marker plus the configured broken UI video stay attached to configured broken parts after the scanner reaches them. The scan can match a specific `nodeName` when mission data provides one, otherwise it falls back to the first scanned parts as placeholder broken parts. In `repairing`, the case opens in a larger focused transform, `RepairCaseModel` traverses the case GLTF for empty nodes named `placeholder_*`, several grabbable replacement parts appear on those placeholder positions, and releasing a part near a placeholder snaps it into place with a short GSAP animation. Scanned broken parts are also rendered as grabbable objects and must be deposited into a compatible placeholder before the final install target validates. If `brokenParts[].placeholderName` is configured, that broken part snaps only to the matching placeholder; otherwise it can use any available placeholder. If the current case asset has no placeholder nodes, the flow keeps using fallback focus positions. Replacement parts show green or red placement feedback after snapping, broken parts show stored feedback after deposit, and the install target gives a short blocked feedback if the player tries to validate too early. The install target only validates when the configured correct replacement part is placed and all scanned broken parts have been deposited. Player movement stays locked through `inspected`, `fragmented`, `scanning`, `repairing`, and `reassembling`, while trigger interactions remain available. In `reassembling`, the exploded model animates back into its assembled position with green completion particles before the flow moves to `done`. In `done`, player movement is available again and the repaired object remains visible with a completion target; validating closes the repair case first, then plays the case exit animation before advancing the global mission progression.
+
+The mission config now carries the mission-specific variations. `bike` repairs one cooling core, `pylone` scans and stores both the lamp relay and a damaged panel with slower scan/reassembly timing, and `ferme` scans and stores an irrigation pump plus humidity sensor with faster scan/reassembly timing.
+
+## Key Files
+
+- `src/world/GameStageContent.tsx` mounts production `RepairGame` instances for `bike`, `pylone`, and `ferme`.
+- `src/components/three/gameplay/RepairCompletionStep.tsx` renders the final repaired object, completion target, case exit animation, and mission UI prompt.
+- `src/components/three/gameplay/RepairGame.tsx` composes the reusable production repair flow.
+- `src/components/three/gameplay/RepairBrokenPartHighlight.tsx` renders the red halo and wire marker around detected broken parts during scanning.
+- `src/components/three/gameplay/RepairBrokenPartPrompt.tsx` centers the configured broken UI video on detected broken parts during scanning.
+- `src/components/three/gameplay/RepairInspectionObject.tsx` handles the `waiting` inspection interaction.
+- `src/components/three/gameplay/RepairMissionCase.tsx` renders the mission repair case after inspection.
+- `src/components/three/gameplay/RepairRepairingStep.tsx` renders grabbable replacement choices, grabbable scanned broken parts, placeholder placement markers, snap placement behavior, correct-part and broken-part placement validation, and the install trigger in `repairing`.
+- `src/components/three/gameplay/RepairReassemblyStep.tsx` renders the inverse fragmentation animation before the final completion step.
+- `src/components/three/gameplay/RepairCompletionParticles.tsx` renders the green completion particles during reassembly.
+- `src/components/three/gameplay/RepairPromptVideo.tsx` renders `.webm` prompts inside the 3D scene.
+- `src/components/three/gameplay/RepairScanSequence.tsx` keeps the exploded model visible and advances the scan from part to part.
+- `src/components/three/gameplay/RepairScanVisual.tsx` renders the scan halo and scan line around the active part.
+- `src/components/ui/RepairMovementLockIndicator.tsx` renders the HTML indicator shown while repair movement is locked.
+- `src/hooks/gameplay/useRepairFragmentationInput.ts` handles the `inspected -> fragmented` two-fists input and can optionally bind keyboard input for non-trigger flows.
+- `src/hooks/gameplay/useRepairMissionStep.ts` reads the active mission step from the game store.
+- `src/hooks/gameplay/useRepairMovementLocked.ts` exposes the shared repair movement-lock rule used by the player controller and UI indicator.
+- `src/hooks/handTracking/useBothFistsHold.ts` detects the reusable two-fists hold gesture.
+- `src/components/three/gameplay/RepairCaseModel.tsx` renders and animates the case model, and exposes `placeholder_*` transforms when the GLTF provides them.
+- `src/components/three/models/ExplodableModel.tsx` renders selectable models with split/exploded visualization.
+- `src/data/gameplay/repairCaseConfig.ts` stores repair case model, sound, and animation constants.
+- `src/data/gameplay/repairGameConfig.ts` stores repair flow timing constants.
+- `src/data/gameplay/repairMissions.ts` stores reusable repair mission config for `bike`, `pylone`, and `ferme`.
+- `src/managers/stores/useGameStore.ts` stores mission progression state and generic mission step helpers.
+- `src/types/gameplay/repairMission.ts` contains shared repair mission ids, mission steps, and guards used by the store, data config, debug UI, and gameplay components.
+
+## Runtime Requirements
+
+The production repair flow currently requires:
+
+- the active `mainState` to be one of `bike`, `pylone`, or `ferme`
+- `GameStageContent` mounted inside the game scene Rapier `Physics` boundary
+- model assets available under `public/models/`
+- sound assets available under `public/sounds/`
+
+Frontend command:
+
+```bash
+npm run dev
+```
+
+Debug URL for state switching and inspection:
+
+```txt
+http://localhost:5173/?debug
+```
+
+The debug physics scene keeps the existing grab, trigger, and animated model tests, and also exposes separate `Bike`, `Pylone`, and `Farm` repair playground zones. Use the debug game-state panel to switch `mainState`; selecting a locked repair mission in that panel opens it at `waiting`, and the matching repair zone mounts the same reusable `RepairGame` flow with that mission's model, broken parts, replacement parts, prompts, and timings.
+
+## Related Hand Tracking
+
+Hand tracking can move grabbable physics objects with webcam input in debug scenes. In the production repair flow, it is also used for the `inspected -> fragmented` transition through the two-fists hold gesture.
+
+For hand tracking, run the Python backend separately:
+
+```bash
+source backend/.venv/bin/activate
+python -m backend.main
+```
+
+## Current Limitations
+
+- The reusable production `RepairGame` currently covers `waiting -> inspected -> fragmented -> scanning -> repairing -> reassembling -> done -> next mission`.
+- Mission progression is wired through Zustand using `completeMission` at the end of each repair.
+- There is no central `GameManager` in this branch.
+- Hand tracking is available for the two-fists input and grabbable repair parts; case interaction and final installation still use the shared `E` trigger path.
+- The repair-game content is configured statically in `src/data/gameplay/`.
@@ -2,6 +2,7 @@ import js from "@eslint/js";
 import globals from "globals";
 import reactHooks from "eslint-plugin-react-hooks";
 import reactRefresh from "eslint-plugin-react-refresh";
+import prettierRecommended from "eslint-plugin-prettier/recommended";
 import tseslint from "typescript-eslint";
 import { defineConfig, globalIgnores } from "eslint/config";

@@ -20,4 +21,5 @@ export default defineConfig([
      globals: globals.browser,
    },
  },
+  prettierRecommended,
 ]);
@@ -3,6 +3,9 @@
  "private": true,
  "version": "0.0.1",
  "type": "module",
+  "engines": {
+    "node": ">=20.19.0 || >=22.12.0"
+  },
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
@@ -11,20 +14,24 @@
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "preview": "vite preview",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc -b"
  },
  "dependencies": {
+    "@mediapipe/tasks-vision": "^0.10.35",
    "@react-three/drei": "^10.7.7",
-    "@react-three/fiber": "^9.6.0",
-    "@react-three/postprocessing": "^3.0.4",
+    "@react-three/fiber": "^9.6.1",
    "@react-three/rapier": "^2.2.0",
+    "@tanstack/react-router": "^1.168.25",
    "gsap": "^3.15.0",
    "lil-gui": "^0.21.0",
+    "lucide-react": "^1.11.0",
    "r3f-perf": "^7.2.3",
    "react": "^19.2.4",
    "react-dom": "^19.2.4",
-    "three": "^0.183.2",
-    "zustand": "^5.0.13"
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "three": "0.182.0",
+    "zustand": "^5.0.12"
  },
  "devDependencies": {
    "@eslint/js": "^9.39.4",
@@ -42,5 +49,13 @@
    "typescript": "~6.0.2",
    "typescript-eslint": "^8.58.0",
    "vite": "^8.0.4"
+  },
+  "overrides": {
+    "@react-three/rapier": {
+      "@dimforge/rapier3d-compat": "0.19.1"
+    },
+    "r3f-perf": {
+      "@react-three/drei": "$@react-three/drei"
+    }
  }
 }
@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "cinematics": [
+    {
+      "id": "intro_overview",
+      "timecode": 0,
+      "dialogueCues": [
+        {
+          "time": 0,
+          "dialogueId": "narrateur_bienvenueaaltera"
+        }
+      ],
+      "cameraKeyframes": [
+        {
+          "time": 0,
+          "position": [8, 5, 12],
+          "target": [0, 2, 0]
+        },
+        {
+          "time": 4,
+          "position": [12, 4, -6],
+          "target": [10, 1.4, -8]
+        }
+      ]
+    }
+  ]
+}
--- a/Show More
+++ b/Show More