feat(site): sync naming typewriter to last subtitle cue

Replace the audio "ended"-based trigger with an SRT-driven one: the
typewriter now starts (lastCue.endTime - typewriterDuration) seconds
into the dialogue so the final letter lands at the moment the
narrator finishes speaking. Char delay shortened from 110ms to 70ms
for a snappier reveal. Fallbacks: audio "ended" when no SRT, 8s
absolute timer otherwise.

README.md

@@ -26,10 +26,11 @@ The current prototype puts the player in a repair-oriented world where they prog
 ## Routes
 
 | Route      | Purpose                                             |
-| --------- | --------------------------------------------------- |
+| ---------- | --------------------------------------------------- |
 | `/`        | Playable 3D experience                              |
 | `/?debug`  | Playable scene with debug GUI and overlays          |
 | `/editor`  | Local map, dialogue, subtitle, and cinematic editor |
+| `/gallery` | 3D model gallery for browsing project assets        |
 | `/docs`    | In-app documentation index                          |
 
 ## Tech Stack
@@ -98,6 +99,7 @@ Useful local URLs:
 ```txt
 http://localhost:5173/?debug
 http://localhost:5173/editor
+http://localhost:5173/gallery
 http://localhost:5173/docs
 ```
 
@@ -110,7 +112,7 @@ npm run format:check
 npm run build
 ```
 
-Regenerate runtime map data after editing `public/map_raw.json`:
+Regenerate runtime map data after editing `public/map_raw.json` that came from the hierachy node of the model Blocking.gltf:
 
 ```bash
 npm run map:transform
@@ -150,11 +152,13 @@ WS  ws://localhost:8000/ws
 | `docs/technical/zustand.md`             | Game, settings, and subtitle stores                        |
 | `docs/technical/three-debugging.md`     | DevTools workflow for stepping into Three.js internals     |
 | `docs/technical/map-performance.md`     | Map draw-call bottlenecks and optimization notes           |
+| `docs/technical/map-lod.md`             | Runtime map LOD presets, paths, and workflow               |
 | `docs/technical/editor.md`              | Editor implementation details                              |
 | `docs/technical/animation.md`           | Animated, explodable, and reusable 3D model components     |
 | `docs/user/features.md`                 | Implemented feature inventory                              |
 | `docs/user/main-feature.md`             | User-facing repair-game walkthrough                        |
 | `docs/user/editor.md`                   | Editor user guide                                          |
+| `docs/user/gallery.md`                  | Model gallery user guide                                   |
 | `docs/code-review-preparation.md`       | French code-review preparation support                     |
 
 ## Current Caveats

docs/technical/hand-tracking.md

@@ -10,17 +10,25 @@ It is now also available to the production repair flow when a mission reaches a
 
 ## Runtime Flow
 
-1. The browser captures webcam frames in `src/hooks/handTracking/useRemoteHandTracking.ts`.
+The frontend can run hand tracking with two interchangeable sources, selected from the debug source controller:
-2. Frames are sent to the local Python backend over WebSocket.
+
-3. The backend runs MediaPipe hand landmark detection.
+- **Browser JS** (`src/hooks/handTracking/useBrowserHandTracking.ts`) runs MediaPipe `hand_landmarker.task` directly in the browser via `@mediapipe/tasks-vision`. Default for debug.
-4. The backend returns hand data including landmarks, handedness, score, center point, and `isFist`.
+- **Backend** (`src/hooks/handTracking/useRemoteHandTracking.ts`) sends webcam frames as JPEG over WebSocket to a local Python process that runs MediaPipe and returns landmarks.
-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.
+Both sources funnel into the same `HandTrackingContext` so all consumers see one shared snapshot:
-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.
+
+1. The active source captures or receives landmarks.
+2. The hook applies an EMA smoothing pass on the landmarks before publishing the snapshot.
+3. `HandTrackingProvider` exposes that snapshot through React context.
+4. `GrabbableObject` reads the snapshot each frame and uses `hand.isFist` plus raycasting to grab objects.
+5. `HandTrackingVisualizer` paints the SVG hand silhouette overlay on top of the canvas — the primary visualization.
+6. `HandTrackingGlove` (opt-in, see UI And Debug) places a rigged 3D glove on each detected hand when enabled via the debug toggle.
+
+All consumers — fist detection, grab raycasting, SVG silhouette, optional 3D glove — read the **same** landmarks from the snapshot. None of them depend on the others.
 
 ## Activation Rules
 
-Hand tracking is intentionally gated so the webcam and backend are not used all the time.
+Hand tracking is gated so the webcam and runtime are only spun up when actually needed.
 
 The debug activation conditions are:
 
@@ -28,16 +36,26 @@ The debug activation conditions are:
 - 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 `ebike`, `pylon`, or `farm`
 - 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.
+This keeps the webcam off during `waiting`, `fragmented`, and `scanning`.
 
-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.
+### Linger
+
+Once activation turns off (player walks back out of a trigger zone, or a mission step transitions away), the runtime stays alive for `HAND_TRACKING_LINGER_MS` (2000 ms) before being torn down. This gives MediaPipe enough time to finish initializing the webcam and load the model on a fresh entry — without the linger, a quick walk-through of a trigger zone never produces a detected hand.
+
+## Provider Stability
+
+`HandTrackingProvider` always renders the same JSX root (`HandTrackingRuntime`) and exposes `enabled` as a prop. Returning two different element types (`<HandTrackingContext value=IDLE>` vs `<ActiveHandTrackingProvider>`) used to be the historical shape and was the root cause of WebGL context loss: every `enabled` toggle forced React to remount the entire subtree, including the `<Canvas>`, which destroyed the WebGL renderer.
+
+The two source hooks are therefore mounted in permanence with an `enabled` flag that they early-return on. No webcam or MediaPipe resources are created while `enabled` is false.
+
+## StrictMode Resilience
+
+In development, `<StrictMode>` mounts → unmounts → remounts each effect to surface non-idempotent code. The two source hooks delay their actual `start()` call by `HAND_TRACKING_RUNTIME_START_DELAY_MS` (80 ms) and clear the timer on cleanup, so a StrictMode double-mount or a rapid `nearby` flicker never reaches `getUserMedia` twice.
 
 ## Backend
 
@@ -52,7 +70,27 @@ The Python process uses MediaPipe and the local model file:
 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.
+The frontend sends JPEG frames at `HAND_TRACKING_FRAME_WIDTH × HAND_TRACKING_FRAME_HEIGHT` (320×240) to keep WebSocket bandwidth low. The backend sends normalized hand coordinates and landmarks.
+
+## Browser MediaPipe
+
+The browser path uses `hand_landmarker.task` (float16) downloaded from Google's MediaPipe model storage. The requested webcam resolution is **640×480** (`HAND_TRACKING_BROWSER_CAMERA_WIDTH/HEIGHT`), independent from the backend's 320×240. The float16 model is more sensitive than the backend Python model and needs the higher-resolution frame to detect hands reliably.
+
+The MediaPipe delegate is currently `"GPU"`. CPU works too but is significantly slower; on a loaded scene the inference drops to ~5fps and the user feels noticeable lag during grab. MediaPipe creates its own WebGL context separate from Three.js, so there is no direct contention.
+
+A singleton instance of `HandLandmarker` is cached in `src/lib/handTracking/browserHandTracking.ts`. `releaseBrowserHandLandmarker()` is called on cleanup and on WebGL context lost.
+
+## Smoothing
+
+MediaPipe at ~10 fps produces noticeable landmark jitter that, when fed raw into the scene, makes both the glove rig and any grabbed object tremble.
+
+A simple exponential moving average is applied to every landmark before the snapshot is published:
+
+```ts
+smoothed.x = previous.x * (1 - factor) + next.x * factor;
+```
+
+The factor is `HAND_TRACKING_LANDMARK_SMOOTHING` (0.4). Hands are matched across frames by `handedness` so left/right don't bleed into each other.
 
 ## Frontend Data Shape
 
@@ -72,6 +110,17 @@ interface HandTrackingHand {
 
 `x` and `y` are normalized camera coordinates. `z` is a relative depth value from MediaPipe, not an absolute world-space distance.
 
+## Fist Detection
+
+`isFist` is computed in `src/lib/handTracking/browserHandTracking.ts` (`isFist()` function) from landmarks alone — no model, no glove. The check is:
+
+1. Palm center = mean of landmarks `[0, 5, 9, 13, 17]` (wrist + 4 MCPs).
+2. Palm size = distance from wrist (landmark 0) to middle MCP (landmark 9).
+3. For each of the four fingertip landmarks `[8, 12, 16, 20]`, check whether its distance to the palm center is less than `1.05 × palmSize`.
+4. `isFist === true` iff all four fingertips pass the check.
+
+The flag is attached to each hand on the snapshot at the publish step (`isFist: isFist(normalizedLandmarks)`) and read directly by `GrabbableObject.tsx` — the SVG visualizer and the 3D glove never participate in the gesture decision.
+
 ## Grab Targeting
 
 The hand grab logic lives in `src/components/three/interaction/GrabbableObject.tsx`.
@@ -106,24 +155,60 @@ This is less expressive than true depth-aware hand movement, but it is more stab
 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
+- `HandTrackingVisualizer` for the SVG hand silhouette overlay (always on when tracking is active)
-- `HandTrackingGlove` for the left-hand `gant_l` and right-hand `gant_r` models in the R3F scene
+- `HandTrackingFallback` for the last-resort hand silhouette overlay (legacy, see below)
+- `HandTrackingGlove` for the per-hand rigged glove models in the R3F scene, opt-in via the **Show Model** toggle
 - `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.
+### SVG Visualizer
+
+`HandTrackingVisualizer` is the primary hand visualization. It draws a light-blue hand silhouette with a crisp dark-blue outline by:
+
+1. Filling a palm polygon (landmarks `[1, 5, 9, 13, 17]` plus two synthetic wrist corners) and five finger tubes (thick rounded `stroke` along each finger's joint chain).
+2. Wrapping the whole thing in an SVG `<filter>` that uses `feMorphology` to dilate the merged alpha by 2 px and subtract the original, producing a single continuous outline around the union — no internal seams where the palm and finger tubes overlap.
+3. Shrinking every landmark toward the hand centroid by `RENDER_SCALE = 0.65` so the silhouette stays compact and doesn't dominate the screen.
+4. Overlaying the 21 raw landmarks and 21 bones as faint translucent lines and dots, so the user can still see the MediaPipe data feeding the silhouette.
+
+The SVG only displays when MediaPipe is active and the debug **Show Model** toggle is off (default). When the toggle is on, the SVG hides and `HandTrackingGlove` takes over.
+
+### Show Model Toggle
+
+The `Hand Tracking` debug folder exposes a single visualization switch:
+
+- `showHandTrackingModel = false` (default): SVG visualizer renders, 3D glove is not mounted at all.
+- `showHandTrackingModel = true`: SVG visualizer hides, 3D glove gets mounted for the detected hand(s).
+
+The 3D glove is treated as opt-in legacy because it had bugs (WebGL context loss, finger rig artefacts) and its hit/grab role was never load-bearing — grab has always read landmarks directly.
+
+### Fallback Overlay (legacy)
+
+`HandTrackingFallback` draws a simple open-hand or fist silhouette positioned on the detected wrist landmark. It renders for any hand whose glove is in the `"error"` state in `useHandTrackingGloveStatus`. Now that the glove is opt-in and rarely mounted, the fallback effectively only fires in the rare case where the user enables `showHandTrackingModel` and the glove fails to load. It is kept on disk for that edge case but is not part of the default visual path.
 
 ## 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 3D glove is **opt-in** via the `Show Model` debug toggle (see UI And Debug). It is not mounted by default; the SVG visualizer is the primary hand UI. The information below applies only when the toggle is enabled.
 
-The glove models are intentionally smaller than the raw SVG overlay so they do not dominate the camera view.
+`HandTrackingGlove` loads `public/models/gant_l/model.gltf` for both hands. The right hand applies `scale.x = -1` at the group level to mirror the mesh, so the thumb ends up on the correct side. Both hands therefore share the same rig and the same material.
+
+The historical `public/models/gant_r/model.gltf` is kept as legacy but is not loaded by the frontend — its GLB embeds three skeletons (`Hand_l`, `Hand_l_pad`, `Hand_r`) plus a `galet` mesh, which made the finger rig unreliable.
+
+The `gant_l` material is set to `alphaMode: OPAQUE` with `doubleSided: true`. The opaque mode prevents transparency sorting issues that made folded fingers disappear behind the palm; the double-sided flag covers the back faces revealed by the mirror scale on the right hand.
+
+Two additional glove variants exist on disk:
+
+- `public/models/gant_l_pad/model.gltf`
+- `public/models/gant_r_pad/model.gltf`
+
+They are intended for future swap-by-state usage but are **not yet rigged**. They cannot be animated by MediaPipe landmarks in their current form — re-exporting them from Blender with the same armature structure as `gant_l` is a prerequisite.
 
 ## Known Limitations
 
 - Production usage is currently limited to repair mission steps that explicitly need hands.
 - MediaPipe depth is relative and currently not used for stable object depth control.
 - 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 3D glove is opt-in only (see `Show Model` toggle). Default visual is the SVG silhouette.
-- The SVG hand visualization is a fallback, not the primary display when glove models load correctly.
+- `HandTrackingFallback` is legacy and effectively unused unless the glove toggle is enabled and the glove fails to load.
+- The right glove is a mirrored copy of `gant_l` rather than its own mesh; in the future a dedicated right-hand model would give a better visual.
+- The `_pad` glove variants are not rigged yet, so swap-by-state (normal ↔ pad) is not wired in.
 - Finger bone animation is an approximate landmark-to-bone mapping; it still needs calibration for per-model twist, offsets, and smoothing.

docs/technical/map-lod.md

@@ -0,0 +1,119 @@
+# Map LOD System
+
+This document describes the runtime LOD system used by the production map.
+
+## Goal
+
+The map now supports two visual versions for selected models:
+
+- the regular model in `public/models/<name>/`
+- the lighter model in `public/models/<name>-LOD/`
+
+The runtime chooses between those paths from the active graphics preset. This keeps nearby objects visually richer while reducing the cost of distant objects.
+
+## Graphics Presets
+
+Presets are configured in:
+
+```txt
+src/data/world/graphicsConfig.ts
+```
+
+Current behavior:
+
+| Preset   | Chunk load distance | Fog | LOD behavior                          |
+| -------- | ------------------: | --- | ------------------------------------- |
+| `low`    |                 10m | On  | Always use `*-LOD` models             |
+| `medium` |                 20m | On  | Always use `*-LOD` models             |
+| `high`   |                 35m | Off | Regular model up to 10m, then `*-LOD` |
+| `ultra`  |                 50m | Off | Regular model up to 20m, then `*-LOD` |
+
+The unload distance stays slightly larger than the load distance to avoid rapid mount/unmount flickering when the player stands near a boundary.
+
+## Runtime Selection
+
+LOD path mapping lives in:
+
+```txt
+src/data/world/mapLodConfig.ts
+```
+
+The main selector is `selectMapModelPathByDistance()`. It receives:
+
+- the current camera distance
+- the map model name
+- the regular model path
+- the active graphics preset
+
+It returns either the regular path or the `*-LOD` path.
+
+## Chunked Instanced Models
+
+Repeated static assets are rendered through:
+
+```txt
+src/world/map-instancing/MapInstancingSystem.tsx
+```
+
+For each visible chunk, the system checks the nearest instance in that chunk. If the nearest instance is inside the high-detail threshold, the whole chunk uses the regular model. Otherwise, it uses the `*-LOD` model.
+
+This is intentionally chunk-level LOD instead of per-instance LOD. It matches the existing chunk streaming architecture and avoids splitting every object into many tiny batches.
+
+## Single And Generated Models
+
+Single map nodes use:
+
+```txt
+src/hooks/world/useMapLodModelPath.ts
+src/world/GameMap.tsx
+```
+
+Some named map objects are rendered through dedicated generated components instead of the generic `GameMap` path. Those components must call `useMapLodModelPath()` directly.
+
+Current dedicated generated components with LOD support:
+
+```txt
+src/components/three/world/EcoleModel.tsx
+src/components/three/world/LaFabrikMapModel.tsx
+```
+
+This matters for `lafabrik`: adding `public/models/lafabrik-LOD/` is not enough by itself. The component must also be connected to `useMapLodModelPath()`.
+
+## Adding A New LOD Model
+
+To add LOD support for a model:
+
+1. Add the light model in `public/models/<name>-LOD/model.gltf`.
+2. Keep the regular model in `public/models/<name>/model.glb` or `public/models/<name>/model.gltf`.
+3. Add the mapping in `src/data/world/mapLodConfig.ts`.
+4. If the model uses a dedicated component, call `useMapLodModelPath()` in that component.
+5. Preload both paths when the component is dedicated and uses `useGLTF.preload()`.
+6. Verify the GLTF/GLB references: buffers, textures, opacity maps, and relative paths.
+
+## Current LOD Models
+
+The current explicit LOD mappings are:
+
+```txt
+ebike
+eolienne
+pylone
+boiteimmeuble
+ecole
+immeuble1
+lafabrik
+maison1
+panneauaffichage
+talkie
+```
+
+## Regression Risks
+
+The most common failure modes are:
+
+- the `*-LOD` folder exists but is missing from `mapLodConfig.ts`
+- a dedicated generated component keeps a hardcoded model path
+- GLTF references point to textures that were renamed during export
+- a model is added to LOD config but does not spawn through `GameMap` or `MapInstancingSystem`
+
+Before committing model changes, validate both the regular and LOD folders for missing GLTF refs.

docs/technical/map-performance.md

@@ -15,9 +15,9 @@ This document tracks the current map-rendering performance pass.
 The first performance bottleneck was draw calls. Some assets were exported as many small GLTF primitives even when they used only a few materials.
 
 | Model            | Instances | Meshes / primitives | Notes                                                                                |
-| ---------------- | --------: | ------------------: | ---------------------------------------------------------------- |
+| ---------------- | --------: | ------------------: | ------------------------------------------------------------------------------------ |
 | `generateur`     |         3 |                3152 | Worst draw-call offender. Needs asset-side mesh merging.                             |
-| `lafabrik`       |         4 |                  56 | Moderate draw calls, heavy 2048 texture set.                     |
+| `lafabrik`       |         4 |                 474 | High primitive count; current HD GLB has embedded geometry and no external textures. |
 | `ecole`          |         1 |                 107 | One material but many primitives; should be merged.                                  |
 | `fermeverticale` |         3 |                   1 | Geometry is fine; textures are large for the visible complexity.                     |
 
@@ -34,7 +34,7 @@ Estimated source primitive count versus runtime merged groups:
 | `generateur` |              3152 |                     8 |
 | `ecole`      |               107 |                     2 |
 | `eolienne`   |               118 |                     8 |
-| `lafabrik`   |                56 |                    14 |
+| `lafabrik`   |               474 |                   ~77 |
 
 This is a code-side safety net, not a replacement for clean asset exports. Clean GLB exports with merged meshes and fewer textures remain the preferred long-term path.
 
@@ -158,9 +158,11 @@ Current runtime values:
 
 ```txt
 chunkSize: 35
-loadRadius: 45
+low load/unload radius: 10m / 18m
-unloadRadius: 45
+medium load/unload radius: 20m / 30m
-updateInterval: 350ms
+high load/unload radius: 35m / 45m
+ultra load/unload radius: 50m / 65m
+updateInterval: 250ms
 fog near: 30
 fog far: 45
 ```
@@ -255,7 +257,7 @@ Design/export should prioritize:
 1. Produce lower-poly `buisson`, `arbre`, `sapin`, and crop assets.
 2. Add LOD or billboard variants for far vegetation.
 3. Merge `generateur` meshes from 3152 primitives to a small number of material groups.
-4. Reduce `lafabrik` texture count and downscale flat/low-detail maps.
+4. Keep `lafabrik` exports texture-light, and merge repeated material primitives where possible.
 5. Merge `ecole` primitives because it uses a single material.
 6. Prefer runtime `.glb` or compressed runtime textures when the pipeline supports it.
 

docs/technical/repair-game.md

@@ -17,8 +17,10 @@ Implemented missions:
 ## Main Files
 
 | File                                                  | Responsibility                                    |
-| ---------------------------------------------- | ------------------------------------------------- |
+| ----------------------------------------------------- | ------------------------------------------------- |
 | `src/components/three/gameplay/RepairGame.tsx`        | Orchestrates the repair step machine              |
+| `src/components/three/gameplay/RepairFocusBubble.tsx` | Dark sphere shroud + cocoon decor during focus    |
+| `src/managers/stores/useRepairFocusStore.ts`          | Global flag + center for the repair focus bubble  |
 | `src/data/gameplay/repairMissions.ts`                 | Mission-specific data                             |
 | `src/types/gameplay/repairMission.ts`                 | Mission ids, step ids, guards                     |
 | `src/managers/stores/useGameStore.ts`                 | Global progression and mission transitions        |
@@ -159,8 +161,6 @@ The repair case appears near the mission object. The player can:
 
 Both paths move to `fragmented`.
 
-`useRepairMovementLocked()` locks player movement during focused repair steps and drives the repair movement indicator.
-
 ### Fragmented
 
 File:
@@ -171,6 +171,10 @@ src/components/three/models/ExplodableModel.tsx
 
 The mission object is shown split apart. A timer then moves the mission to `scanning`.
 
+`ExplodedModel.createParts` walks the GLTF tree recursively, descending through any single mesh-bearing wrapper node (e.g. `Scene > Moto > Eclatement` for the Ebike) until it reaches a node with multiple mesh-bearing children. Those children are the natural "explosion groups" authored by the modeler. This avoids exploding raw leaf meshes in local space when the model has extra empty wrapper nodes above the intended group.
+
+When mounted, `RepairGame` applies `RepairMissionConfig.modelRotation` and `modelScale` to the fragmented model so it lines up with the source inspection model in world space (e.g. the parked Ebike using `EBIKE_WORLD_ROTATION_Y` / `EBIKE_WORLD_SCALE`).
+
 The default delay comes from:
 
 ```txt
@@ -256,6 +260,21 @@ The repaired object remains visible. The player validates the completion target,
 2. the case plays its exit animation
 3. `completeMission(mission)` advances the global game progression
 
+## Focus Bubble
+
+While the player is in `fragmented`, `scanning`, `repairing` or `reassembling`, `RepairGame` flips `useRepairFocusStore.active = true` and publishes the snapped world center of the repair model.
+
+`RepairFocusBubble` reads the store and:
+
+- renders a `BackSide` sphere (radius 1, scaled 0 → 10m) tinted `#060814` at opacity 0.92
+- grows the sphere with GSAP `expo.out` over 2.5 s when focus turns on
+- shrinks back with `expo.in` over 1.2 s when focus turns off
+- mounts a small "cocoon" decor pass inside (subtle grid floor + soft directional light + ambient) that fades in once the bubble is mostly grown
+
+`Environment.tsx` and `GameStageContent.tsx` consume the same store flag to unmount the vegetation system and the zone debug visuals while the bubble is up, so trees and gizmos do not pierce the shroud. Terrain, water, sky, clouds and grass remain visible behind the bubble.
+
+The bubble is mounted both in `GameStageContent` (production scene) and `TestMap` (physics test scene) so the behaviour matches in both contexts.
+
 ## Repair Case Details
 
 The case model implementation lives in:

docs/technical/scene-runtime.md

@@ -32,6 +32,8 @@ The loading progress in `HomePage` is monotonic:
 
 This prevents the overlay from jumping backward when nested loaders finish in a slightly different order.
 
+After the initial map boot is complete, late loading signals no longer reopen the full-screen loading overlay. Instead, `HomePage` shows the compact `AppLoadingIndicator` while the game remains visible. This is reserved for explicit runtime reload signals such as graphics preset changes, repair-state transitions, or late world loading events; chunk streaming intentionally does not drive this indicator.
+
 ## World Composition
 
 `src/world/World.tsx` is the main scene composer.
@@ -74,12 +76,31 @@ It tracks:
 - `showGameStage`: true when the map is ready enough to mount gameplay content
 - `gameplayReady`: true when map, stage, and octree are all ready
 
-The final game-scene readiness condition is:
+The game-scene readiness condition is:
 
 ```ts
 showGameStage && gameStageLoaded && octree !== null;
 ```
 
+Shadows are configured once when `Lighting` mounts (renderer `shadowMap.enabled`, sun
+`shadow.autoUpdate = true`, bias and frustum from `SHADOW_CONFIG` in
+`src/data/world/lightingConfig.ts`). The shadow map then refreshes every frame and
+follows the player camera through the sun's `target`. The earlier `SceneShadowWarmup`
+step has been removed — the visible loading overlay no longer waits for a forced
+shadow refresh because `autoUpdate` covers steady-state rendering.
+
+### Avoiding global scene remounts
+
+Heavy stage components (`GameStageContent`, `Player`, dialogues) load assets via
+`useGLTF`/`useTexture` without preload (e.g. `EbikeSpeedometer` calls `useTexture`
+when the bike mounts). To prevent any late suspension from bubbling up to the
+root `<Suspense>` boundary in `src/pages/page.tsx` and unmounting the entire
+world (which would trigger a redundant octree rebuild and shadow re-config), the
+game stage block and the spawn-player block are wrapped in their own
+`<Suspense fallback={null}>` boundaries inside `src/world/World.tsx`. Any new
+sibling that suspends late should be added inside one of these boundaries or get
+its own.
+
 The debug physics scene is ready when:
 
 ```ts

docs/technical/three-debugging.md

@@ -20,3 +20,63 @@ If DevTools still opens a bundled file, stop the dev server, clear Vite's cached
 rm -rf node_modules/.vite
 npm run dev:three-debug
 ```
+
+## Visual debug toggles
+
+The `Debug` folder of the runtime debug GUI exposes inspection toggles backed by
+`src/managers/stores/useDebugVisualsStore.ts`:
+
+- **Show Player Model** — renders the main character GLTF in front of the
+  current camera (`src/components/debug/DebugPlayerModel.tsx`). The model is
+  positioned in camera-local space so it stays visible regardless of pitch.
+- **Show Octree** — overlays the collision octree as colored line segments,
+  one wireframe per spatial cell (`src/components/debug/DebugOctreeVisualization.tsx`).
+  Cells are colored by depth. Use it to inspect collision precision around
+  doorways or passages.
+- **Octree Max Depth** — caps how deep the octree visualization recurses
+  (default 6). Increase to see leaf-level subdivisions; decrease to keep the
+  scene readable when the tree is large.
+
+The octree visualization reads the live `Octree` instance from `World`. The
+mesh uses `depthTest: false` and a high `renderOrder`, so cells stay visible
+through opaque geometry.
+
+## Shadow rendering intermittence
+
+Shadows occasionally failed to render on initial load and could disappear
+mid-session even though the `Lighting` configuration ran to completion. The
+fix has two layers:
+
+### Per-frame refresh (steady state)
+
+The sun follows the camera, so its world matrix is dirty every frame. With
+`shadow.autoUpdate` alone, three.js can skip the shadow map re-render on a
+frame where the matrix update has happened but the renderer's internal dirty
+tracking does not pick it up. To prevent that, `Lighting.useFrame` sets
+`sun.shadow.needsUpdate = true` after the per-frame matrix updates. Shadow
+config is centralized in `src/data/world/lightingConfig.ts` (`bias=0`,
+`normalBias=0`, `cameraSize=95`).
+
+### Mount-time shadow map reallocation (`useShadowMapWarmup`)
+
+The merged static map and other GLTFs mount imperatively after `Lighting`,
+so the shadow render target ends up linked to a renderer state that pre-dates
+the final scene. Materials compiled at that point bake a "no shadow map"
+permutation into their shader program and silently fail to render shadows
+until a WebGL context-restore cycle (the kind triggered by Chrome DevTools
+in `?debug` runs) reallocates everything.
+
+`src/hooks/three/useShadowMapWarmup.ts` replays that cycle programmatically
+without the cost of a full context loss. It runs a `useFrame` watchdog that
+samples the scene mesh count every 6 frames; once the count has been stable
+for ~1 s (or after a 5 s safety cap), it:
+
+1. Disposes the directional light shadow map and nulls it. three.js
+   reallocates the render target on the next render at the configured
+   `mapSize`.
+2. Marks every material's `needsUpdate = true`, forcing a shader recompile
+   that rebinds every program to the freshly created shadow sampler.
+3. Forces a single shadow pass and invalidates the renderer.
+
+The watchdog runs once per mount and adds a single traversal every 6 frames
+during the warmup window, after which it self-terminates.

docs/user/gallery.md

@@ -0,0 +1,46 @@
+# Galerie des modèles
+
+La galerie est disponible sur `/gallery`. Elle permet de parcourir les modèles 3D présents dans `public/models/` sans lancer la boucle de gameplay principale.
+
+## Objectif
+
+Cette page sert à remercier et valoriser le travail des designers du projet La Fabrik. Chaque modèle est affiché dans un canvas dédié, avec la même skybox et le même lighting que l'expérience principale.
+
+## Utilisation
+
+1. Ouvrir `/gallery`.
+2. Utiliser les flèches en bas de l'écran pour passer au modèle précédent ou suivant.
+3. Tourner autour du modèle avec la souris ou le doigt.
+4. Utiliser le bouton de réglages à droite pour ouvrir ou fermer le panneau lumière.
+5. Lire le diagnostic texture discret pour savoir si le modèle chargé semble correct côté textures.
+
+## Fonctionnement
+
+- La liste des modèles est déclarée dans `src/data/galleryModels.ts`.
+- Le viewer utilise `@react-three/fiber` et `@react-three/drei`.
+- `OrbitControls` permet de manipuler la caméra autour du modèle.
+- `Bounds` et `Center` recadrent automatiquement le modèle actif.
+- `SkyModel` réutilise la skybox du jeu, avec un matériau non éclairé uniquement dans la galerie pour éviter que certaines faces deviennent noires avec une caméra orbitale libre.
+- Les lumières reprennent les valeurs par défaut du jeu, puis peuvent être ajustées dans le panneau latéral.
+- `OrbitControls` autorise une orbite verticale complète pour inspecter le dessous des modèles.
+- Le viewer désactive les normal maps dans la preview pour limiter les coutures visibles sur certains exports découpés en plusieurs meshes.
+- Les animations GLTF présentes dans un modèle sont lancées automatiquement.
+- Un diagnostic simple inspecte les matériaux chargés pour signaler les textures absentes ou non exploitables.
+
+## Ajouter un modèle
+
+1. Ajouter le dossier du modèle dans `public/models/{nom}`.
+2. Vérifier que le modèle possède un fichier chargeable, par exemple `model.gltf`, `model.glb` ou un nom explicite comme `potager.gltf`.
+3. Ajouter une entrée dans `src/data/galleryModels.ts` avec un `id`, un `name` et un `path`.
+
+Exemple :
+
+```ts
+{ id: "nouveau-modele", name: "Nouveau modèle", path: "/models/nouveau-modele/model.gltf" }
+```
+
+## Limites connues
+
+- Le navigateur ne liste pas automatiquement les dossiers de `public/models/`, donc la liste reste déclarative.
+- Les modèles très lourds peuvent prendre du temps à charger.
+- La galerie est un viewer simple : elle ne remplace pas les outils d'inspection avancée comme Blender ou le viewer d'upload.

public/map.json

@@ -584,22 +584,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "arbre",
-                  "type": "Object3D",
-                  "position": [50.072, 2.2583, 78.7082],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "arbre",
-                      "type": "Mesh",
-                      "position": [50.072, 2.2583, 78.7082],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "arbre",
                   "type": "Object3D",
@@ -888,22 +872,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "arbre",
-                  "type": "Object3D",
-                  "position": [59.1794, 2.2557, 73.349],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "arbre",
-                      "type": "Mesh",
-                      "position": [59.1794, 2.2557, 73.349],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "arbre",
                   "type": "Object3D",
@@ -1112,22 +1080,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "arbre",
-                  "type": "Object3D",
-                  "position": [74.0452, 2.309, 59.2374],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "arbre",
-                      "type": "Mesh",
-                      "position": [74.0452, 2.309, 59.2374],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "arbre",
                   "type": "Object3D",
@@ -2754,22 +2706,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [73.7334, 1.1132, 54.1382],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [73.7334, 1.1132, 54.1382],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -3330,22 +3266,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [67.9046, 0.5562, 74.8395],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [67.9046, 0.5562, 74.8395],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -3714,22 +3634,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [73.5205, 0.3748, 75.9136],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [73.5205, 0.3748, 75.9136],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -3858,22 +3762,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [66.999, 1.7223, 48.3983],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [66.999, 1.7223, 48.3983],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -4914,22 +4802,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [61.3924, 0.4621, 82.2195],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [61.3924, 0.4621, 82.2195],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -5122,22 +4994,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [61.1082, 0.6236, 77.7642],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [61.1082, 0.6236, 77.7642],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -5170,22 +5026,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [53.1033, 1.6054, 63.3842],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [53.1033, 1.6054, 63.3842],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -5266,22 +5106,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [59.647, 1.5484, 59.429],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [59.647, 1.5484, 59.429],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -5410,22 +5234,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [69.2496, 0.6286, 71.5478],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [69.2496, 0.6286, 71.5478],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -6226,22 +6034,6 @@
                     }
                   ]
                 },
-                {
-                  "name": "buisson",
-                  "type": "Object3D",
-                  "position": [58.3126, 0.686, 77.9828],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1],
-                  "children": [
-                    {
-                      "name": "buisson",
-                      "type": "Mesh",
-                      "position": [58.3126, 0.686, 77.9828],
-                      "rotation": [0, 0, 0],
-                      "scale": [1, 1, 1]
-                    }
-                  ]
-                },
                 {
                   "name": "buisson",
                   "type": "Object3D",
@@ -37602,23 +37394,6 @@
           "rotation": [0, 0, 0],
           "scale": [1, 1, 1],
           "children": [
-            {
-              "name": "ebike",
-              "type": "Object3D",
-              "role": "group",
-              "position": [0, 0, 0],
-              "rotation": [0, 0, 0],
-              "scale": [1, 1, 1],
-              "children": [
-                {
-                  "name": "ebike",
-                  "type": "Object3D",
-                  "position": [42.2399, 4.5484, 34.6468],
-                  "rotation": [0, 0, 0],
-                  "scale": [1, 1, 1]
-                }
-              ]
-            },
             {
               "name": "zone1_residence",
               "type": "Object3D",
@@ -40477,14 +40252,14 @@
                   "name": "lafabrik",
                   "type": "Object3D",
                   "position": [59.4973, 6.2746, 64.6354],
-                  "rotation": [-3.1416, -0.7309, -3.1416],
+                  "rotation": [-3.1416, 2.4107, -3.1416],
                   "scale": [1, 2, 1],
                   "children": [
                     {
                       "name": "lafabrik",
                       "type": "Mesh",
                       "position": [59.4973, 6.2746, 64.6354],
-                      "rotation": [-3.1416, -0.7309, -3.1416],
+                      "rotation": [-3.1416, 2.4107, -3.1416],
                       "scale": [1, 2, 1]
                     }
                   ]