@principal-ai/file-city-react 0.5.8 → 0.5.9

package/src/components/FileCity3D/FileCity3D.tsx

@@ -310,6 +310,9 @@ function hasActiveHighlights(layers: HighlightLayer[]): boolean {
 // Animated RoundedBox wrapper
 const AnimatedRoundedBox = animated(RoundedBox);
 
+// Animated meshStandardMaterial for opacity transitions
+const AnimatedMeshStandardMaterial = animated('meshStandardMaterial');
+
 // ============================================================================
 // Building Edges - Batched edge rendering for performance
 // ============================================================================
@@ -317,10 +320,11 @@ const AnimatedRoundedBox = animated(RoundedBox);
 interface BuildingEdgeData {
   width: number;
   depth: number;
-  targetHeight: number;
+  fullHeight: number;
   x: number;
   z: number;
   staggerDelayMs: number;
+  buildingIndex: number; // Index to look up height multiplier
 }
 
 interface BuildingEdgesProps {
@@ -329,9 +333,10 @@ interface BuildingEdgesProps {
   minHeight: number;
   baseOffset: number;
   springDuration: number;
+  heightMultipliersRef: React.MutableRefObject<Float32Array | null>;
 }
 
-function BuildingEdges({ buildings, growProgress, minHeight, baseOffset, springDuration }: BuildingEdgesProps) {
+function BuildingEdges({ buildings, growProgress, minHeight, baseOffset, springDuration, heightMultipliersRef }: BuildingEdgesProps) {
   const meshRef = useRef<THREE.InstancedMesh>(null);
   const startTimeRef = useRef<number | null>(null);
   const tempObject = useMemo(() => new THREE.Object3D(), []);
@@ -342,15 +347,15 @@ function BuildingEdges({ buildings, growProgress, minHeight, baseOffset, springD
   // Pre-compute edge data
   const edgeData = useMemo(() => {
     return buildings.flatMap((data) => {
-      const { width, depth, x, z, targetHeight, staggerDelayMs } = data;
+      const { width, depth, x, z, fullHeight, staggerDelayMs, buildingIndex } = data;
       const halfW = width / 2;
       const halfD = depth / 2;
 
       return [
-        { x: x - halfW, z: z - halfD, targetHeight, staggerDelayMs },
-        { x: x + halfW, z: z - halfD, targetHeight, staggerDelayMs },
-        { x: x - halfW, z: z + halfD, targetHeight, staggerDelayMs },
-        { x: x + halfW, z: z + halfD, targetHeight, staggerDelayMs },
+        { x: x - halfW, z: z - halfD, fullHeight, staggerDelayMs, buildingIndex },
+        { x: x + halfW, z: z - halfD, fullHeight, staggerDelayMs, buildingIndex },
+        { x: x - halfW, z: z + halfD, fullHeight, staggerDelayMs, buildingIndex },
+        { x: x + halfW, z: z + halfD, fullHeight, staggerDelayMs, buildingIndex },
       ];
     });
   }, [buildings]);
@@ -367,7 +372,10 @@ function BuildingEdges({ buildings, growProgress, minHeight, baseOffset, springD
     const animStartTime = startTimeRef.current ?? currentTime;
 
     edgeData.forEach((edge, idx) => {
-      const { x, z, targetHeight, staggerDelayMs } = edge;
+      const { x, z, fullHeight, staggerDelayMs, buildingIndex } = edge;
+
+      // Get height multiplier from shared ref (for collapse animation)
+      const heightMultiplier = heightMultipliersRef.current?.[buildingIndex] ?? 1;
 
       // Calculate per-building animation progress
       const elapsed = currentTime - animStartTime - staggerDelayMs;
@@ -381,7 +389,8 @@ function BuildingEdges({ buildings, growProgress, minHeight, baseOffset, springD
         animProgress = 0;
       }
 
-      const height = animProgress * targetHeight + minHeight;
+      // Apply both grow animation and collapse multiplier
+      const height = animProgress * fullHeight * heightMultiplier + minHeight;
       const yPosition = height / 2 + baseOffset;
 
       tempObject.position.set(x, yPosition, z);
@@ -416,13 +425,18 @@ interface InstancedBuildingsProps {
   hoveredIndex: number | null;
   growProgress: number;
   animationConfig: AnimationConfig;
-  highlightLayers: HighlightLayer[];
-  isolationMode: IsolationMode;
-  hasActiveHighlights: boolean;
-  dimOpacity: number;
   heightScaling: HeightScaling;
   linearScale: number;
   staggerIndices: number[];
+  focusDirectory: string | null;
+  highlightLayers: HighlightLayer[];
+  isolationMode: IsolationMode;
+}
+
+// Helper to check if a path is inside a directory
+function isPathInDirectory(path: string, directory: string | null): boolean {
+  if (!directory) return true;
+  return path === directory || path.startsWith(directory + '/');
 }
 
 function InstancedBuildings({
@@ -433,77 +447,85 @@ function InstancedBuildings({
   hoveredIndex,
   growProgress,
   animationConfig,
-  highlightLayers,
-  isolationMode,
-  hasActiveHighlights,
-  dimOpacity,
   heightScaling,
   linearScale,
   staggerIndices,
+  focusDirectory,
+  highlightLayers,
+  isolationMode,
 }: InstancedBuildingsProps) {
   const meshRef = useRef<THREE.InstancedMesh>(null);
   const startTimeRef = useRef<number | null>(null);
   const tempObject = useMemo(() => new THREE.Object3D(), []);
   const tempColor = useMemo(() => new THREE.Color(), []);
 
+  // Track animated height multipliers for each building (for collapse animation)
+  const heightMultipliersRef = useRef<Float32Array | null>(null);
+  const targetMultipliersRef = useRef<Float32Array | null>(null);
+
+  // Check if highlight layers have any active items
+  const hasActiveHighlightLayers = useMemo(() => {
+    return highlightLayers.some(layer => layer.enabled && layer.items.length > 0);
+  }, [highlightLayers]);
+
+  // Initialize height multiplier arrays
+  useEffect(() => {
+    if (buildings.length > 0) {
+      if (!heightMultipliersRef.current || heightMultipliersRef.current.length !== buildings.length) {
+        heightMultipliersRef.current = new Float32Array(buildings.length).fill(1);
+        targetMultipliersRef.current = new Float32Array(buildings.length).fill(1);
+      }
+    }
+  }, [buildings.length]);
+
+  // Update target multipliers when focusDirectory or highlightLayers change
+  useEffect(() => {
+    if (!targetMultipliersRef.current) return;
+
+    buildings.forEach((building, index) => {
+      let shouldCollapse = false;
+
+      // Priority 1: focusDirectory - collapse buildings outside
+      if (focusDirectory) {
+        const isInFocus = isPathInDirectory(building.path, focusDirectory);
+        shouldCollapse = !isInFocus;
+      }
+      // Priority 2: highlightLayers with collapse isolation mode
+      else if (hasActiveHighlightLayers && isolationMode === 'collapse') {
+        const highlight = getHighlightForPath(building.path, highlightLayers);
+        shouldCollapse = highlight === null;
+      }
+
+      targetMultipliersRef.current![index] = shouldCollapse ? 0.05 : 1;
+    });
+  }, [focusDirectory, buildings, highlightLayers, isolationMode, hasActiveHighlightLayers]);
+
   // Pre-compute building data
   const buildingData = useMemo(() => {
     return buildings.map((building, index) => {
       const [width, , depth] = building.dimensions;
-      const highlight = getHighlightForPath(building.path, highlightLayers);
-      const isHighlighted = highlight !== null;
-      const shouldDim = hasActiveHighlights && !isHighlighted;
-      const shouldCollapse = shouldDim && isolationMode === 'collapse';
-      const shouldHide = shouldDim && isolationMode === 'hide';
-
-      const fullHeight = calculateBuildingHeight(
-        building,
-        heightScaling,
-        linearScale
-      );
-      const targetHeight = shouldCollapse ? 0.5 : fullHeight;
-
-      const baseColor = getColorForFile(building);
-      const color = isHighlighted ? highlight.color : baseColor;
+      const fullHeight = calculateBuildingHeight(building, heightScaling, linearScale);
+      const color = getColorForFile(building);
 
       const x = building.position.x - centerOffset.x;
       const z = building.position.z - centerOffset.z;
 
       const staggerIndex = staggerIndices[index] ?? index;
-      const staggerDelayMs =
-        (animationConfig.staggerDelay || 15) * staggerIndex;
+      const staggerDelayMs = (animationConfig.staggerDelay || 15) * staggerIndex;
 
       return {
         building,
         index,
         width,
         depth,
-        targetHeight,
+        fullHeight,
         color,
         x,
         z,
-        shouldHide,
-        shouldDim,
         staggerDelayMs,
-        isHighlighted,
       };
     });
-  }, [
-    buildings,
-    centerOffset,
-    highlightLayers,
-    hasActiveHighlights,
-    isolationMode,
-    heightScaling,
-    linearScale,
-    staggerIndices,
-    animationConfig.staggerDelay,
-  ]);
-
-  const visibleBuildings = useMemo(
-    () => buildingData.filter((b) => !b.shouldHide),
-    [buildingData]
-  );
+  }, [buildings, centerOffset, heightScaling, linearScale, staggerIndices, animationConfig.staggerDelay]);
 
   const minHeight = 0.3;
   const baseOffset = 0.2;
@@ -511,13 +533,20 @@ function InstancedBuildings({
   const friction = animationConfig.friction || 14;
   const springDuration = Math.sqrt(1 / (tension * 0.001)) * friction * 20;
 
+  // Initialize all buildings (only on first render or when building data changes)
+  // DO NOT include focusDirectory here - that would bypass the animation
+  const initializedRef = useRef(false);
+
   useEffect(() => {
-    if (!meshRef.current) return;
+    if (!meshRef.current || buildingData.length === 0) return;
 
-    visibleBuildings.forEach((data, instanceIndex) => {
-      const { width, depth, x, z, color, targetHeight } = data;
+    buildingData.forEach((data, instanceIndex) => {
+      const { width, depth, x, z, color, fullHeight } = data;
 
-      const height = growProgress * targetHeight + minHeight;
+      // Use the current animated multiplier, or default to 1 on first render
+      const multiplier = heightMultipliersRef.current?.[instanceIndex] ?? 1;
+
+      const height = growProgress * fullHeight * multiplier + minHeight;
       const yPosition = height / 2 + baseOffset;
 
       tempObject.position.set(x, yPosition, z);
@@ -534,17 +563,14 @@ function InstancedBuildings({
     if (meshRef.current.instanceColor) {
       meshRef.current.instanceColor.needsUpdate = true;
     }
-  }, [
-    visibleBuildings,
-    growProgress,
-    tempObject,
-    tempColor,
-    minHeight,
-    baseOffset,
-  ]);
 
+    initializedRef.current = true;
+  }, [buildingData, growProgress, tempObject, tempColor, minHeight, baseOffset]);
+
+  // Animate buildings each frame
   useFrame(({ clock }) => {
-    if (!meshRef.current) return;
+    if (!meshRef.current || buildingData.length === 0) return;
+    if (!heightMultipliersRef.current || !targetMultipliersRef.current) return;
 
     if (startTimeRef.current === null && growProgress > 0) {
       startTimeRef.current = clock.elapsedTime * 1000;
@@ -553,10 +579,19 @@ function InstancedBuildings({
     const currentTime = clock.elapsedTime * 1000;
     const animStartTime = startTimeRef.current ?? currentTime;
 
-    visibleBuildings.forEach((data, instanceIndex) => {
-      const { width, depth, targetHeight, x, z, staggerDelayMs, shouldDim } =
-        data;
+    // Animation speed for collapse/expand (lerp factor per frame)
+    const collapseSpeed = 0.08;
 
+    buildingData.forEach((data, instanceIndex) => {
+      const { width, depth, fullHeight, x, z, staggerDelayMs } = data;
+
+      // Animate height multiplier towards target
+      const currentMultiplier = heightMultipliersRef.current![instanceIndex];
+      const targetMultiplier = targetMultipliersRef.current![instanceIndex];
+      const newMultiplier = currentMultiplier + (targetMultiplier - currentMultiplier) * collapseSpeed;
+      heightMultipliersRef.current![instanceIndex] = newMultiplier;
+
+      // Calculate grow animation progress
       const elapsed = currentTime - animStartTime - staggerDelayMs;
       let animProgress = growProgress;
 
@@ -568,7 +603,8 @@ function InstancedBuildings({
         animProgress = 0;
       }
 
-      const height = animProgress * targetHeight + minHeight;
+      // Apply both grow animation and collapse multiplier
+      const height = animProgress * fullHeight * newMultiplier + minHeight;
       const yPosition = height / 2 + baseOffset;
 
       const isHovered = hoveredIndex === data.index;
@@ -580,11 +616,15 @@ function InstancedBuildings({
 
       meshRef.current!.setMatrixAt(instanceIndex, tempObject.matrix);
 
-      const opacity =
-        shouldDim && isolationMode === 'transparent' ? dimOpacity : 1;
+      // Desaturate collapsed buildings
       tempColor.set(data.color);
-      if (opacity < 1) {
-        tempColor.multiplyScalar(opacity + 0.3);
+      if (newMultiplier < 0.5) {
+        // Lerp towards gray based on collapse amount
+        const grayAmount = 1 - newMultiplier * 2; // 0 at multiplier=0.5, 1 at multiplier=0
+        const gray = 0.3;
+        tempColor.r = tempColor.r * (1 - grayAmount) + gray * grayAmount;
+        tempColor.g = tempColor.g * (1 - grayAmount) + gray * grayAmount;
+        tempColor.b = tempColor.b * (1 - grayAmount) + gray * grayAmount;
       }
       if (isHovered) {
         tempColor.multiplyScalar(1.2);
@@ -601,15 +641,12 @@ function InstancedBuildings({
   const handlePointerMove = useCallback(
     (e: ThreeEvent<PointerEvent>) => {
       e.stopPropagation();
-      if (
-        e.instanceId !== undefined &&
-        e.instanceId < visibleBuildings.length
-      ) {
-        const data = visibleBuildings[e.instanceId];
+      if (e.instanceId !== undefined && e.instanceId < buildingData.length) {
+        const data = buildingData[e.instanceId];
         onHover?.(data.building);
       }
     },
-    [visibleBuildings, onHover]
+    [buildingData, onHover]
   );
 
   const handlePointerOut = useCallback(() => {
@@ -619,25 +656,22 @@ function InstancedBuildings({
   const handleClick = useCallback(
     (e: ThreeEvent<MouseEvent>) => {
       e.stopPropagation();
-      if (
-        e.instanceId !== undefined &&
-        e.instanceId < visibleBuildings.length
-      ) {
-        const data = visibleBuildings[e.instanceId];
+      if (e.instanceId !== undefined && e.instanceId < buildingData.length) {
+        const data = buildingData[e.instanceId];
         onClick?.(data.building);
       }
     },
-    [visibleBuildings, onClick]
+    [buildingData, onClick]
   );
 
-  if (visibleBuildings.length === 0) return null;
+  if (buildingData.length === 0) return null;
 
   return (
     <group>
-      {/* Main building meshes */}
+      {/* All buildings - single mesh, original colors */}
       <instancedMesh
         ref={meshRef}
-        args={[undefined, undefined, visibleBuildings.length]}
+        args={[undefined, undefined, buildingData.length]}
         onPointerMove={handlePointerMove}
         onPointerOut={handlePointerOut}
         onClick={handleClick}
@@ -647,13 +681,22 @@ function InstancedBuildings({
         <meshStandardMaterial metalness={0.1} roughness={0.35} />
       </instancedMesh>
 
-      {/* Building edge outlines - batched into single geometry for performance */}
+      {/* Building edge outlines */}
       <BuildingEdges
-        buildings={visibleBuildings}
+        buildings={buildingData.map(d => ({
+          width: d.width,
+          depth: d.depth,
+          fullHeight: d.fullHeight,
+          x: d.x,
+          z: d.z,
+          staggerDelayMs: d.staggerDelayMs,
+          buildingIndex: d.index,
+        }))}
         growProgress={growProgress}
         minHeight={minHeight}
         baseOffset={baseOffset}
         springDuration={springDuration}
+        heightMultipliersRef={heightMultipliersRef}
       />
     </group>
   );
@@ -909,9 +952,16 @@ function DistrictFloor({
 }
 
 // Camera controller
+interface FocusTarget {
+  x: number;
+  z: number;
+  size: number;  // Approximate size of the focused area
+}
+
 interface AnimatedCameraProps {
   citySize: number;
   isFlat: boolean;
+  focusTarget?: FocusTarget | null;
 }
 
 let cameraResetFn: (() => void) | null = null;
@@ -920,11 +970,59 @@ export function resetCamera() {
   cameraResetFn?.();
 }
 
-function AnimatedCamera({ citySize, isFlat }: AnimatedCameraProps) {
+function AnimatedCamera({ citySize, isFlat, focusTarget }: AnimatedCameraProps) {
   const { camera } = useThree();
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const controlsRef = useRef<any>(null);
 
+  // Animated camera position and target
+  const targetPos = useMemo(() => {
+    if (focusTarget) {
+      // Position camera to look at focus target
+      const distance = Math.max(focusTarget.size * 2, 50);
+      const height = Math.max(focusTarget.size * 1.5, 40);
+      return {
+        x: focusTarget.x,
+        y: height,
+        z: focusTarget.z + distance,
+        targetX: focusTarget.x,
+        targetY: 0,
+        targetZ: focusTarget.z,
+      };
+    }
+    // Default: overview of entire city
+    const targetHeight = isFlat ? citySize * 1.5 : citySize * 1.1;
+    const targetZ = isFlat ? 0 : citySize * 1.3;
+    return {
+      x: 0,
+      y: targetHeight,
+      z: targetZ,
+      targetX: 0,
+      targetY: 0,
+      targetZ: 0,
+    };
+  }, [focusTarget, isFlat, citySize]);
+
+  // Spring animation for camera movement
+  const { camX, camY, camZ, lookX, lookY, lookZ } = useSpring({
+    camX: targetPos.x,
+    camY: targetPos.y,
+    camZ: targetPos.z,
+    lookX: targetPos.targetX,
+    lookY: targetPos.targetY,
+    lookZ: targetPos.targetZ,
+    config: { tension: 60, friction: 20 },
+  });
+
+  // Update camera each frame based on spring values
+  useFrame(() => {
+    if (!controlsRef.current) return;
+
+    camera.position.set(camX.get(), camY.get(), camZ.get());
+    controlsRef.current.target.set(lookX.get(), lookY.get(), lookZ.get());
+    controlsRef.current.update();
+  });
+
   const resetToInitial = useCallback(() => {
     const targetHeight = isFlat ? citySize * 1.5 : citySize * 1.1;
     const targetZ = isFlat ? 0 : citySize * 1.3;
@@ -939,8 +1037,10 @@ function AnimatedCamera({ citySize, isFlat }: AnimatedCameraProps) {
   }, [isFlat, citySize, camera]);
 
   useEffect(() => {
-    resetToInitial();
-  }, [resetToInitial]);
+    if (!focusTarget) {
+      resetToInitial();
+    }
+  }, [resetToInitial, focusTarget]);
 
   useEffect(() => {
     cameraResetFn = resetToInitial;
@@ -1073,9 +1173,9 @@ interface CitySceneProps {
   animationConfig: AnimationConfig;
   highlightLayers: HighlightLayer[];
   isolationMode: IsolationMode;
-  dimOpacity: number;
   heightScaling: HeightScaling;
   linearScale: number;
+  focusDirectory: string | null;
 }
 
 function CityScene({
@@ -1087,9 +1187,9 @@ function CityScene({
   animationConfig,
   highlightLayers,
   isolationMode,
-  dimOpacity,
   heightScaling,
   linearScale,
+  focusDirectory,
 }: CitySceneProps) {
   const centerOffset = useMemo(
     () => ({
@@ -1109,6 +1209,146 @@ function CityScene({
     [highlightLayers]
   );
 
+  // Helper to check if a path is inside a directory
+  const isPathInDirectory = useCallback((path: string, directory: string) => {
+    if (!directory) return true;
+    return path === directory || path.startsWith(directory + '/');
+  }, []);
+
+  // Three-phase animation when switching directories:
+  // Phase 1: Camera zooms out to overview
+  // Phase 2: Buildings collapse/expand
+  // Phase 3: Camera zooms into new directory
+  //
+  // We track two separate states:
+  // - buildingFocusDirectory: controls which buildings are collapsed (passed to InstancedBuildings)
+  // - cameraFocusDirectory: controls camera position (used for focusTarget calculation)
+  const [buildingFocusDirectory, setBuildingFocusDirectory] = useState<string | null>(null);
+  const [cameraFocusDirectory, setCameraFocusDirectory] = useState<string | null>(null);
+  const prevFocusDirectoryRef = useRef<string | null>(null);
+  const animationTimersRef = useRef<NodeJS.Timeout[]>([]);
+
+  useEffect(() => {
+    // Clear any pending timers
+    animationTimersRef.current.forEach(clearTimeout);
+    animationTimersRef.current = [];
+
+    const prevFocus = prevFocusDirectoryRef.current;
+    prevFocusDirectoryRef.current = focusDirectory;
+
+    // No change
+    if (focusDirectory === prevFocus) return;
+
+    // Case 1: Going from overview to a directory (null -> dir)
+    if (prevFocus === null && focusDirectory !== null) {
+      // Phase 1: Collapse buildings immediately
+      setBuildingFocusDirectory(focusDirectory);
+      // Phase 2: After collapse settles, zoom camera in
+      const timer = setTimeout(() => {
+        setCameraFocusDirectory(focusDirectory);
+      }, 600);
+      animationTimersRef.current.push(timer);
+      return;
+    }
+
+    // Case 2: Going from a directory to overview (dir -> null)
+    if (prevFocus !== null && focusDirectory === null) {
+      // Phase 1: Zoom camera out first
+      setCameraFocusDirectory(null);
+      // Phase 2: After zoom-out settles, expand buildings
+      const timer = setTimeout(() => {
+        setBuildingFocusDirectory(null);
+      }, 500);
+      animationTimersRef.current.push(timer);
+      return;
+    }
+
+    // Case 3: Switching between directories (dirA -> dirB)
+    if (prevFocus !== null && focusDirectory !== null) {
+      // Phase 1: Zoom camera out
+      setCameraFocusDirectory(null);
+      // Phase 2: After zoom-out, collapse/expand buildings
+      const timer1 = setTimeout(() => {
+        setBuildingFocusDirectory(focusDirectory);
+      }, 500);
+      // Phase 3: After collapse settles, zoom camera into new directory
+      const timer2 = setTimeout(() => {
+        setCameraFocusDirectory(focusDirectory);
+      }, 1100); // 500ms zoom-out + 600ms collapse
+      animationTimersRef.current.push(timer1, timer2);
+      return;
+    }
+  }, [focusDirectory]);
+
+  // Cleanup timers on unmount
+  useEffect(() => {
+    return () => {
+      animationTimersRef.current.forEach(clearTimeout);
+    };
+  }, []);
+
+  // Calculate focus target from cameraFocusDirectory (for camera)
+  const focusTarget = useMemo((): FocusTarget | null => {
+    // Use camera focus directory for camera movement
+    if (cameraFocusDirectory) {
+      const focusedBuildings = cityData.buildings.filter((building) =>
+        isPathInDirectory(building.path, cameraFocusDirectory)
+      );
+
+      if (focusedBuildings.length === 0) return null;
+
+      let minX = Infinity, maxX = -Infinity;
+      let minZ = Infinity, maxZ = -Infinity;
+
+      for (const building of focusedBuildings) {
+        const x = building.position.x - centerOffset.x;
+        const z = building.position.z - centerOffset.z;
+        const [width, , depth] = building.dimensions;
+
+        minX = Math.min(minX, x - width / 2);
+        maxX = Math.max(maxX, x + width / 2);
+        minZ = Math.min(minZ, z - depth / 2);
+        maxZ = Math.max(maxZ, z + depth / 2);
+      }
+
+      const centerX = (minX + maxX) / 2;
+      const centerZ = (minZ + maxZ) / 2;
+      const size = Math.max(maxX - minX, maxZ - minZ);
+
+      return { x: centerX, z: centerZ, size };
+    }
+
+    // Priority 2: highlight layers
+    if (!activeHighlights) return null;
+
+    const highlightedBuildings = cityData.buildings.filter((building) => {
+      const highlight = getHighlightForPath(building.path, highlightLayers);
+      return highlight !== null;
+    });
+
+    if (highlightedBuildings.length === 0) return null;
+
+    let minX = Infinity, maxX = -Infinity;
+    let minZ = Infinity, maxZ = -Infinity;
+
+    for (const building of highlightedBuildings) {
+      const x = building.position.x - centerOffset.x;
+      const z = building.position.z - centerOffset.z;
+      const [width, , depth] = building.dimensions;
+
+      minX = Math.min(minX, x - width / 2);
+      maxX = Math.max(maxX, x + width / 2);
+      minZ = Math.min(minZ, z - depth / 2);
+      maxZ = Math.max(maxZ, z + depth / 2);
+    }
+
+    const centerX = (minX + maxX) / 2;
+    const centerZ = (minZ + maxZ) / 2;
+    const size = Math.max(maxX - minX, maxZ - minZ);
+
+    return { x: centerX, z: centerZ, size };
+  }, [cameraFocusDirectory, activeHighlights, cityData.buildings, highlightLayers, centerOffset, isPathInDirectory]);
+
   const staggerIndices = useMemo(() => {
     const centerX = (cityData.bounds.minX + cityData.bounds.maxX) / 2;
     const centerZ = (cityData.bounds.minZ + cityData.bounds.maxZ) / 2;
@@ -1143,7 +1383,7 @@ function CityScene({
 
   return (
     <>
-      <AnimatedCamera citySize={citySize} isFlat={growProgress === 0} />
+      <AnimatedCamera citySize={citySize} isFlat={growProgress === 0} focusTarget={focusTarget} />
 
       <ambientLight intensity={1.2} />
       <hemisphereLight
@@ -1182,13 +1422,12 @@ function CityScene({
         hoveredIndex={hoveredIndex}
         growProgress={growProgress}
         animationConfig={animationConfig}
-        highlightLayers={highlightLayers}
-        isolationMode={isolationMode}
-        hasActiveHighlights={activeHighlights}
-        dimOpacity={dimOpacity}
         heightScaling={heightScaling}
         linearScale={linearScale}
         staggerIndices={staggerIndices}
+        focusDirectory={buildingFocusDirectory}
+        highlightLayers={highlightLayers}
+        isolationMode={isolationMode}
       />
 
       <BuildingIcons
@@ -1249,6 +1488,10 @@ export interface FileCity3DProps {
   heightScaling?: HeightScaling;
   /** Scale factor for linear mode (height per line, default 0.05) */
   linearScale?: number;
+  /** Directory path to focus on - buildings outside will collapse */
+  focusDirectory?: string | null;
+  /** Callback when user clicks on a district to navigate */
+  onDirectorySelect?: (directory: string | null) => void;
 }
 
 /**
@@ -1276,6 +1519,8 @@ export function FileCity3D({
   emptyMessage = 'No file tree data available',
   heightScaling = 'logarithmic',
   linearScale = 0.05,
+  focusDirectory = null,
+  onDirectorySelect,
 }: FileCity3DProps) {
   const { theme } = useTheme();
   const [hoveredBuilding, setHoveredBuilding] = useState<CityBuilding | null>(
@@ -1392,9 +1637,9 @@ export function FileCity3D({
           animationConfig={animationConfig}
           highlightLayers={highlightLayers}
           isolationMode={isolationMode}
-          dimOpacity={dimOpacity}
           heightScaling={heightScaling}
           linearScale={linearScale}
+          focusDirectory={focusDirectory}
         />
       </Canvas>
       <InfoPanel building={hoveredBuilding} />