update: doc dialogue and cinematic tools

docs/technical/architecture.md

@@ -56,6 +56,18 @@ This document describes the code that exists today in the repository.
 - `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
 
@@ -83,6 +95,8 @@ This document describes the code that exists today in the repository.
 
 - `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.
@@ -105,7 +119,7 @@ This document describes the code that exists today in the repository.
 - 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`.
-- Missions, zones, and cinematics are not implemented.
+- Missions and zones are not implemented.
-- Dialogue playback exists, but queueing, branching, and gameplay-triggered dialogue orchestration are still limited.
+- Dialogue branching and gameplay-triggered 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.

docs/technical/editor.md

@@ -23,6 +23,8 @@ src/
 ├── components/
 │   └── editor/
 │       ├── EditorControls.tsx
+│       ├── EditorCinematicManifestPanel.tsx
+│       ├── EditorDialogueManifestPanel.tsx
 │       ├── EditorSrtPanel.tsx
 │       └── scene/
 │           ├── EditorMap.tsx
@@ -62,6 +64,10 @@ src/
 
 `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.
@@ -174,6 +180,45 @@ SRT timecodes are relative to the dialogue audio file being previewed, not to th
 
 Missing English SRT files are warnings because runtime loading falls back to French subtitles when the selected language is not available.
 
+## 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.
@@ -185,4 +230,5 @@ Editor styles are in `src/index.css` under the `/* Editor page */` section. Clas
 - 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.
-- The editor validates dialogue assets but does not yet create, delete, or reorder dialogue manifest entries.
+- 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.

docs/user/editor.md

@@ -76,7 +76,28 @@ The button is hidden in production builds because production persistence is not
 
 ## Editing Dialogue Subtitles
 
-The side panel also includes an SRT editor for 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`.
@@ -100,6 +121,40 @@ The validation checks:
 
 Missing English SRT files are warnings because the runtime falls back to French subtitles.
 
+## 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.
@@ -108,3 +163,4 @@ Missing English SRT files are warnings because the runtime falls back to French
 - 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.

docs/user/features.md

@@ -40,6 +40,15 @@ This document lists features that are implemented in the current codebase.
 - 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
 
@@ -75,14 +84,15 @@ This document lists features that are implemented in the current codebase.
 - 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
 - zone system
-- cinematic system
+- gameplay-triggered dialogue branches beyond current prototype triggers
-- dialogue queueing and gameplay-triggered dialogue branches
 - loading flow
 - minimap and mission HUD
 - full production separation between gameplay and debug scenes

src/data/docs/docsTranslations.ts

@@ -139,6 +139,18 @@ Ce document décrit le code réellement présent aujourd'hui dans le dépôt.
 - \`src/managers/stores/useSubtitleStore.ts\` stocke la cue de sous-titre affichée.
 - \`src/components/ui/Subtitles.tsx\` rend l'overlay de sous-titres.
 - \`src/world/GameDialogues.tsx\` déclenche actuellement les dialogues qui définissent un \`timecode\`.
+- La lecture de dialogue est mise en file pour éviter les chevauchements.
+
+## Cinématiques
+
+- \`public/cinematics.json\` est le manifeste runtime des cinématiques.
+- \`src/types/cinematics/cinematics.ts\` contient les types du manifeste.
+- \`src/utils/cinematics/cinematicManifestValidation.ts\` valide la forme du manifeste.
+- \`src/utils/cinematics/loadCinematicManifest.ts\` charge \`/cinematics.json\`.
+- \`src/world/GameCinematics.tsx\` déclenche les cinématiques qui définissent un \`timecode\` global.
+- Les cinématiques utilisent GSAP pour animer la position caméra et sa cible de regard.
+- Les \`dialogueCues\` d'une cinématique déclenchent des dialogues à des temps relatifs au début de la cinématique.
+- \`useGameStore.isCinematicPlaying\` sert à bloquer les inputs joueur pendant une cinématique.
 
 ## Système debug
 
@@ -159,8 +171,8 @@ Ce document décrit le code réellement présent aujourd'hui dans le dépôt.
 - Le dépôt est encore un prototype, pas le runtime complet du jeu.
 - \`src/world/debug/TestMap.tsx\` fait encore partie de la composition active.
 - Il n'existe pas encore d'orchestrateur gameplay central comme \`GameManager\`.
-- Les systèmes de missions, zones et cinématiques ne sont pas implémentés.
+- Les systèmes de missions et zones ne sont pas implémentés.
-- La lecture de dialogues existe, mais la file d'attente, les branches et l'orchestration par gameplay restent limitées.
+- Les branches de dialogue et l'orchestration gameplay restent limitées.
 - Le joueur utilise une collision octree et des règles simples, pas une pile physique gameplay complète.
 `;
 
@@ -438,6 +450,15 @@ Ce document liste les fonctionnalités présentes dans le code actuel.
 - Fallback vers les sous-titres français quand le fichier de langue sélectionné manque
 - Overlay de sous-titres runtime avec couleurs par speaker
 - Déclenchement timecodé pour les dialogues qui définissent \`timecode\`
+- File d'attente pour éviter les dialogues superposés
+
+## Cinématiques
+
+- Manifeste de cinématiques dans \`public/cinematics.json\`
+- Déclenchement timecodé des cinématiques
+- Lecture de keyframes caméra via GSAP
+- Dialogue cues optionnelles synchronisées avec les timelines de cinématique
+- Blocage des inputs joueur pendant une cinématique
 
 ## Menu options
 
@@ -471,13 +492,14 @@ Ce document liste les fonctionnalités présentes dans le code actuel.
 - Preview audio et outils de timing pour les cues SRT
 - Endpoint de sauvegarde dev-server pour les fichiers SRT
 - Validation du manifeste de dialogues depuis l'UI de l'éditeur
+- Éditeur de manifeste dialogues avec preview et création assistée de cue SRT FR
+- Éditeur de manifeste cinématiques avec keyframes caméra, dialogue cues et preview canvas
 
 ## Pas encore implémenté
 
 - système de missions
 - système de zones
-- système de cinématiques
+- branches de dialogues gameplay au-delà des déclencheurs prototype actuels
-- file d'attente de dialogues et branches déclenchées par gameplay
 - flow de chargement
 - minimap et HUD de mission
 - séparation complète production / debug pour les scènes gameplay
@@ -536,9 +558,26 @@ Les modèles sont chargés depuis "/public/models". Si un modèle manque, l'édi
 
 Cette action est masquée dans les builds de production car il n'existe pas encore d'API de persistance production.
 
-## Éditer les sous-titres de dialogue
+## Éditer les dialogues et sous-titres
 
-Le panneau latéral contient aussi un éditeur SRT pour les sous-titres de dialogue.
+Le panneau latéral contient aussi des outils pour les dialogues et les sous-titres.
+
+### Manifeste dialogues
+
+Le panneau \`Dialogues\` permet d'éditer \`public/sounds/dialogue/dialogues.json\` sans ouvrir le JSON à la main.
+
+- \`Reload\` recharge le manifeste depuis le disque.
+- \`Add\` crée un dialogue local pour la voix courante et assigne le prochain index SRT disponible.
+- \`Save\` écrit le manifeste via le serveur Vite local.
+- \`Preview dialogue\` joue le dialogue sélectionné avec les sous-titres dans l'éditeur.
+- \`Create FR SRT cue\` crée la cue française si elle manque.
+- \`Delete dialogue\` supprime localement l'entrée sélectionnée.
+
+Après \`Add\`, il faut cliquer \`Save\` pour conserver le dialogue dans le manifeste. La cue SRT FR est écrite directement, mais le manifeste reste local tant qu'il n'est pas sauvegardé.
+
+Les nouveaux dialogues utilisent un chemin audio placeholder comme \`/sounds/dialogue/new_dialogue_24.mp3\`. Remplace-le par un vrai MP3 avant validation finale.
+
+### Éditeur SRT
 
 1. Choisir une voix : \`narrateur\`, \`fermier\` ou \`electricienne\`.
 2. Choisir une langue : \`FR\` ou \`EN\`.
@@ -562,6 +601,31 @@ La validation vérifie :
 
 Les fichiers SRT anglais manquants sont des warnings parce que le runtime retombe sur les sous-titres français.
 
+## Éditer les cinématiques
+
+Le panneau \`Cinematics\` permet d'éditer \`public/cinematics.json\`.
+
+Chaque cinématique contient :
+
+- un \`id\`
+- un \`timecode\` global optionnel
+- au moins deux keyframes caméra
+- des dialogue cues optionnelles synchronisées avec la timeline
+
+Les keyframes caméra définissent un temps relatif, une position caméra et une cible de regard. Les dialogue cues définissent un temps relatif et un \`dialogueId\` issu de \`dialogues.json\`.
+
+Actions disponibles :
+
+- \`Reload\` recharge le manifeste.
+- \`Add\` crée une cinématique locale avec deux keyframes.
+- \`Save\` écrit \`public/cinematics.json\` via le serveur Vite local.
+- \`Preview cinematic\` joue l'animation caméra dans le canvas éditeur.
+- \`Add keyframe\` et \`Remove\` modifient le chemin caméra.
+- \`Add dialogue\` et \`Remove\` modifient les dialogues synchronisés.
+- \`Delete cinematic\` supprime localement la cinématique sélectionnée.
+
+Les dialogue cues sont la manière recommandée de synchroniser un dialogue avec une cinématique. Évite de donner aussi un \`timecode\` global au même dialogue dans \`dialogues.json\`, sinon il peut être lancé deux fois.
+
 ## Inspecteur JSON
 
 Le panneau latéral affiche le JSON brut de la carte :
@@ -578,4 +642,5 @@ Utilise-le pour vérifier les valeurs numériques exactes avant export ou sauveg
 - La sauvegarde production n'est pas implémentée.
 - Les modèles manquants s'affichent comme cubes de fallback au lieu de bloquer tout l'éditeur.
 - La sauvegarde SRT est un helper local du serveur Vite, pas une API backend de production.
+- Les sauvegardes dialogues et cinématiques sont aussi des helpers locaux du serveur Vite.
 `;