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.