chore(world): add temporary shadow pipeline diagnostics

Shadows still go missing intermittently despite the per-frame
needsUpdate fix. Add temporary console logs to narrow down the cause:

- [shadow:mount]: one-shot snapshot of renderer shadow flags and a
  scene.traverse count of meshes with castShadow / receiveShadow at
  Lighting mount time.
- [shadow:tick]: every 2s during useFrame, log shadow map enabled flag,
  autoUpdate, sun.castShadow, sun intensity, shadow map texture
  presence, sun and target world positions, and renderer draw calls.

To be removed once the root cause is identified.

README.md

@@ -152,6 +152,7 @@ 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/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

@@ -14,12 +14,12 @@ 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.                     |
-| `ecole`          |         1 |                 107 | One material but many primitives; should be merged.              |
-| `fermeverticale` |         3 |                   1 | Geometry is fine; textures are large for the visible complexity. |
+| Model            | Instances | Meshes / primitives | Notes                                                                                |
+| ---------------- | --------: | ------------------: | ------------------------------------------------------------------------------------ |
+| `generateur`     |         3 |                3152 | Worst draw-call offender. Needs asset-side mesh merging.                             |
+| `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.                     |
 
 `generateur` was especially expensive because three visible instances could multiply thousands of primitives into thousands of draw calls. Instancing reduces repeated instance cost, but the source asset still needs a cleaner export.
 
@@ -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
-unloadRadius: 45
-updateInterval: 350ms
+low load/unload radius: 10m / 18m
+medium load/unload radius: 20m / 30m
+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/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.
@@ -72,22 +74,32 @@ It tracks:
 - `gameMapLoaded`: map data and visible map nodes settled
 - `gameStageLoaded`: Rapier gameplay stage mounted
 - `showGameStage`: true when the map is ready enough to mount gameplay content
-- `shadowsReady`: renderer, shadow lights, and scene matrices have been forced once after the scene is mounted
-- `gameplayReady`: true when map, stage, octree, and the shadow warmup are all ready
+- `gameplayReady`: true when map, stage, and octree are all ready
 
-The base game-scene readiness condition before the shadow warmup is:
+The game-scene readiness condition is:
 
 ```ts
 showGameStage && gameStageLoaded && octree !== null;
 ```
 
-After that condition is met, `SceneShadowWarmup` runs one final loading step:
+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.
 
-```txt
-Activation des ombres -> Ombres prêtes -> Gameplay prêt
-```
+### Avoiding global scene remounts
 
-This keeps the loading overlay visible until the renderer shadow map, shadow-casting light, and mounted scene graph have all been explicitly refreshed.
+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:
 

docs/technical/three-debugging.md

@@ -20,3 +20,54 @@ 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.
+
+Root cause: the sun follows the camera (its world matrix is dirty every frame
+via `updateMatrixWorld()` inside `Lighting.useFrame`). 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, leaving the shadow map stale or unrendered.
+
+Fix in `src/world/Lighting.tsx`: explicit `sun.shadow.needsUpdate = true` in
+two places, restoring the belt-and-suspenders pattern from `develop`:
+
+- After `configureSunShadow(...)` in the mount `useEffect`.
+- At the end of the `useFrame` block, right after `sun.updateMatrixWorld()`.
+
+Mitigations also in place:
+
+- Shadow config centralized in `src/data/world/lightingConfig.ts`
+  (`bias=0`, `normalBias=0`, `cameraSize=95`).
+- Late-suspension Suspense boundaries in `World.tsx` to prevent global scene
+  remounts that would re-run shadow setup mid-load.
+- `gl.shadowMap.needsUpdate = true` on `onCreated` and on
+  `webglcontextrestored` in `src/pages/page.tsx`.
+
+If the issue reproduces, capture `[diag]`-style logs from `useOctreeGraphNode`,
+`Lighting`, and `GameMapCollision` to confirm there is no extra configuration
+pass (which would indicate a remaining suspending hook outside the existing
+Suspense boundaries).