@principal-ai/file-city-react 0.5.16 → 0.5.18

package/dist/components/FileCity3D/FileCity3D.d.ts

@@ -168,6 +168,8 @@ export interface FileCity3DProps {
     textColor?: string;
     /** Currently selected building (controlled by host) */
     selectedBuilding?: CityBuilding | null;
+    /** When true, camera height adjusts based on tallest building when grown */
+    adaptCameraToBuildings?: boolean;
 }
 /**
  * FileCity3D - 3D visualization of codebase structure
@@ -175,6 +177,6 @@ export interface FileCity3DProps {
  * Renders CityData as an interactive 3D city where buildings represent files
  * and their height corresponds to line count or file size.
  */
-export declare function FileCity3D({ cityData, width, height, onBuildingClick, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls, highlightLayers, isolationMode, dimOpacity: _dimOpacity, isLoading, loadingMessage, emptyMessage, heightScaling, linearScale, focusDirectory, focusColor, onDirectorySelect: _onDirectorySelect, backgroundColor, textColor, selectedBuilding, }: FileCity3DProps): import("react/jsx-runtime").JSX.Element;
+export declare function FileCity3D({ cityData, width, height, onBuildingClick, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls, highlightLayers, isolationMode, dimOpacity: _dimOpacity, isLoading, loadingMessage, emptyMessage, heightScaling, linearScale, focusDirectory, focusColor, onDirectorySelect: _onDirectorySelect, backgroundColor, textColor, selectedBuilding, adaptCameraToBuildings, }: FileCity3DProps): import("react/jsx-runtime").JSX.Element;
 export default FileCity3D;
 //# sourceMappingURL=FileCity3D.d.ts.map

package/dist/components/FileCity3D/FileCity3D.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileCity3D.d.ts","sourceRoot":"","sources":["../../../src/components/FileCity3D/FileCity3D.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"FileCity3D.d.ts","sourceRoot":"","sources":["../../../src/components/FileCity3D/FileCity3D.tsx"],"names":[],"mappings":"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"}

package/dist/components/FileCity3D/FileCity3D.js

@@ -439,11 +439,11 @@ function InstancedBuildings({ buildings, centerOffset, onHover, onClick, hovered
                 })), growProgress: growProgress, minHeight: minHeight, baseOffset: baseOffset, springDuration: springDuration, heightMultipliersRef: heightMultipliersRef })] }));
 }
 function AnimatedIcon({ x, z, targetHeight, iconSize, texture, opacity, growProgress, staggerDelayMs, springDuration, }) {
-    const spriteRef = useRef(null);
+    const meshRef = useRef(null);
     const startTimeRef = useRef(null);
     const materialRef = useRef(null);
     useFrame(({ clock }) => {
-        if (!spriteRef.current)
+        if (!meshRef.current)
             return;
         if (startTimeRef.current === null && growProgress > 0) {
             startTimeRef.current = clock.elapsedTime * 1000;
@@ -465,13 +465,26 @@ function AnimatedIcon({ x, z, targetHeight, iconSize, texture, opacity, growProg
         const baseOffset = 0.2;
         const height = animProgress * targetHeight + minHeight;
         const buildingTop = height + baseOffset;
-        const yPosition = buildingTop + iconSize / 2 + 2;
-        spriteRef.current.position.y = yPosition;
+        // When flat (animProgress=0): icon lies flat at ground level
+        // When grown (animProgress=1): icon floats above building
+        const flatY = minHeight + baseOffset + 0.5;
+        const grownY = buildingTop + iconSize / 2 + 2;
+        const yPosition = flatY + (grownY - flatY) * animProgress;
+        meshRef.current.position.y = yPosition;
+        // Rotate from flat (facing up) to upright (facing camera-ish)
+        // Flat: -Math.PI / 2 (facing up)
+        // Grown: 0 (facing forward)
+        const flatRotationX = -Math.PI / 2;
+        const grownRotationX = 0;
+        meshRef.current.rotation.x = flatRotationX + (grownRotationX - flatRotationX) * animProgress;
         if (materialRef.current) {
-            materialRef.current.opacity = opacity * animProgress;
+            // Show icons even when flat, fade out only slightly
+            const minOpacity = 0.8;
+            const effectiveOpacity = minOpacity + (1 - minOpacity) * animProgress;
+            materialRef.current.opacity = opacity * effectiveOpacity;
         }
     });
-    return (_jsx("sprite", { ref: spriteRef, position: [x, 0, z], scale: [iconSize, iconSize, 1], raycast: () => null, children: _jsx("spriteMaterial", { ref: materialRef, map: texture, transparent: true, opacity: 0, depthTest: true, depthWrite: false }) }));
+    return (_jsxs("mesh", { ref: meshRef, position: [x, 0, z], scale: [iconSize, iconSize, 1], raycast: () => null, children: [_jsx("planeGeometry", { args: [1, 1] }), _jsx("meshBasicMaterial", { ref: materialRef, map: texture, transparent: true, opacity: 0.8, depthTest: true, depthWrite: false, side: THREE.DoubleSide })] }));
 }
 function BuildingIcons({ buildings, centerOffset, growProgress, heightScaling, linearScale, highlightLayers, isolationMode, hasActiveHighlights, staggerIndices, springDuration, staggerDelay, }) {
     // Pre-compute buildings with icons
@@ -516,9 +529,7 @@ function BuildingIcons({ buildings, centerOffset, growProgress, heightScaling, l
         staggerIndices,
         staggerDelay,
     ]);
-    // Don't render if no progress yet
-    if (growProgress < 0.1)
-        return null;
+    // Icons are now always rendered (flat or grown)
     return (_jsx(_Fragment, { children: buildingsWithIcons.map(({ building, config, x, z, targetHeight, shouldDim, staggerDelayMs }) => {
             const icon = config.icon;
             const texture = getIconTexture(icon.name, icon.color || '#ffffff');
@@ -526,14 +537,14 @@ function BuildingIcons({ buildings, centerOffset, growProgress, heightScaling, l
                 return null;
             // Icon size based on building dimensions
             const [width] = building.dimensions;
-            const baseSize = Math.max(width * 0.8, 6);
+            const baseSize = Math.max(width * 1.2, 8);
             const heightBoost = Math.min(targetHeight / 20, 3);
             const iconSize = (baseSize + heightBoost) * (icon.size || 1);
             const opacity = shouldDim && isolationMode === 'transparent' ? 0.3 : 1;
             return (_jsx(AnimatedIcon, { x: x, z: z, targetHeight: targetHeight, iconSize: iconSize, texture: texture, opacity: opacity, growProgress: growProgress, staggerDelayMs: staggerDelayMs, springDuration: springDuration }, building.path));
         }) }));
 }
-function DistrictFloor({ district, centerOffset, highlightColor }) {
+function DistrictFloor({ district, centerOffset, highlightColor, growProgress }) {
     const { worldBounds } = district;
     const width = worldBounds.maxX - worldBounds.minX;
     const depth = worldBounds.maxZ - worldBounds.minZ;
@@ -545,7 +556,19 @@ function DistrictFloor({ district, centerOffset, highlightColor }) {
     const borderColor = highlightColor || '#475569';
     const lineWidth = highlightColor ? 3 : 1;
     const labelColor = highlightColor || '#cbd5e1';
-    return (_jsxs("group", { position: [centerX, 0, centerZ], children: [_jsxs("lineSegments", { rotation: [-Math.PI / 2, 0, 0], position: [0, floorY, 0], renderOrder: -1, children: [_jsx("edgesGeometry", { args: [new THREE.PlaneGeometry(width, depth)], attach: "geometry" }), _jsx("lineBasicMaterial", { color: borderColor, linewidth: lineWidth, depthWrite: false })] }), highlightColor && (_jsxs("mesh", { rotation: [-Math.PI / 2, 0, 0], position: [0, floorY - 0.1, 0], renderOrder: -2, children: [_jsx("planeGeometry", { args: [width, depth] }), _jsx("meshBasicMaterial", { color: highlightColor, transparent: true, opacity: 0.15, depthWrite: false })] })), district.label && (_jsx(Text, { position: [0, 1.5, depth / 2 + 2], rotation: [-Math.PI / 6, 0, 0], fontSize: Math.min(3, width / 6), color: labelColor, anchorX: "center", anchorY: "middle", outlineWidth: 0.1, outlineColor: "#0f172a", children: dirName }))] }));
+    // Interpolate text rotation and position based on growProgress
+    // Flat: -Math.PI / 2 (facing up), positioned at center of district
+    // Grown: -Math.PI / 6 (angled), positioned at edge of district
+    const flatRotationX = -Math.PI / 2;
+    const grownRotationX = -Math.PI / 6;
+    const textRotationX = flatRotationX + (grownRotationX - flatRotationX) * growProgress;
+    const flatY = 0.5;
+    const grownY = 1.5;
+    const textY = flatY + (grownY - flatY) * growProgress;
+    const flatZ = 0; // Center of district when flat
+    const grownZ = depth / 2 + 2; // Edge of district when grown
+    const textZ = flatZ + (grownZ - flatZ) * growProgress;
+    return (_jsxs("group", { position: [centerX, 0, centerZ], children: [_jsxs("lineSegments", { rotation: [-Math.PI / 2, 0, 0], position: [0, floorY, 0], renderOrder: -1, children: [_jsx("edgesGeometry", { args: [new THREE.PlaneGeometry(width, depth)], attach: "geometry" }), _jsx("lineBasicMaterial", { color: borderColor, linewidth: lineWidth, depthWrite: false })] }), highlightColor && (_jsxs("mesh", { rotation: [-Math.PI / 2, 0, 0], position: [0, floorY - 0.1, 0], renderOrder: -2, children: [_jsx("planeGeometry", { args: [width, depth] }), _jsx("meshBasicMaterial", { color: highlightColor, transparent: true, opacity: 0.15, depthWrite: false })] })), district.label && (_jsx(Text, { position: [0, textY, textZ], rotation: [textRotationX, 0, 0], fontSize: Math.min(3, width / 6), color: labelColor, anchorX: "center", anchorY: "middle", outlineWidth: 0.1, outlineColor: "#0f172a", children: dirName }))] }));
 }
 let cameraApi = null;
 export function resetCamera() {
@@ -623,7 +646,7 @@ export function getCameraAngle() {
 export function getCameraTilt() {
     return cameraApi?.getCurrentTilt() ?? null;
 }
-function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }) {
+function AnimatedCamera({ citySize, isFlat, focusTarget, maxBuildingHeight = 0 }) {
     const { camera } = useThree();
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const controlsRef = useRef(null);
@@ -632,6 +655,7 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }) {
     const hasAppliedInitial = useRef(false);
     const frameCount = useRef(0);
     // Compute target camera position
+    // When flat, use a more top-down view; when grown, use an angled view
     const targetPos = useMemo(() => {
         if (focusTarget) {
             const distance = Math.max(focusTarget.size * 2, 50);
@@ -645,9 +669,15 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }) {
                 targetZ: focusTarget.z,
             };
         }
-        // Default overview
-        const targetHeight = citySize * 1.1;
-        const targetZ = citySize * 1.3;
+        // Default overview - adjust angle based on flat/grown state
+        // Flat: directly overhead (90 degrees, looking straight down)
+        // Grown: angled view to see building heights (optionally based on max building height)
+        const baseHeight = citySize * 1.1;
+        const buildingAwareHeight = maxBuildingHeight > 0
+            ? Math.max(baseHeight, maxBuildingHeight * 2.5)
+            : baseHeight;
+        const targetHeight = isFlat ? citySize * 2.0 : buildingAwareHeight;
+        const targetZ = isFlat ? 0.001 : citySize * 1.3; // Near-zero for top-down (tiny offset to avoid gimbal lock)
         return {
             x: 0,
             y: targetHeight,
@@ -656,7 +686,7 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }) {
             targetY: 0,
             targetZ: 0,
         };
-    }, [focusTarget, citySize]);
+    }, [focusTarget, citySize, isFlat, maxBuildingHeight]);
     // Spring animation for camera movement
     const [{ camX, camY, camZ, lookX, lookY, lookZ }, api] = useSpring(() => ({
         camX: targetPos.x,
@@ -1074,12 +1104,18 @@ function ControlsOverlay({ isFlat, onToggle, onResetCamera }) {
             gap: 8,
         }, children: [_jsx("button", { onClick: onResetCamera, style: buttonStyle, children: "Reset View" }), _jsx("button", { onClick: onToggle, style: buttonStyle, children: isFlat ? 'Grow to 3D' : 'Flatten to 2D' })] }));
 }
-function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding, selectedBuilding, growProgress, animationConfig, highlightLayers, isolationMode, heightScaling, linearScale, focusDirectory, focusColor, }) {
+function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding, selectedBuilding, growProgress, animationConfig, highlightLayers, isolationMode, heightScaling, linearScale, focusDirectory, focusColor, adaptCameraToBuildings = false, }) {
     const centerOffset = useMemo(() => ({
         x: (cityData.bounds.minX + cityData.bounds.maxX) / 2,
         z: (cityData.bounds.minZ + cityData.bounds.maxZ) / 2,
     }), [cityData.bounds]);
     const citySize = Math.max(cityData.bounds.maxX - cityData.bounds.minX, cityData.bounds.maxZ - cityData.bounds.minZ);
+    // Calculate max building height for camera positioning (when adaptCameraToBuildings is true)
+    const maxBuildingHeight = useMemo(() => {
+        if (!adaptCameraToBuildings)
+            return 0;
+        return Math.max(...cityData.buildings.map(b => b.dimensions[1]), 0);
+    }, [adaptCameraToBuildings, cityData.buildings]);
     const activeHighlights = useMemo(() => hasActiveHighlights(highlightLayers), [highlightLayers]);
     // Helper to check if a path is inside a directory
     const isPathInDirectory = useCallback((path, directory) => {
@@ -1262,7 +1298,7 @@ function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding
     const tension = animationConfig.tension || 120;
     const friction = animationConfig.friction || 14;
     const springDuration = Math.sqrt(1 / (tension * 0.001)) * friction * 20;
-    return (_jsxs(_Fragment, { children: [_jsx(AnimatedCamera, { citySize: citySize, isFlat: growProgress === 0, focusTarget: focusTarget }), _jsx("ambientLight", { intensity: 1.2 }), _jsx("hemisphereLight", { args: ['#ddeeff', '#667788', 0.8], position: [0, citySize, 0] }), _jsx("directionalLight", { position: [citySize, citySize * 1.5, citySize * 0.5], intensity: 2, castShadow: true, "shadow-mapSize": [2048, 2048] }), _jsx("directionalLight", { position: [-citySize * 0.5, citySize * 0.8, -citySize * 0.5], intensity: 1 }), _jsx("directionalLight", { position: [citySize * 0.3, citySize, citySize], intensity: 0.6 }), cityData.districts.map(district => {
+    return (_jsxs(_Fragment, { children: [_jsx(AnimatedCamera, { citySize: citySize, isFlat: growProgress === 0, focusTarget: focusTarget, maxBuildingHeight: maxBuildingHeight }), _jsx("ambientLight", { intensity: 1.2 }), _jsx("hemisphereLight", { args: ['#ddeeff', '#667788', 0.8], position: [0, citySize, 0] }), _jsx("directionalLight", { position: [citySize, citySize * 1.5, citySize * 0.5], intensity: 2, castShadow: true, "shadow-mapSize": [2048, 2048] }), _jsx("directionalLight", { position: [-citySize * 0.5, citySize * 0.8, -citySize * 0.5], intensity: 1 }), _jsx("directionalLight", { position: [citySize * 0.3, citySize, citySize], intensity: 0.6 }), cityData.districts.map(district => {
                 // Check if district matches focusDirectory
                 const isFocused = buildingFocusDirectory
                     ? district.path === buildingFocusDirectory
@@ -1284,7 +1320,7 @@ function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding
                 // Use buildingFocusColor (synced with animation) instead of focusColor prop
                 // Focus color takes priority, then highlight layer color
                 const districtColor = (isFocused && buildingFocusColor) ? buildingFocusColor : highlightLayerColor;
-                return (_jsx(DistrictFloor, { district: district, centerOffset: centerOffset, opacity: 1, highlightColor: districtColor }, district.path));
+                return (_jsx(DistrictFloor, { district: district, centerOffset: centerOffset, opacity: 1, highlightColor: districtColor, growProgress: growProgress }, district.path));
             }), _jsx(InstancedBuildings, { buildings: cityData.buildings, centerOffset: centerOffset, onHover: onBuildingHover, onClick: onBuildingClick, hoveredIndex: hoveredIndex, selectedIndex: selectedIndex, growProgress: growProgress, animationConfig: animationConfig, heightScaling: heightScaling, linearScale: linearScale, staggerIndices: staggerIndices, focusDirectory: buildingFocusDirectory, highlightLayers: highlightLayers, isolationMode: isolationMode }), _jsx(BuildingIcons, { buildings: cityData.buildings, centerOffset: centerOffset, growProgress: growProgress, heightScaling: heightScaling, linearScale: linearScale, highlightLayers: highlightLayers, isolationMode: isolationMode, hasActiveHighlights: activeHighlights, staggerIndices: staggerIndices, springDuration: springDuration, staggerDelay: animationConfig.staggerDelay || 15 })] }));
 }
 /**
@@ -1293,7 +1329,7 @@ function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding
  * Renders CityData as an interactive 3D city where buildings represent files
  * and their height corresponds to line count or file size.
  */
-export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingClick, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls = true, highlightLayers = [], isolationMode = 'transparent', dimOpacity: _dimOpacity = 0.15, isLoading = false, loadingMessage = 'Loading file city...', emptyMessage = 'No file tree data available', heightScaling = 'logarithmic', linearScale = 0.05, focusDirectory = null, focusColor = null, onDirectorySelect: _onDirectorySelect, backgroundColor = '#0f172a', textColor = '#94a3b8', selectedBuilding = null, }) {
+export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingClick, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls = true, highlightLayers = [], isolationMode = 'transparent', dimOpacity: _dimOpacity = 0.15, isLoading = false, loadingMessage = 'Loading file city...', emptyMessage = 'No file tree data available', heightScaling = 'logarithmic', linearScale = 0.05, focusDirectory = null, focusColor = null, onDirectorySelect: _onDirectorySelect, backgroundColor = '#0f172a', textColor = '#94a3b8', selectedBuilding = null, adaptCameraToBuildings = false, }) {
     const [hoveredBuilding, setHoveredBuilding] = useState(null);
     const [internalIsGrown, setInternalIsGrown] = useState(false);
     const animationConfig = useMemo(() => ({ ...DEFAULT_ANIMATION, ...animation }), [animation]);
@@ -1364,6 +1400,6 @@ export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingC
                     left: 0,
                     width: '100%',
                     height: '100%',
-                }, children: _jsx(CityScene, { cityData: cityData, onBuildingHover: setHoveredBuilding, onBuildingClick: onBuildingClick, hoveredBuilding: hoveredBuilding, selectedBuilding: selectedBuilding, growProgress: growProgress, animationConfig: animationConfig, highlightLayers: highlightLayers, isolationMode: isolationMode, heightScaling: heightScaling, linearScale: linearScale, focusDirectory: focusDirectory, focusColor: focusColor }) }), _jsx(InfoPanel, { building: selectedBuilding || hoveredBuilding }), showControls && (_jsx(ControlsOverlay, { isFlat: !isGrown, onToggle: handleToggle, onResetCamera: resetCamera }))] }));
+                }, children: _jsx(CityScene, { cityData: cityData, onBuildingHover: setHoveredBuilding, onBuildingClick: onBuildingClick, hoveredBuilding: hoveredBuilding, selectedBuilding: selectedBuilding, growProgress: growProgress, animationConfig: animationConfig, highlightLayers: highlightLayers, isolationMode: isolationMode, heightScaling: heightScaling, linearScale: linearScale, focusDirectory: focusDirectory, focusColor: focusColor, adaptCameraToBuildings: adaptCameraToBuildings }) }), _jsx(InfoPanel, { building: selectedBuilding || hoveredBuilding }), showControls && (_jsx(ControlsOverlay, { isFlat: !isGrown, onToggle: handleToggle, onResetCamera: resetCamera }))] }));
 }
 export default FileCity3D;

package/dist/components/FileCity3D/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * FileCity3D - 3D visualization component
  */
-export { FileCity3D, resetCamera, moveCameraTo, setCameraTarget, getCameraTarget, rotateCameraTo, rotateCameraBy, tiltCameraTo, tiltCameraBy, getCameraPosition, getCameraAngle, getCameraTilt } from './FileCity3D';
-export type { FileCity3DProps, AnimationConfig, HighlightLayer, HighlightItem, IsolationMode, HeightScaling, CityData, CityBuilding, CityDistrict, RotateOptions, } from './FileCity3D';
+export { FileCity3D, resetCamera, getCameraAngle, getCameraTarget, getCameraTilt, rotateCameraTo, rotateCameraBy, tiltCameraTo, tiltCameraBy, moveCameraTo, setCameraTarget, } from './FileCity3D';
+export type { FileCity3DProps, AnimationConfig, HighlightLayer, HighlightItem, IsolationMode, HeightScaling, CityData, CityBuilding, CityDistrict, } from './FileCity3D';
 //# sourceMappingURL=index.d.ts.map

package/dist/components/FileCity3D/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/FileCity3D/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACrN,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/FileCity3D/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/components/FileCity3D/index.js

@@ -1,4 +1,4 @@
 /**
  * FileCity3D - 3D visualization component
  */
-export { FileCity3D, resetCamera, moveCameraTo, setCameraTarget, getCameraTarget, rotateCameraTo, rotateCameraBy, tiltCameraTo, tiltCameraBy, getCameraPosition, getCameraAngle, getCameraTilt } from './FileCity3D';
+export { FileCity3D, resetCamera, getCameraAngle, getCameraTarget, getCameraTilt, rotateCameraTo, rotateCameraBy, tiltCameraTo, tiltCameraBy, moveCameraTo, setCameraTarget, } from './FileCity3D';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/file-city-react",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "type": "module",
   "description": "React components for File City visualization",
   "main": "dist/index.js",

package/src/components/FileCity3D/FileCity3D.tsx

@@ -745,12 +745,12 @@ function AnimatedIcon({
   staggerDelayMs,
   springDuration,
 }: AnimatedIconProps) {
-  const spriteRef = useRef<THREE.Sprite>(null);
+  const meshRef = useRef<THREE.Mesh>(null);
   const startTimeRef = useRef<number | null>(null);
-  const materialRef = useRef<THREE.SpriteMaterial>(null);
+  const materialRef = useRef<THREE.MeshBasicMaterial>(null);
 
   useFrame(({ clock }) => {
-    if (!spriteRef.current) return;
+    if (!meshRef.current) return;
 
     if (startTimeRef.current === null && growProgress > 0) {
       startTimeRef.current = clock.elapsedTime * 1000;
@@ -775,31 +775,48 @@ function AnimatedIcon({
     const baseOffset = 0.2;
     const height = animProgress * targetHeight + minHeight;
     const buildingTop = height + baseOffset;
-    const yPosition = buildingTop + iconSize / 2 + 2;
 
-    spriteRef.current.position.y = yPosition;
+    // When flat (animProgress=0): icon lies flat at ground level
+    // When grown (animProgress=1): icon floats above building
+    const flatY = minHeight + baseOffset + 0.5;
+    const grownY = buildingTop + iconSize / 2 + 2;
+    const yPosition = flatY + (grownY - flatY) * animProgress;
+
+    meshRef.current.position.y = yPosition;
+
+    // Rotate from flat (facing up) to upright (facing camera-ish)
+    // Flat: -Math.PI / 2 (facing up)
+    // Grown: 0 (facing forward)
+    const flatRotationX = -Math.PI / 2;
+    const grownRotationX = 0;
+    meshRef.current.rotation.x = flatRotationX + (grownRotationX - flatRotationX) * animProgress;
 
     if (materialRef.current) {
-      materialRef.current.opacity = opacity * animProgress;
+      // Show icons even when flat, fade out only slightly
+      const minOpacity = 0.8;
+      const effectiveOpacity = minOpacity + (1 - minOpacity) * animProgress;
+      materialRef.current.opacity = opacity * effectiveOpacity;
     }
   });
 
   return (
-    <sprite
-      ref={spriteRef}
+    <mesh
+      ref={meshRef}
       position={[x, 0, z]}
       scale={[iconSize, iconSize, 1]}
       raycast={() => null}
     >
-      <spriteMaterial
+      <planeGeometry args={[1, 1]} />
+      <meshBasicMaterial
         ref={materialRef}
         map={texture}
         transparent
-        opacity={0}
+        opacity={0.8}
         depthTest={true}
         depthWrite={false}
+        side={THREE.DoubleSide}
       />
-    </sprite>
+    </mesh>
   );
 }
 
@@ -871,9 +888,7 @@ function BuildingIcons({
     staggerDelay,
   ]);
 
-  // Don't render if no progress yet
-  if (growProgress < 0.1) return null;
-
+  // Icons are now always rendered (flat or grown)
   return (
     <>
       {buildingsWithIcons.map(
@@ -884,7 +899,7 @@ function BuildingIcons({
 
           // Icon size based on building dimensions
           const [width] = building.dimensions;
-          const baseSize = Math.max(width * 0.8, 6);
+          const baseSize = Math.max(width * 1.2, 8);
           const heightBoost = Math.min(targetHeight / 20, 3);
           const iconSize = (baseSize + heightBoost) * (icon.size || 1);
 
@@ -916,9 +931,10 @@ interface DistrictFloorProps {
   centerOffset: { x: number; z: number };
   opacity: number;
   highlightColor?: string | null;
+  growProgress: number;
 }
 
-function DistrictFloor({ district, centerOffset, highlightColor }: DistrictFloorProps) {
+function DistrictFloor({ district, centerOffset, highlightColor, growProgress }: DistrictFloorProps) {
   const { worldBounds } = district;
   const width = worldBounds.maxX - worldBounds.minX;
   const depth = worldBounds.maxZ - worldBounds.minZ;
@@ -934,6 +950,21 @@ function DistrictFloor({ district, centerOffset, highlightColor }: DistrictFloor
   const lineWidth = highlightColor ? 3 : 1;
   const labelColor = highlightColor || '#cbd5e1';
 
+  // Interpolate text rotation and position based on growProgress
+  // Flat: -Math.PI / 2 (facing up), positioned at center of district
+  // Grown: -Math.PI / 6 (angled), positioned at edge of district
+  const flatRotationX = -Math.PI / 2;
+  const grownRotationX = -Math.PI / 6;
+  const textRotationX = flatRotationX + (grownRotationX - flatRotationX) * growProgress;
+
+  const flatY = 0.5;
+  const grownY = 1.5;
+  const textY = flatY + (grownY - flatY) * growProgress;
+
+  const flatZ = 0; // Center of district when flat
+  const grownZ = depth / 2 + 2; // Edge of district when grown
+  const textZ = flatZ + (grownZ - flatZ) * growProgress;
+
   return (
     <group position={[centerX, 0, centerZ]}>
       {/* Border outline */}
@@ -952,8 +983,8 @@ function DistrictFloor({ district, centerOffset, highlightColor }: DistrictFloor
 
       {district.label && (
         <Text
-          position={[0, 1.5, depth / 2 + 2]}
-          rotation={[-Math.PI / 6, 0, 0]}
+          position={[0, textY, textZ]}
+          rotation={[textRotationX, 0, 0]}
           fontSize={Math.min(3, width / 6)}
           color={labelColor}
           anchorX="center"
@@ -979,6 +1010,7 @@ interface AnimatedCameraProps {
   citySize: number;
   isFlat: boolean;
   focusTarget?: FocusTarget | null;
+  maxBuildingHeight?: number;
 }
 
 // Camera rotation options
@@ -1096,7 +1128,7 @@ export function getCameraTilt() {
   return cameraApi?.getCurrentTilt() ?? null;
 }
 
-function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }: AnimatedCameraProps) {
+function AnimatedCamera({ citySize, isFlat, focusTarget, maxBuildingHeight = 0 }: AnimatedCameraProps) {
   const { camera } = useThree();
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const controlsRef = useRef<any>(null);
@@ -1106,6 +1138,7 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }: AnimatedCame
   const frameCount = useRef(0);
 
   // Compute target camera position
+  // When flat, use a more top-down view; when grown, use an angled view
   const targetPos = useMemo(() => {
     if (focusTarget) {
       const distance = Math.max(focusTarget.size * 2, 50);
@@ -1119,9 +1152,15 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }: AnimatedCame
         targetZ: focusTarget.z,
       };
     }
-    // Default overview
-    const targetHeight = citySize * 1.1;
-    const targetZ = citySize * 1.3;
+    // Default overview - adjust angle based on flat/grown state
+    // Flat: directly overhead (90 degrees, looking straight down)
+    // Grown: angled view to see building heights (optionally based on max building height)
+    const baseHeight = citySize * 1.1;
+    const buildingAwareHeight = maxBuildingHeight > 0
+      ? Math.max(baseHeight, maxBuildingHeight * 2.5)
+      : baseHeight;
+    const targetHeight = isFlat ? citySize * 2.0 : buildingAwareHeight;
+    const targetZ = isFlat ? 0.001 : citySize * 1.3; // Near-zero for top-down (tiny offset to avoid gimbal lock)
     return {
       x: 0,
       y: targetHeight,
@@ -1130,7 +1169,7 @@ function AnimatedCamera({ citySize, isFlat: _isFlat, focusTarget }: AnimatedCame
       targetY: 0,
       targetZ: 0,
     };
-  }, [focusTarget, citySize]);
+  }, [focusTarget, citySize, isFlat, maxBuildingHeight]);
 
   // Spring animation for camera movement
   const [{ camX, camY, camZ, lookX, lookY, lookZ }, api] = useSpring(() => ({
@@ -1695,6 +1734,7 @@ interface CitySceneProps {
   linearScale: number;
   focusDirectory: string | null;
   focusColor?: string | null;
+  adaptCameraToBuildings?: boolean;
 }
 
 function CityScene({
@@ -1711,6 +1751,7 @@ function CityScene({
   linearScale,
   focusDirectory,
   focusColor,
+  adaptCameraToBuildings = false,
 }: CitySceneProps) {
   const centerOffset = useMemo(
     () => ({
@@ -1725,6 +1766,12 @@ function CityScene({
     cityData.bounds.maxZ - cityData.bounds.minZ,
   );
 
+  // Calculate max building height for camera positioning (when adaptCameraToBuildings is true)
+  const maxBuildingHeight = useMemo(() => {
+    if (!adaptCameraToBuildings) return 0;
+    return Math.max(...cityData.buildings.map(b => b.dimensions[1]), 0);
+  }, [adaptCameraToBuildings, cityData.buildings]);
+
   const activeHighlights = useMemo(() => hasActiveHighlights(highlightLayers), [highlightLayers]);
 
   // Helper to check if a path is inside a directory
@@ -1956,7 +2003,7 @@ function CityScene({
 
   return (
     <>
-      <AnimatedCamera citySize={citySize} isFlat={growProgress === 0} focusTarget={focusTarget} />
+      <AnimatedCamera citySize={citySize} isFlat={growProgress === 0} focusTarget={focusTarget} maxBuildingHeight={maxBuildingHeight} />
 
       <ambientLight intensity={1.2} />
       <hemisphereLight args={['#ddeeff', '#667788', 0.8]} position={[0, citySize, 0]} />
@@ -2002,6 +2049,7 @@ function CityScene({
             centerOffset={centerOffset}
             opacity={1}
             highlightColor={districtColor}
+            growProgress={growProgress}
           />
         );
       })}
@@ -2093,6 +2141,8 @@ export interface FileCity3DProps {
   textColor?: string;
   /** Currently selected building (controlled by host) */
   selectedBuilding?: CityBuilding | null;
+  /** When true, camera height adjusts based on tallest building when grown */
+  adaptCameraToBuildings?: boolean;
 }
 
 /**
@@ -2126,6 +2176,7 @@ export function FileCity3D({
   backgroundColor = '#0f172a',
   textColor = '#94a3b8',
   selectedBuilding = null,
+  adaptCameraToBuildings = false,
 }: FileCity3DProps) {
   const [hoveredBuilding, setHoveredBuilding] = useState<CityBuilding | null>(null);
   const [internalIsGrown, setInternalIsGrown] = useState(false);
@@ -2241,6 +2292,7 @@ export function FileCity3D({
           linearScale={linearScale}
           focusDirectory={focusDirectory}
           focusColor={focusColor}
+          adaptCameraToBuildings={adaptCameraToBuildings}
         />
       </Canvas>
       <InfoPanel building={selectedBuilding || hoveredBuilding} />

package/src/components/FileCity3D/index.ts

@@ -2,7 +2,19 @@
  * FileCity3D - 3D visualization component
  */
 
-export { FileCity3D, resetCamera, moveCameraTo, setCameraTarget, getCameraTarget, rotateCameraTo, rotateCameraBy, tiltCameraTo, tiltCameraBy, getCameraPosition, getCameraAngle, getCameraTilt } from './FileCity3D';
+export {
+  FileCity3D,
+  resetCamera,
+  getCameraAngle,
+  getCameraTarget,
+  getCameraTilt,
+  rotateCameraTo,
+  rotateCameraBy,
+  tiltCameraTo,
+  tiltCameraBy,
+  moveCameraTo,
+  setCameraTarget,
+} from './FileCity3D';
 export type {
   FileCity3DProps,
   AnimationConfig,
@@ -13,5 +25,4 @@ export type {
   CityData,
   CityBuilding,
   CityDistrict,
-  RotateOptions,
 } from './FileCity3D';

package/src/stories/FileCity3D.stories.tsx

@@ -2001,3 +2001,134 @@ export const CameraControls: Story = {
     },
   },
 };
+
+/**
+ * 2D to 3D Transition - Tests the camera angle adjustment when transitioning from flat to grown
+ * Camera starts top-down when flat, then animates to an angled view when buildings grow
+ */
+const FlatToGrownTransitionTemplate: React.FC = () => {
+  const [isGrown, setIsGrown] = React.useState(false);
+  const [autoTransition, setAutoTransition] = React.useState(false);
+  const [adaptCamera, setAdaptCamera] = React.useState(true);
+
+  // Auto-transition effect (simulates the CodeCityPanel behavior)
+  React.useEffect(() => {
+    if (!autoTransition) return;
+    setIsGrown(false);
+    const timer = setTimeout(() => {
+      setIsGrown(true);
+    }, 600);
+    return () => clearTimeout(timer);
+  }, [autoTransition]);
+
+  return (
+    <div style={{ height: '100vh', display: 'flex', flexDirection: 'column', position: 'relative' }}>
+      {/* 3D City */}
+      <FileCity3D
+        cityData={sampleCityData}
+        height="100%"
+        heightScaling="linear"
+        linearScale={0.5}
+        isGrown={isGrown}
+        adaptCameraToBuildings={adaptCamera}
+        animation={{
+          startFlat: true,
+          autoStartDelay: null, // External control
+          staggerDelay: 15,
+          tension: 120,
+          friction: 14,
+        }}
+        showControls={true}
+      />
+
+      {/* Control panel */}
+      <div
+        style={{
+          position: 'absolute',
+          bottom: 0,
+          left: 0,
+          right: 0,
+          zIndex: 100,
+          background: 'rgba(15, 23, 42, 0.95)',
+          borderTop: '1px solid #334155',
+          padding: '16px 24px',
+        }}
+      >
+        <div style={{ display: 'flex', gap: '16px', alignItems: 'center', justifyContent: 'center' }}>
+          <div style={{ color: '#94a3b8', fontSize: '14px' }}>
+            State: <strong style={{ color: isGrown ? '#22c55e' : '#f59e0b' }}>{isGrown ? 'GROWN' : 'FLAT'}</strong>
+          </div>
+          <button
+            onClick={() => setIsGrown(false)}
+            style={{
+              padding: '8px 16px',
+              background: !isGrown ? '#3b82f6' : '#1e293b',
+              color: 'white',
+              border: '1px solid #334155',
+              borderRadius: '6px',
+              cursor: 'pointer',
+            }}
+          >
+            Flatten (2D)
+          </button>
+          <button
+            onClick={() => setIsGrown(true)}
+            style={{
+              padding: '8px 16px',
+              background: isGrown ? '#3b82f6' : '#1e293b',
+              color: 'white',
+              border: '1px solid #334155',
+              borderRadius: '6px',
+              cursor: 'pointer',
+            }}
+          >
+            Grow (3D)
+          </button>
+          <button
+            onClick={() => {
+              setAutoTransition(false);
+              setTimeout(() => setAutoTransition(true), 10);
+            }}
+            style={{
+              padding: '8px 16px',
+              background: '#7c3aed',
+              color: 'white',
+              border: '1px solid #334155',
+              borderRadius: '6px',
+              cursor: 'pointer',
+            }}
+          >
+            Simulate 2D→3D Transition
+          </button>
+          <label style={{ display: 'flex', alignItems: 'center', gap: '6px', color: '#94a3b8', fontSize: '14px', cursor: 'pointer' }}>
+            <input
+              type="checkbox"
+              checked={adaptCamera}
+              onChange={(e) => setAdaptCamera(e.target.checked)}
+              style={{ cursor: 'pointer' }}
+            />
+            Adapt to building heights
+          </label>
+        </div>
+        <div style={{ color: '#64748b', fontSize: '12px', textAlign: 'center', marginTop: '8px' }}>
+          Camera should start top-down when flat, then animate to angled view when grown.
+          {adaptCamera && ' Camera height will adjust based on tallest building.'}
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export const FlatToGrownTransition: Story = {
+  render: () => <FlatToGrownTransitionTemplate />,
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Tests the camera angle adjustment when transitioning between flat (2D) and grown (3D) states. ' +
+          'The camera should start with a top-down view when buildings are flat, then animate to an angled view when buildings grow. ' +
+          'Use "Simulate 2D→3D Transition" to test the full transition sequence as it happens in CodeCityPanel.',
+      },
+    },
+  },
+};