Update GameMapCollision.tsx

Shadows occasionally failed to render on initial load and the Fabrik
doorway sometimes blocked the player. Both issues are tracked down to
geometry that mounts after Lighting:

- Shadows: GLTFs and the merged static map mount imperatively after
  Lighting, so materials get compiled against a renderer state that
  pre-dates the final scene and bake a 'no shadow map' permutation,
  silently dropping shadows. A WebGL context-restore cycle fixes it,
  but is too invasive. New 'useShadowMapWarmup' hook replays it
  cheaply: once the scene mesh count has been stable for ~1s, it
  disposes the directional shadow map (three.js reallocates it on
  the next render) and marks every material 'needsUpdate' so shaders
  rebind to the freshly created shadow sampler.
- Doorway: the door slab + its Solidify-modifier frame (children of
  the 'Thicken' parent in the LaFabrik GLTF) sat inside the doorway
  AABB and prevented the player from walking through. Stripped from
  the collision octree alongside the existing 'porte' slab; visual
  rendering is unaffected.

Also: extract sun-relative-to-camera placement into a small helper,
remove the temporary diagnostic logs, and document the shadow warmup
in three-debugging.md.

docs/technical/three-debugging.md

@@ -44,30 +44,39 @@ 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.
+mid-session even though the `Lighting` configuration ran to completion. The
+fix has two layers:
 
-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.
+### Per-frame refresh (steady state)
 
-Fix in `src/world/Lighting.tsx`: explicit `sun.shadow.needsUpdate = true` in
-two places, restoring the belt-and-suspenders pattern from `develop`:
+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`).
 
-- After `configureSunShadow(...)` in the mount `useEffect`.
-- At the end of the `useFrame` block, right after `sun.updateMatrixWorld()`.
+### Mount-time shadow map reallocation (`useShadowMapWarmup`)
 
-Mitigations also in place:
+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.
 
-- 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`.
+`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:
 
-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).
+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.

src/components/debug/DebugOctreeVisualization.tsx

@@ -1,6 +1,10 @@
 import { useMemo } from "react";
 import { Box3, BufferAttribute, BufferGeometry } from "three";
 import type { Octree } from "three-stdlib";
+import {
+  LA_FABRIK_CENTER,
+  isInsideLaFabrikFootprint,
+} from "@/data/world/laFabrikConfig";
 import { useDebugVisualsStore } from "@/managers/stores/useDebugVisualsStore";
 
 interface DebugOctreeVisualizationProps {
@@ -18,8 +22,12 @@ interface CollectOptions {
   minDepth: number;
   maxDepth: number;
   leavesOnly: boolean;
+  fabrikOnly: boolean;
 }
 
+const FABRIK_FILTER_PADDING = 1.5;
+const FABRIK_FILTER_VERTICAL = 8;
+
 const BOX_VERTEX_INDEX_PAIRS: ReadonlyArray<readonly [number, number]> = [
   [0, 1],
   [1, 3],
@@ -35,6 +43,24 @@ const BOX_VERTEX_INDEX_PAIRS: ReadonlyArray<readonly [number, number]> = [
   [3, 7],
 ];
 
+function boxIntersectsFabrik(box: Box3): boolean {
+  if (box.max.y < LA_FABRIK_CENTER[1] - FABRIK_FILTER_VERTICAL) return false;
+  if (box.min.y > LA_FABRIK_CENTER[1] + FABRIK_FILTER_VERTICAL) return false;
+
+  // Sample box corners + center on XZ plane against the rotated fabrik footprint.
+  const samples: ReadonlyArray<readonly [number, number]> = [
+    [box.min.x, box.min.z],
+    [box.min.x, box.max.z],
+    [box.max.x, box.min.z],
+    [box.max.x, box.max.z],
+    [(box.min.x + box.max.x) * 0.5, (box.min.z + box.max.z) * 0.5],
+  ];
+  for (const [x, z] of samples) {
+    if (isInsideLaFabrikFootprint(x, z, FABRIK_FILTER_PADDING)) return true;
+  }
+  return false;
+}
+
 function collectOctreeBoxes(
   node: Octree,
   options: CollectOptions,
@@ -47,8 +73,10 @@ function collectOctreeBoxes(
   const passesDepth = depth >= options.minDepth;
   const passesLeafFilter = !options.leavesOnly || isLeaf;
   const hasTriangles = node.triangles.length > 0;
+  const passesFabrikFilter =
+    !options.fabrikOnly || boxIntersectsFabrik(node.box);
 
-  if (passesDepth && passesLeafFilter && hasTriangles) {
+  if (passesDepth && passesLeafFilter && hasTriangles && passesFabrikFilter) {
     acc.push({
       box: node.box,
       depth,
@@ -114,6 +142,7 @@ export function DebugOctreeVisualization({
   const maxDepth = useDebugVisualsStore((state) => state.octreeMaxDepth);
   const leavesOnly = useDebugVisualsStore((state) => state.octreeLeavesOnly);
   const opacity = useDebugVisualsStore((state) => state.octreeOpacity);
+  const fabrikOnly = useDebugVisualsStore((state) => state.octreeFabrikOnly);
 
   const geometry = useMemo(() => {
     if (!octree || !showOctree) return null;
@@ -121,10 +150,11 @@ export function DebugOctreeVisualization({
       minDepth,
       maxDepth,
       leavesOnly,
+      fabrikOnly,
     });
     if (boxes.length === 0) return null;
     return buildOctreeLineGeometry(boxes);
-  }, [leavesOnly, maxDepth, minDepth, octree, showOctree]);
+  }, [fabrikOnly, leavesOnly, maxDepth, minDepth, octree, showOctree]);
 
   if (!geometry) return null;
 

src/data/world/octreeCollisionConfig.ts

@@ -23,10 +23,14 @@ export const MAP_OCTREE_COLLISION_BOXES = {
 } as const satisfies Record<string, MapOctreeCollisionBox>;
 
 export const LA_FABRIK_INTERIOR_COLLISION_BOXES = [
-  {
-    center: [-6.9351, 2.278, -0.0001],
-    size: [0.2, 1.94, 3.711],
-  },
+  // NOTE: removed — this thin wall (size [0.2, 1.94, 3.71]) sat at x≈-6.93 and
+  // sealed the doorway despite the geometry having a hole there. The fabrik
+  // mesh octree already provides the surrounding wall collision, so this
+  // proxy was both redundant and bug-causing.
+  // {
+  //   center: [-6.9351, 2.278, -0.0001],
+  //   size: [0.2, 1.94, 3.711],
+  // },
   {
     center: [0.8026, 0.719, -3.639],
     size: [4.346, 1.108, 1.181],

src/hooks/debug/useDebugVisualsDebug.ts

@@ -11,6 +11,7 @@ export function useDebugVisualsDebug(): void {
       octreeMaxDepth: state.octreeMaxDepth,
       octreeLeavesOnly: state.octreeLeavesOnly,
       octreeOpacity: state.octreeOpacity,
+      octreeFabrikOnly: state.octreeFabrikOnly,
     };
 
     folder
@@ -54,5 +55,12 @@ export function useDebugVisualsDebug(): void {
       .onChange((value: number) => {
         useDebugVisualsStore.getState().setOctreeOpacity(value);
       });
+
+    folder
+      .add(controls, "octreeFabrikOnly")
+      .name("Octree Fabrik Only")
+      .onChange((value: boolean) => {
+        useDebugVisualsStore.getState().setOctreeFabrikOnly(value);
+      });
   });
 }

src/hooks/three/useOctreeGraphNode.ts

@@ -1,6 +1,6 @@
 import { useEffect, useRef } from "react";
 import type { RefObject } from "react";
-import type { Object3D } from "three";
+import { type Object3D } from "three";
 import { Octree } from "three-stdlib";
 import type { OctreeReadyHandler } from "@/types/three/three";
 

src/hooks/three/useShadowMapWarmup.ts

@@ -0,0 +1,105 @@
+import { useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import {
+  Material,
+  Mesh,
+  type DirectionalLight,
+  type Scene,
+  type WebGLRenderer,
+} from "three";
+
+interface UseShadowMapWarmupOptions {
+  /** Light whose shadow map should be reallocated once the scene stabilizes. */
+  light: React.RefObject<DirectionalLight | null>;
+  scene: Scene;
+  gl: WebGLRenderer;
+  invalidate: () => void;
+  /** Frames the mesh count must remain unchanged to consider the scene stable. */
+  stableFramesThreshold?: number;
+  /** Hard cap on how long we keep watching, in frames (~5s @60fps). */
+  safetyCapFrames?: number;
+  /** Sample mesh count every N frames to keep the traversal cost negligible. */
+  sampleEveryFrames?: number;
+}
+
+export function useShadowMapWarmup({
+  light,
+  scene,
+  gl,
+  invalidate,
+  stableFramesThreshold = 60,
+  safetyCapFrames = 300,
+  sampleEveryFrames = 6,
+}: UseShadowMapWarmupOptions): void {
+  const meshCountRef = useRef(0);
+  const stableFramesRef = useRef(0);
+  const watchFramesRef = useRef(0);
+  const doneRef = useRef(false);
+
+  useFrame(() => {
+    if (doneRef.current || !light.current) return;
+
+    watchFramesRef.current += 1;
+
+    if (watchFramesRef.current % sampleEveryFrames === 0) {
+      let meshCount = 0;
+      scene.traverse((object) => {
+        if (object instanceof Mesh) meshCount += 1;
+      });
+
+      if (meshCount !== meshCountRef.current) {
+        meshCountRef.current = meshCount;
+        stableFramesRef.current = 0;
+      } else {
+        stableFramesRef.current += sampleEveryFrames;
+      }
+    }
+
+    const stableEnough = stableFramesRef.current >= stableFramesThreshold;
+    const safetyCapReached = watchFramesRef.current >= safetyCapFrames;
+    if (!stableEnough && !safetyCapReached) return;
+
+    doneRef.current = true;
+    reallocateShadowMap(light.current);
+    invalidateAllMaterials(scene);
+    forceShadowPass(gl, scene, light.current);
+    invalidate();
+  });
+}
+
+function reallocateShadowMap(light: DirectionalLight): void {
+  const shadowMap = light.shadow.map;
+  if (!shadowMap) return;
+
+  shadowMap.dispose();
+  light.shadow.map = null;
+}
+
+function invalidateAllMaterials(scene: Scene): void {
+  const seen = new Set<Material>();
+  scene.traverse((object) => {
+    if (!(object instanceof Mesh)) return;
+    const materials = Array.isArray(object.material)
+      ? object.material
+      : [object.material];
+    for (const material of materials) {
+      if (!material || seen.has(material)) continue;
+      seen.add(material);
+      material.needsUpdate = true;
+    }
+  });
+}
+
+function forceShadowPass(
+  gl: WebGLRenderer,
+  scene: Scene,
+  light: DirectionalLight,
+): void {
+  scene.updateMatrixWorld(true);
+  light.target.updateMatrixWorld(true);
+  light.updateMatrixWorld(true);
+  light.shadow.camera.updateMatrixWorld(true);
+  light.shadow.camera.updateProjectionMatrix();
+  light.shadow.needsUpdate = true;
+  gl.shadowMap.needsUpdate = true;
+}

src/managers/stores/useDebugVisualsStore.ts

@@ -13,6 +13,8 @@ interface DebugVisualsStore {
   setOctreeLeavesOnly: (value: boolean) => void;
   octreeOpacity: number;
   setOctreeOpacity: (value: number) => void;
+  octreeFabrikOnly: boolean;
+  setOctreeFabrikOnly: (value: boolean) => void;
 }
 
 export const useDebugVisualsStore = create<DebugVisualsStore>((set) => ({
@@ -28,4 +30,6 @@ export const useDebugVisualsStore = create<DebugVisualsStore>((set) => ({
   setOctreeLeavesOnly: (octreeLeavesOnly) => set({ octreeLeavesOnly }),
   octreeOpacity: 0.35,
   setOctreeOpacity: (octreeOpacity) => set({ octreeOpacity }),
+  octreeFabrikOnly: false,
+  setOctreeFabrikOnly: (octreeFabrikOnly) => set({ octreeFabrikOnly }),
 }));

src/world/GameMapCollision.tsx

@@ -272,18 +272,20 @@ function CollisionModelInstance({
   });
   const sceneInstance = useClonedObject(scene);
   useEffect(() => {
-    // Strip the door slab from the la fabrik collision octree so the player
-    // can walk through the doorway. The visual model is rendered separately
-    // by MergedStaticMapModel and is unaffected.
     if (node.name !== "lafabrik") return;
 
-    const removed: THREE.Object3D[] = [];
+    const isDoorSlab = (name: string): boolean =>
+      name === "porte" || /^porte[._]\d+$/i.test(name);
+    const isDoorFrameThickenChild = (child: THREE.Object3D): boolean =>
+      child.parent?.name === "Thicken";
+
+    const doorMeshes: THREE.Object3D[] = [];
     sceneInstance.traverse((child) => {
-      if (child.name === "porte") {
-        removed.push(child);
+      if (isDoorSlab(child.name) || isDoorFrameThickenChild(child)) {
+        doorMeshes.push(child);
       }
     });
-    for (const child of removed) {
+    for (const child of doorMeshes) {
       child.removeFromParent();
     }
   }, [node.name, sceneInstance]);
@@ -331,7 +333,6 @@ function CollisionBox({ box }: { box: OctreeCollisionBox }): React.JSX.Element {
         <boxGeometry args={box.size} />
         <meshBasicMaterial />
       </mesh>
-      {/* Octree ignores material.side, so rotate a second shell for X/Z collisions. */}
       <mesh rotation={[0, Math.PI, 0]}>
         <boxGeometry args={box.size} />
         <meshBasicMaterial />

src/world/Lighting.tsx

@@ -1,12 +1,10 @@
 import { useEffect, useRef } from "react";
 import { useFrame, useThree } from "@react-three/fiber";
 import {
-  Mesh,
   PCFShadowMap,
   type AmbientLight,
   type DirectionalLight,
   type Object3D,
-  type Scene,
   type WebGLRenderer,
 } from "three";
 import {
@@ -29,6 +27,7 @@ import {
 } from "@/data/world/lightingConfig";
 import { LA_FABRIK_INTERIOR_LIGHT_POSITION } from "@/data/world/laFabrikConfig";
 import { useDebugFolder } from "@/hooks/debug/useDebugFolder";
+import { useShadowMapWarmup } from "@/hooks/three/useShadowMapWarmup";
 import { LIGHTING_STATE } from "@/world/lightingState";
 
 function configureRendererShadows(gl: WebGLRenderer): void {
@@ -53,52 +52,41 @@ function configureSunShadow(sun: DirectionalLight, sunTarget: Object3D): void {
   sun.shadow.camera.updateProjectionMatrix();
 }
 
-// [diag] temporary helper: count shadow-casting/receiving meshes in the scene
-function snapshotShadowMeshes(scene: Scene): {
-  meshCount: number;
-  castShadowCount: number;
-  receiveShadowCount: number;
-} {
-  let meshCount = 0;
-  let castShadowCount = 0;
-  let receiveShadowCount = 0;
-  scene.traverse((obj) => {
-    if (obj instanceof Mesh) {
-      meshCount += 1;
-      if (obj.castShadow) castShadowCount += 1;
-      if (obj.receiveShadow) receiveShadowCount += 1;
-    }
-  });
-  return { meshCount, castShadowCount, receiveShadowCount };
+function placeSunRelativeToCamera(
+  sun: DirectionalLight,
+  sunTarget: Object3D,
+  cameraPosition: { x: number; z: number },
+): void {
+  sunTarget.position.set(cameraPosition.x, 0, cameraPosition.z);
+  sun.position.set(
+    cameraPosition.x + LIGHTING_STATE.sunX,
+    LIGHTING_STATE.sunY,
+    cameraPosition.z + LIGHTING_STATE.sunZ,
+  );
 }
 
 export function Lighting(): React.JSX.Element {
   const camera = useThree((state) => state.camera);
   const gl = useThree((state) => state.gl);
   const scene = useThree((state) => state.scene);
+  const invalidate = useThree((state) => state.invalidate);
   const ambient = useRef<AmbientLight>(null);
   const sun = useRef<DirectionalLight>(null);
   const sunTarget = useRef<Object3D>(null);
-  const lastDiagAtRef = useRef(0);
 
   useEffect(() => {
     if (!sun.current || !sunTarget.current) return;
 
-    configureSunShadow(sun.current, sunTarget.current);
     configureRendererShadows(gl);
-    sun.current.shadow.needsUpdate = true;
+    configureSunShadow(sun.current, sunTarget.current);
+    // Prime the sun + target onto the camera before the first shadow pass so
+    // the initial shadow frustum already covers the visible scene; without
+    // this, the first frame is rendered with the default (origin-centered)
+    // frustum and shadows can appear absent until the player moves.
+    placeSunRelativeToCamera(sun.current, sunTarget.current, camera.position);
+  }, [camera, gl]);
 
-    // [diag] one-shot scene snapshot to count shadow casters/receivers
-    const counts = snapshotShadowMeshes(scene);
-    console.log("[shadow:mount]", {
-      shadowMapEnabled: gl.shadowMap.enabled,
-      shadowMapType: gl.shadowMap.type,
-      shadowAutoUpdate: gl.shadowMap.autoUpdate,
-      sunCastShadow: sun.current.castShadow,
-      hasShadowMap: !!sun.current.shadow.map,
-      ...counts,
-    });
-  }, [gl, scene]);
+  useShadowMapWarmup({ light: sun, scene, gl, invalidate });
 
   useDebugFolder("Lighting", (folder) => {
     folder.addColor(LIGHTING_STATE, "ambientColor").name("Ambient Color");
@@ -132,43 +120,20 @@ export function Lighting(): React.JSX.Element {
       .name("Sun Z");
   });
 
-  useFrame(({ clock }) => {
+  useFrame(() => {
     if (ambient.current) {
       ambient.current.color.set(LIGHTING_STATE.ambientColor);
       ambient.current.intensity = LIGHTING_STATE.ambientIntensity;
     }
 
-    if (sun.current && sunTarget.current) {
-      sunTarget.current.position.set(camera.position.x, 0, camera.position.z);
-      sunTarget.current.updateMatrixWorld();
-      sun.current.position.set(
-        camera.position.x + LIGHTING_STATE.sunX,
-        LIGHTING_STATE.sunY,
-        camera.position.z + LIGHTING_STATE.sunZ,
-      );
-      sun.current.color.set(LIGHTING_STATE.sunColor);
-      sun.current.intensity = LIGHTING_STATE.sunIntensity;
-      sun.current.updateMatrixWorld();
-      sun.current.shadow.needsUpdate = true;
-    }
+    if (!sun.current || !sunTarget.current) return;
 
-    // [diag] periodic shadow pipeline check (every 2s)
-    const now = clock.getElapsedTime();
-    if (now - lastDiagAtRef.current > 2 && sun.current) {
-      lastDiagAtRef.current = now;
-      console.log("[shadow:tick]", {
-        shadowMapEnabled: gl.shadowMap.enabled,
-        shadowAutoUpdate: gl.shadowMap.autoUpdate,
-        sunCastShadow: sun.current.castShadow,
-        sunIntensity: sun.current.intensity,
-        hasShadowMapTexture: !!sun.current.shadow.map?.texture,
-        sunPos: sun.current.position.toArray().map((n) => Number(n.toFixed(2))),
-        targetPos: sunTarget.current?.position
-          .toArray()
-          .map((n) => Number(n.toFixed(2))),
-        renderCalls: gl.info.render.calls,
-      });
-    }
+    placeSunRelativeToCamera(sun.current, sunTarget.current, camera.position);
+    sunTarget.current.updateMatrixWorld();
+    sun.current.color.set(LIGHTING_STATE.sunColor);
+    sun.current.intensity = LIGHTING_STATE.sunIntensity;
+    sun.current.updateMatrixWorld();
+    sun.current.shadow.needsUpdate = true;
   });
 
   return (