docs: audit app architecture and refresh feature documentation

docs/user/features.md

@@ -1,112 +1,244 @@
 # Implemented Features
 
-This document lists features that are implemented in the current codebase.
+This document lists the user-visible and developer-facing features implemented in the current `develop` branch.
 
-## Scene
+## Application And Routes
 
-- Fullscreen React Three Fiber scene
-- 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
+- React 19 application bootstrapped by Vite and TypeScript
+- TanStack Router route tree
+- `/` playable 3D experience
+- `/editor` local content editor
+- `/docs` in-app documentation browser
+- Lazy-loaded docs pages rendered from repository Markdown files
+
+## 3D World
+
+- Fullscreen React Three Fiber canvas
+- Production world composition in `src/world/World.tsx`
+- Environment model/background through `Environment` and `SkyModel`
+- Shared lighting setup
+- Production map loaded from `public/map.json`
+- Model resolution from `public/models/{name}/model.glb`, then `model.gltf`
+- Fallback cubes when a map node has no available model
+- Progressive scene loading overlay for game, debug physics scene, and editor
+- Stabilized game scene loading gates for map, model, collision, octree, and gameplay stage readiness
+- Game stage content mounted only after the map has loaded
+- Player, music, dialogues, and gameplay-dependent systems mounted only after gameplay is ready
 
 ## Player
 
 - Player camera mode
-- Pointer lock mouse look
-- Movement with `ZQSD`
-- Jumping
-- 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`
+- Pointer-lock mouse look
+- `ZQSD` movement
+- Jump with `Space`
+- Trigger interaction with `E`
+- Grab interaction with primary mouse button
+- Spawn reset based on scene mode
+- Input lock while the settings menu is open
+- Input lock while a cinematic is playing
+- Octree collision against dedicated map collision nodes, currently scoped to the `terrain` node
+- Repair movement-lock hook and indicator exist, but the hook currently returns `false`, so movement is not locked during repair on the current branch
 
-## Interactions
+## Physics And Collision
 
-- 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
+- Separate collision responsibility between player and gameplay objects
+- Player collision uses a Three.js capsule plus octree
+- Gameplay objects use Rapier rigid bodies and colliders
+- Production `GameStageContent` is mounted inside a Rapier `Physics` provider
+- Debug physics scene owns its own Rapier playground
+- Map collision octree is built from explicit collision nodes instead of the full visible map
+
+## Interaction System
+
+- Shared `InteractionManager` singleton for focused object, nearby object, holding state, and hand-holding state
+- React subscription through `useSyncExternalStore`
+- Distance and camera-ray focus detection in `InteractableObject`
+- Trigger interactions through `TriggerObject`
+- Grab interactions through `GrabbableObject`
+- Trigger prompt shown by `InteractPrompt`
+- Optional trigger SFX and optional spawned model support
+- Debug interaction sphere visibility through the `Interaction` lil-gui folder
+- Hand-controlled grab support for grabbable objects
+- Snap-to-target behavior after releasing grabbable objects
 
 ## 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
+- Reusable `RepairGame` mounted for `bike`, `pylone`, and `ferme`
+- Mission progression driven by Zustand and shared `MissionStep` types
+- Production repair positions:
+  - `bike` at `[8, 0, -6]`
+  - `pylone` at `[64, 0, -66]`
+  - `ferme` at `[-24, 0, 42]`
+- Debug physics repair playground zones for all three missions
+- Data-driven mission config in `src/data/gameplay/repairMissions.ts`
+- Mission flow: `locked -> waiting -> inspected -> fragmented -> scanning -> repairing -> reassembling -> done`
+- `.webm` 3D prompts for mission object, interaction, and broken parts
+- Repair object inspection
+- Repair case spawn, pop animation, proximity float, wobble, open/close lid animation, exit animation, and open/close sounds
+- Repair case placeholder traversal from GLTF nodes named `placeholder_*`
+- Fallback placeholder positions when a case asset has no placeholder nodes
+- Fragmentation through repair-case trigger or two-fists hand gesture
+- Exploded model visualization through `ExplodableModel`
+- Scan visual that steps through exploded parts
+- Broken-part detection by configured `nodeName`, with fallback to first scanned parts
+- Persistent broken-part highlight and broken-part prompt after discovery
+- Grabbable replacement part choices, including decoys
+- Grabbable broken parts that must be deposited back into the case
+- Snap-to-placeholder placement
+- Correct-part, wrong-part, and stored-part visual feedback
+- Blocked install feedback when validation is attempted too early
+- Install target that validates only when the correct replacement is placed and all broken parts are stored
+- Inverse reassembly animation
+- Completion particles
+- Completion target that closes/exits the repair case before calling `completeMission`
 
-## Audio
+## Game Progression Store
 
-- 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
+- Zustand `useGameStore` for durable gameplay progression
+- Main states: `intro`, `bike`, `pylone`, `ferme`, `outro`
+- Per-mission repair step state
+- Per-mission completion flags
+- Generic mission helpers: `setMissionStep`, `completeMission`, `advanceGameState`, `rewindGameState`, `resetGame`
+- `isCinematicPlaying` flag used by the player input lock
+- Debug game-state panel that can jump between main states and sub-states
 
-## Dialogue And Subtitles
+## Settings And UI Overlays
 
-- 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
+- `Esc` opens and closes the settings 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
+- Repair-runtime choice between JavaScript and Python modes stored in settings
 - Quit action that clears browser-accessible cookies and returns to `/`
+- Crosshair overlay
+- Interaction prompt
+- Subtitle overlay
+- Repair movement-lock indicator component, currently inactive because the lock hook returns `false`
+- Debug overlay layout
+- Scene loading overlay
+
+## Audio
+
+- Singleton `AudioManager`
+- Looped music playback
+- One-shot SFX/dialogue playback
+- Per-path one-shot audio pools
+- Category volumes for `music`, `sfx`, and `dialogue`
+- Optional stereo panning for one-shot sounds
+- Playback-rate option for one-shot sounds
+- Browser autoplay fallback for music: retry after user `pointerdown` or `keydown`
+- Game music mounted through `GameMusic`
+- Current game music path: `/sounds/musique/test.mp3`
+- Current base music volume: `0.33`
+- Repair case open/close sounds
+- Trigger-object SFX support
+
+## Dialogue And Subtitles
+
+- Runtime dialogue manifest in `public/sounds/dialogue/dialogues.json`
+- Dialogue audio under `public/sounds/dialogue/`
+- One SRT file per voice and language
+- French and English subtitle folders
+- Runtime SRT parsing
+- Subtitle cue lookup by voice, selected language, and `subtitleCueIndex`
+- French fallback when the selected language file is unavailable
+- Dialogue playback through the `dialogue` audio category
+- Runtime subtitle synchronization from audio `timeupdate`
+- Speaker-aware subtitle overlay
+- Dialogue queueing to avoid overlapping dialogue playback
+- Global timecode dialogue triggering through `GameDialogues`
+
+## Cinematics
+
+- Runtime cinematic manifest in `public/cinematics.json`
+- Cinematic manifest validation
+- GSAP camera keyframe playback
+- Camera position and look target interpolation
+- Optional dialogue cues relative to cinematic start time
+- Player input lock while a cinematic is active
+- Current world integration only mounts `GameCinematics` during `mainState === "outro"`
+
+## Hand Tracking
+
+- Optional webcam hand tracking provider around the playable scene
+- Source switch in debug GUI: local Python backend or browser-side MediaPipe
+- Backend WebSocket endpoint at `ws://localhost:8000/ws`
+- Backend health endpoint at `http://localhost:8000/health`
+- Browser-side MediaPipe through `@mediapipe/tasks-vision`
+- Lazy activation so camera/tracking is not always active
+- Production activation during repair steps that need hand input
+- Debug activation in physics mode while near, holding, or hand-holding interactions
+- Hand snapshot context for R3F and UI consumers
+- Fist detection
+- Two-fists hold gesture for repair fragmentation
+- Hand grab support for `GrabbableObject`
+- Hand-tracking debug panel with status, source/server state, hand count, fist state, and glove model status
+- SVG hand visualizer fallback
+- `gant_l` and `gant_r` R3F glove overlays when tracking is active
 
 ## Debug Tooling
 
-- `?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
+- `?debug` query param enables debug systems
+- `lil-gui` root debug folder
+- Camera mode switch between player and debug camera
+- Scene mode switch between production game and physics test scene
+- R3F perf toggle
+- Debug overlay toggle
+- Hand-tracking source switch
+- Interaction sphere debug toggle
+- Grabbable tuning controls for stiffness, throw boost, and hold distance
+- Debug helpers: grid and axes
+- Debug camera controls
+- Debug game-state panel
+- Debug hand-tracking panel
+- Physics test scene with floor, grabbable object, trigger object, repair zones, and animated model preview
+- Animated `electricienne_animated` model preview restored in the debug physics scene
 
-## Map Editor
+## Map And Content 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
+- `/editor` route
+- Automatic loading of `public/map.json`
+- Folder upload fallback when map data is not available
+- Shared `MapNode` format with runtime map loading
+- Render available map models
+- Fallback cubes for missing models
 - 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
+- Transform modes: translate, rotate, scale
+- Transform keyboard shortcuts: `T`, `R`, `S`
+- Selection lock
+- Explicit selection clear
+- Undo and redo
+- Player-style editor navigation with `WASD`, `ZQSD`, arrows, `Space`, and `Shift`
+- JSON inspector
+- JSON export
+- Dev-server save endpoint for `public/map.json`
+- Dialogue manifest editor
+- SRT subtitle editor
+- Audio preview and cue timing helpers
+- French SRT cue creation helper
+- Dialogue asset validation endpoint
+- Cinematic manifest editor
+- Cinematic camera keyframe editor
+- Cinematic dialogue cue editor
+- Cinematic preview in the editor canvas
+- Dev-server endpoints for dialogue, SRT, and cinematic saves
 
-## Not Implemented Yet
+## In-App Documentation
 
-- 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
-- full production separation between gameplay and debug scenes
-- production backend persistence for editor saves
+- `/docs` documentation layout
+- Markdown rendered through `react-markdown` and `remark-gfm`
+- Technical docs for architecture, scene runtime, repair game, interaction, editor, audio, hand tracking, Zustand, Three debugging, animation, and target architecture
+- User docs for implemented features, main feature, editor usage, and code-review preparation
+
+## Not Implemented Or Incomplete
+
+- Complete production mission manager/orchestrator
+- Full mission HUD or minimap
+- Full zone system
+- Dialogue branching
+- Production persistence for editor saves
+- Production backend for repair-game runtime selection
+- Production save/load of player progression
+- Full migration of player movement to Rapier
+- Advanced hand smoothing and calibrated glove finger animation
+- Snap-to-grid, object creation, object deletion, material editing, or model editing in the map editor