merge: sync develop into env manager

docs/user/editor.md

@@ -1,12 +1,18 @@
 # 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`.
+The map editor is available at `/editor`. It is a browser-based tool for editing the runtime map, cinematic manifest, dialogue manifest, and SRT subtitle files without manually jumping between JSON and subtitle files.
 
 ## Purpose
 
-Use the editor when you need to move, rotate, or scale existing map objects without editing JSON by hand.
+Use the editor when you need to:
 
-The editor reads the same map data as the runtime scene:
+- move, rotate, or scale objects from `public/map.json`
+- inspect the raw JSON generated by the editor
+- preview and edit cinematics from `public/cinematics.json`
+- create, preview, and validate dialogue entries from `public/sounds/dialogue/dialogues.json`
+- edit FR/EN SRT subtitle files per voice
+
+The map 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.
@@ -24,7 +30,18 @@ Each entry in `public/map.json` represents one object:
 | `rotation` | Object rotation as `[x, y, z]`, expressed radians |
 | `scale`    | Object scale as `[x, y, z]`                       |
 
-## Editing Workflow
+## Panel Layout
+
+The right panel is split into dropdown groups:
+
+- `Editor`: map transform tools, shortcuts, selection, view mode, JSON preview, and file actions.
+- `Cinematics`: editor for `public/cinematics.json`.
+- `Dialogues`: editor for `public/sounds/dialogue/dialogues.json`.
+- `SRT`: editor for subtitle files in `public/sounds/dialogue/subtitles/`.
+
+Only the `Editor` group is open by default. Open the other groups when you need audio or cinematic tooling.
+
+## Map Editing Workflow
 
 1. Open `/editor` in the local app.
 2. Click an object in the scene to select it.
@@ -40,6 +57,8 @@ Each entry in `public/map.json` represents one object:
 | -------------------- | -------------------------- |
 | Select object        | Click object               |
 | Deselect             | `Esc` or click empty space |
+| Lock selection       | `Lock` button in Selection |
+| Clear selection      | `X` button in Selection    |
 | Translate mode       | `T`                        |
 | Rotate mode          | `R`                        |
 | Scale mode           | `S`                        |
@@ -49,18 +68,34 @@ Each entry in `public/map.json` represents one object:
 | Move up              | `Space`                    |
 | Move down            | `Shift`                    |
 
+## Selection
+
+The `Selection` section shows the selected object name and its index in `public/map.json`.
+
+- Click an object to select it.
+- Click empty space or press `Esc` to clear the selection.
+- Use the `X` button to clear the selection explicitly.
+- Use the `Lock` button to protect the current selection while editing.
+
+When selection is locked:
+
+- clicking another object does not change the selection
+- clicking empty space does not clear the selection
+- pressing `Esc` does not clear the selection
+- the `X` button still clears the selection intentionally
+
 ## 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:
+The `JSON` section shows the raw map data that will be exported or saved:
 
 - 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.
+Use it to verify exact numeric transform values before saving or exporting. The JSON inspector is read-only; transform values are changed through the gizmo in the scene.
 
 ## Saving Changes
 
@@ -76,12 +111,27 @@ The button is hidden in production builds because production persistence is not
 
 ## Editing Dialogue Subtitles
 
-The side panel also includes dialogue tools for the dialogue manifest and SRT subtitles.
+The side panel includes two separate audio text tools:
+
+- `Dialogues` edits the dialogue manifest, which links dialogue IDs to audio files and SRT cue indexes.
+- `SRT` edits the actual subtitle text and cue timings.
+
+The important model is: one dialogue entry points to one cue inside one SRT file. The SRT file is grouped by voice and language, not by dialogue.
 
 ### Dialogue Manifest
 
 Use the `Dialogues` panel to edit `public/sounds/dialogue/dialogues.json` without opening the JSON file manually.
 
+Each dialogue entry contains:
+
+| Field              | Meaning                                                           |
+| ------------------ | ----------------------------------------------------------------- |
+| `id`               | Unique dialogue ID used by cinematics and runtime triggers        |
+| `voice`            | Voice file group: `narrateur`, `fermier`, or `electricienne`      |
+| `audio`            | Runtime audio path, usually under `/sounds/dialogue/`             |
+| `subtitleCueIndex` | Cue number inside the selected voice/language SRT file            |
+| `timecode`         | Optional global runtime trigger time, in seconds from scene start |
+
 Available actions:
 
 - `Reload` reloads the manifest from disk.
@@ -95,6 +145,19 @@ After using `Add`, save the manifest to keep the new dialogue entry. The generat
 
 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.
 
+Recommended workflow for a new dialogue:
+
+1. Open `Dialogues`.
+2. Click `Add`.
+3. Choose the correct `voice`.
+4. Replace the generated `id` with a readable stable ID.
+5. Replace the placeholder `audio` path with the real MP3 path.
+6. Check the generated `subtitleCueIndex`.
+7. Click `Create FR SRT cue` if the cue does not exist yet.
+8. Click `Save`.
+9. Open `SRT`, edit the cue text and timings, then save the SRT file.
+10. Run `Validate` from the SRT panel.
+
 ### SRT Editor
 
 Use the `SRT` panel to edit one subtitle file at a time.
@@ -108,6 +171,8 @@ Use the `SRT` panel to edit one subtitle file at a time.
 
 Each SRT file belongs to one voice, not one dialogue. Cue indexes must match the `subtitleCueIndex` values referenced by the dialogue manifest.
 
+SRT timings are relative to the dialogue audio file, not to the global game timeline and not to the cinematic timeline. For example, `00:00:01,000` means one second after that dialogue audio starts.
+
 ## Validating Dialogue Assets
 
 Use `Validate` in the SRT panel to check the dialogue manifest and linked assets.
@@ -143,6 +208,17 @@ Dialogue cues define:
 - `time`: seconds relative to the cinematic start
 - `dialogueId`: an entry from `public/sounds/dialogue/dialogues.json`
 
+Recommended workflow for a cinematic:
+
+1. Open `Cinematics`.
+2. Select an existing cinematic or click `Add`.
+3. Set a stable `id`.
+4. Add or adjust camera keyframes.
+5. Keep keyframe `time` values increasing from start to end.
+6. Add dialogue cues when a dialogue must start during the camera sequence.
+7. Click `Preview cinematic` to test the camera path in the editor canvas.
+8. Click `Save` when the manifest is correct.
+
 Available actions:
 
 - `Reload` reloads the cinematic manifest from disk.
@@ -155,6 +231,8 @@ Available actions:
 
 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.
 
+Use `dialogueCues` when the dialogue belongs to a cinematic. Use a dialogue `timecode` only for simple global scene timing outside a cinematic.
+
 ## Current Limitations
 
 - The editor only modifies existing nodes.

docs/user/features.md

@@ -6,7 +6,9 @@ This document lists features that are implemented in the current codebase.
 
 - Fullscreen React Three Fiber scene
 - Main map scene loaded from `public/map.json` and matching `public/models/{name}/model.glb` or `model.gltf` assets
-- Debug physics test scene selectable from the debug panel
+- 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,15 +18,24 @@ 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
 
 - Category-based volumes for music, SFX, and dialogue
@@ -64,6 +75,7 @@ This document lists features that are implemented in the current codebase.
 - `?debug` query param enables the debug panel
 - `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
@@ -90,8 +102,9 @@ This document lists features that are implemented in the current codebase.
 
 ## Not Implemented Yet
 
-- mission system
+- complete mission system
 - zone system
+- full cinematic system beyond current timecode prototype
 - gameplay-triggered dialogue branches beyond current prototype triggers
 - loading flow
 - minimap and mission HUD

docs/user/main-feature.md

@@ -1,50 +1,78 @@
 # Main Feature
 
-This document explains the current repair-game prototype in La-Fabrik.
+This document explains the current repair-game flow in La-Fabrik.
 
 ## What It Does
 
-The main feature is a repair interaction sandbox mounted in the debug physics scene. It lets the player approach a repair case, open it, and interact with module slots that can show selectable models and exploded-model states.
+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. Open the app with `?debug`.
-2. Switch the scene to `Physics` in the debug panel.
-3. Move close to the repair case.
-4. Press the interaction key when prompted.
-5. Watch the case open or close with sound feedback.
-6. Interact with repair module slots to cycle/select repair models.
+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 core repair fantasy 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.
+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
 
-The repair case reacts to player proximity. When the player is close enough, it floats upward and rotates gently to signal interactivity. When the player moves away, it returns to its resting transform.
+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.
 
-Interacting with the case toggles its open state. The lid animation is handled with GSAP because it is a discrete interaction animation, not a continuous per-frame loop.
+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.
 
-Repair module slots are configured from static gameplay data. They render selectable repair models and can use exploded model visualization to show parts separated from their original positions.
+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/debug/TestMap.tsx` mounts the repair-game prototype in the debug physics scene.
-- `src/components/three/gameplay/RepairGameZone.tsx` composes the repair-game zone.
-- `src/components/three/gameplay/RepairCaseObject.tsx` connects the repair case to trigger interaction and audio.
-- `src/components/three/gameplay/RepairCaseModel.tsx` renders and animates the case model.
-- `src/components/three/gameplay/RepairModuleSlot.tsx` renders repair slots and model selection behavior.
+- `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 zone and slot positions.
-- `src/data/gameplay/repairGameModelCatalog.ts` stores selectable repair models.
+- `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.
 
-## Debug Requirements
+## Runtime Requirements
 
-The repair-game prototype currently requires:
+The production repair flow currently requires:
 
-- the app opened with `?debug`
-- the debug scene set to `Physics`
+- 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/`
 
@@ -54,15 +82,17 @@ Frontend command:
 npm run dev
 ```
 
-Debug URL:
+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 is a separate debug interaction layer. It can move grabbable physics objects with webcam input, but it is not yet integrated into the repair-game mission flow.
+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:
 
@@ -73,8 +103,8 @@ python -m backend.main
 
 ## Current Limitations
 
-- It is mounted only in the debug physics scene.
-- There is no mission progression system yet.
-- There is no central `GameManager` or Zustand store in this branch.
-- Hand tracking is available as debug interaction input, not as final repair gameplay.
+- 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/`.