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.

src/components/debug/DebugOctreeVisualization.tsx

@@ -1,5 +1,5 @@
 import { useMemo } from "react";
-import { Box3, BufferAttribute, BufferGeometry, Color } from "three";
+import { Box3, BufferAttribute, BufferGeometry } from "three";
 import type { Octree } from "three-stdlib";
 import { useDebugVisualsStore } from "@/managers/stores/useDebugVisualsStore";
 
@@ -11,6 +11,13 @@ interface OctreeNodeBox {
   box: Box3;
   depth: number;
   triangleCount: number;
+  isLeaf: boolean;
+}
+
+interface CollectOptions {
+  minDepth: number;
+  maxDepth: number;
+  leavesOnly: boolean;
 }
 
 const BOX_VERTEX_INDEX_PAIRS: ReadonlyArray<readonly [number, number]> = [
@@ -30,20 +37,28 @@ const BOX_VERTEX_INDEX_PAIRS: ReadonlyArray<readonly [number, number]> = [
 
 function collectOctreeBoxes(
   node: Octree,
-  maxDepth: number,
+  options: CollectOptions,
   depth = 0,
   acc: OctreeNodeBox[] = [],
 ): OctreeNodeBox[] {
-  if (depth > maxDepth) return acc;
+  if (depth > options.maxDepth) return acc;
 
+  const isLeaf = node.subTrees.length === 0;
+  const passesDepth = depth >= options.minDepth;
+  const passesLeafFilter = !options.leavesOnly || isLeaf;
+  const hasTriangles = node.triangles.length > 0;
+
+  if (passesDepth && passesLeafFilter && hasTriangles) {
     acc.push({
       box: node.box,
       depth,
       triangleCount: node.triangles.length,
+      isLeaf,
     });
+  }
 
   for (const sub of node.subTrees) {
-    collectOctreeBoxes(sub, maxDepth, depth + 1, acc);
+    collectOctreeBoxes(sub, options, depth + 1, acc);
   }
 
   return acc;
@@ -55,17 +70,12 @@ function buildOctreeLineGeometry(
   const positionsBuffer = new Float32Array(
     nodes.length * BOX_VERTEX_INDEX_PAIRS.length * 2 * 3,
   );
-  const colorsBuffer = new Float32Array(
-    nodes.length * BOX_VERTEX_INDEX_PAIRS.length * 2 * 3,
-  );
 
   const corners: [number, number, number][] = Array.from({ length: 8 }, () => [
     0, 0, 0,
   ]);
 
   let positionsOffset = 0;
-  let colorsOffset = 0;
-  const colorHelper = new Color();
 
   for (const node of nodes) {
     const { min, max } = node.box;
@@ -79,9 +89,6 @@ function buildOctreeLineGeometry(
     corners[6] = [min.x, max.y, max.z];
     corners[7] = [max.x, max.y, max.z];
 
-    const hue = (node.depth * 0.13) % 1;
-    colorHelper.setHSL(hue, 0.85, 0.55);
-
     for (const [a, b] of BOX_VERTEX_INDEX_PAIRS) {
       const ca = corners[a]!;
       const cb = corners[b]!;
@@ -91,19 +98,11 @@ function buildOctreeLineGeometry(
       positionsBuffer[positionsOffset++] = cb[0];
       positionsBuffer[positionsOffset++] = cb[1];
       positionsBuffer[positionsOffset++] = cb[2];
-
-      colorsBuffer[colorsOffset++] = colorHelper.r;
-      colorsBuffer[colorsOffset++] = colorHelper.g;
-      colorsBuffer[colorsOffset++] = colorHelper.b;
-      colorsBuffer[colorsOffset++] = colorHelper.r;
-      colorsBuffer[colorsOffset++] = colorHelper.g;
-      colorsBuffer[colorsOffset++] = colorHelper.b;
     }
   }
 
   const geometry = new BufferGeometry();
   geometry.setAttribute("position", new BufferAttribute(positionsBuffer, 3));
-  geometry.setAttribute("color", new BufferAttribute(colorsBuffer, 3));
   return geometry;
 }
 
@@ -111,14 +110,21 @@ export function DebugOctreeVisualization({
   octree,
 }: DebugOctreeVisualizationProps): React.JSX.Element | null {
   const showOctree = useDebugVisualsStore((state) => state.showOctree);
+  const minDepth = useDebugVisualsStore((state) => state.octreeMinDepth);
   const maxDepth = useDebugVisualsStore((state) => state.octreeMaxDepth);
+  const leavesOnly = useDebugVisualsStore((state) => state.octreeLeavesOnly);
+  const opacity = useDebugVisualsStore((state) => state.octreeOpacity);
 
   const geometry = useMemo(() => {
     if (!octree || !showOctree) return null;
-    const boxes = collectOctreeBoxes(octree, maxDepth);
+    const boxes = collectOctreeBoxes(octree, {
+      minDepth,
+      maxDepth,
+      leavesOnly,
+    });
     if (boxes.length === 0) return null;
     return buildOctreeLineGeometry(boxes);
-  }, [maxDepth, octree, showOctree]);
+  }, [leavesOnly, maxDepth, minDepth, octree, showOctree]);
 
   if (!geometry) return null;
 
@@ -126,11 +132,11 @@ export function DebugOctreeVisualization({
     <lineSegments frustumCulled={false} renderOrder={999}>
       <primitive object={geometry} attach="geometry" />
       <lineBasicMaterial
-        vertexColors
+        color="#22d3ee"
         depthTest={false}
         depthWrite={false}
         transparent
-        opacity={0.85}
+        opacity={opacity}
       />
     </lineSegments>
   );

src/components/ui/TalkieDialogueOverlay.tsx

@@ -71,14 +71,14 @@ export function TalkieDialogueOverlay(): React.JSX.Element | null {
     mainState !== "intro" || TALKIE_REVEAL_STEPS.has(introStep);
   const isNarratorDialogue = activeSubtitle?.speaker === "Narrateur";
 
-  if (!isAfterReveal || !isNarratorDialogue) return null;
+  if (!isAfterReveal) return null;
 
   return (
     <aside
-      className="talkie-dialogue-overlay talkie-dialogue-overlay--raised"
+      className={`talkie-dialogue-overlay${isNarratorDialogue ? " talkie-dialogue-overlay--raised" : ""}`}
       aria-hidden="true"
     >
-      <TalkieSignalLines />
+      {isNarratorDialogue ? <TalkieSignalLines /> : null}
       <div className="talkie-dialogue-overlay__model-frame">
         <Canvas
           camera={{ position: [0, 0, 4.2], zoom: 78 }}

src/hooks/debug/useDebugVisualsDebug.ts

@@ -3,10 +3,14 @@ import { useDebugVisualsStore } from "@/managers/stores/useDebugVisualsStore";
 
 export function useDebugVisualsDebug(): void {
   useDebugFolder("Debug", (folder) => {
+    const state = useDebugVisualsStore.getState();
     const controls = {
-      showPlayerModel: useDebugVisualsStore.getState().showPlayerModel,
+      showPlayerModel: state.showPlayerModel,
-      showOctree: useDebugVisualsStore.getState().showOctree,
+      showOctree: state.showOctree,
-      octreeMaxDepth: useDebugVisualsStore.getState().octreeMaxDepth,
+      octreeMinDepth: state.octreeMinDepth,
+      octreeMaxDepth: state.octreeMaxDepth,
+      octreeLeavesOnly: state.octreeLeavesOnly,
+      octreeOpacity: state.octreeOpacity,
     };
 
     folder
@@ -23,11 +27,32 @@ export function useDebugVisualsDebug(): void {
         useDebugVisualsStore.getState().setShowOctree(value);
       });
 
+    folder
+      .add(controls, "octreeLeavesOnly")
+      .name("Octree Leaves Only")
+      .onChange((value: boolean) => {
+        useDebugVisualsStore.getState().setOctreeLeavesOnly(value);
+      });
+
+    folder
+      .add(controls, "octreeMinDepth", 0, 10, 1)
+      .name("Octree Min Depth")
+      .onChange((value: number) => {
+        useDebugVisualsStore.getState().setOctreeMinDepth(value);
+      });
+
     folder
       .add(controls, "octreeMaxDepth", 0, 10, 1)
       .name("Octree Max Depth")
       .onChange((value: number) => {
         useDebugVisualsStore.getState().setOctreeMaxDepth(value);
       });
+
+    folder
+      .add(controls, "octreeOpacity", 0.05, 1, 0.05)
+      .name("Octree Opacity")
+      .onChange((value: number) => {
+        useDebugVisualsStore.getState().setOctreeOpacity(value);
+      });
   });
 }

src/managers/stores/useDebugVisualsStore.ts

@@ -7,6 +7,12 @@ interface DebugVisualsStore {
   setShowOctree: (value: boolean) => void;
   octreeMaxDepth: number;
   setOctreeMaxDepth: (value: number) => void;
+  octreeMinDepth: number;
+  setOctreeMinDepth: (value: number) => void;
+  octreeLeavesOnly: boolean;
+  setOctreeLeavesOnly: (value: boolean) => void;
+  octreeOpacity: number;
+  setOctreeOpacity: (value: number) => void;
 }
 
 export const useDebugVisualsStore = create<DebugVisualsStore>((set) => ({
@@ -14,6 +20,12 @@ export const useDebugVisualsStore = create<DebugVisualsStore>((set) => ({
   setShowPlayerModel: (showPlayerModel) => set({ showPlayerModel }),
   showOctree: false,
   setShowOctree: (showOctree) => set({ showOctree }),
-  octreeMaxDepth: 6,
+  octreeMaxDepth: 8,
   setOctreeMaxDepth: (octreeMaxDepth) => set({ octreeMaxDepth }),
+  octreeMinDepth: 4,
+  setOctreeMinDepth: (octreeMinDepth) => set({ octreeMinDepth }),
+  octreeLeavesOnly: true,
+  setOctreeLeavesOnly: (octreeLeavesOnly) => set({ octreeLeavesOnly }),
+  octreeOpacity: 0.35,
+  setOctreeOpacity: (octreeOpacity) => set({ octreeOpacity }),
 }));

src/world/Lighting.tsx

@@ -1,10 +1,12 @@
 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 {
@@ -51,12 +53,33 @@ 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 };
+}
+
 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 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;
@@ -64,7 +87,18 @@ export function Lighting(): React.JSX.Element {
     configureSunShadow(sun.current, sunTarget.current);
     configureRendererShadows(gl);
     sun.current.shadow.needsUpdate = true;
-  }, [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]);
 
   useDebugFolder("Lighting", (folder) => {
     folder.addColor(LIGHTING_STATE, "ambientColor").name("Ambient Color");
@@ -98,7 +132,7 @@ export function Lighting(): React.JSX.Element {
       .name("Sun Z");
   });
 
-  useFrame(() => {
+  useFrame(({ clock }) => {
     if (ambient.current) {
       ambient.current.color.set(LIGHTING_STATE.ambientColor);
       ambient.current.intensity = LIGHTING_STATE.ambientIntensity;
@@ -117,6 +151,24 @@ export function Lighting(): React.JSX.Element {
       sun.current.updateMatrixWorld();
       sun.current.shadow.needsUpdate = true;
     }
+
+    // [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,
+      });
+    }
   });
 
   return (