@principal-ai/file-city-react 0.5.42 → 0.5.44

package/src/components/FileCity3D/FileCity3D.tsx

@@ -41,6 +41,32 @@ declare module 'react' {
 export type { CityData, CityBuilding, CityDistrict, LayerItem, LayerRenderStrategy };
 export type HighlightLayer = BuilderHighlightLayer;
 
+/** Visual style for the `selectedPath` ring on a directory. */
+export interface SelectionStyle {
+  /** Ring color. Defaults to the theme accent. */
+  color?: string;
+  /** Ring border width in world units. Default: 2. */
+  borderWidth?: number;
+}
+
+/**
+ * Per-frame camera callback signature. Fires once per R3F render frame from
+ * inside the Canvas, so projection done in the callback is in lockstep with
+ * the city render — useful for HTML/SVG overlays that need to track world
+ * positions (e.g. leader lines anchored to buildings).
+ *
+ * The callback receives the live `THREE.Camera` and the current canvas
+ * size in CSS pixels. To project a world point to canvas-local pixels:
+ *
+ *   const v = new THREE.Vector3(x, y, z).project(camera);
+ *   const px = (v.x *  0.5 + 0.5) * size.width;
+ *   const py = (v.y * -0.5 + 0.5) * size.height;
+ */
+export type OnCameraFrame = (
+  camera: THREE.Camera,
+  size: { width: number; height: number },
+) => void;
+
 /** What to do with non-highlighted buildings */
 export type IsolationMode =
   | 'none' // Show all buildings normally
@@ -710,7 +736,7 @@ function BorderHighlights({
   return (
     <instancedMesh ref={meshRef} args={[undefined, undefined, borderEdgeData.length]} frustumCulled={false}>
       <boxGeometry args={[1, 1, 1]} />
-      <meshBasicMaterial transparent opacity={0.9} vertexColors />
+      <meshBasicMaterial transparent opacity={0.9} />
     </instancedMesh>
   );
 }
@@ -735,6 +761,7 @@ interface InstancedBuildingsProps {
   focusDirectory: string | null;
   highlightLayers: HighlightLayer[];
   isolationMode: IsolationMode;
+  defaultBuildingColor?: string;
 }
 
 // Helper to check if a path is inside a directory
@@ -759,6 +786,7 @@ function InstancedBuildings({
   focusDirectory,
   highlightLayers,
   isolationMode,
+  defaultBuildingColor,
 }: InstancedBuildingsProps) {
   const meshRef = useRef<THREE.InstancedMesh>(null);
   const startTimeRef = useRef<number | null>(null);
@@ -844,7 +872,7 @@ function InstancedBuildings({
       // Get all layer matches and find first fill match for building color
       const matches = getLayerMatchesForPath(building.path, highlightLayers);
       const fillMatch = matches.find(m => m.renderStrategy === 'fill');
-      const color = fillMatch?.color ?? getColorForFile(building);
+      const color = fillMatch?.color ?? defaultBuildingColor ?? getColorForFile(building);
 
       const x = building.position.x - centerOffset.x;
       const z = building.position.z - centerOffset.z;
@@ -873,6 +901,7 @@ function InstancedBuildings({
     staggerIndices,
     animationConfig.staggerDelay,
     highlightLayers,
+    defaultBuildingColor,
   ]);
 
   const minHeight = 0.3;
@@ -1529,6 +1558,19 @@ export function getCameraTilt() {
   return cameraApi?.getCurrentTilt() ?? null;
 }
 
+/**
+ * Bridge for piping the live camera + canvas size out of the R3F Canvas on
+ * every frame. Mounted as a child of `<Canvas>` so it has access to the R3F
+ * render loop; runs zero work if no callback is provided.
+ */
+function CameraFrameBridge({ onCameraFrame }: { onCameraFrame?: OnCameraFrame }) {
+  const { camera, size } = useThree();
+  useFrame(() => {
+    onCameraFrame?.(camera, { width: size.width, height: size.height });
+  });
+  return null;
+}
+
 const AnimatedCamera = React.memo(function AnimatedCamera({
   citySize,
   isFlat,
@@ -2394,6 +2436,279 @@ function ControlsOverlay({ isFlat, onToggle, onResetCamera, onLookDown }: Contro
   );
 }
 
+// Distance (world units) the panel lifts upward when dismissed. Reads as
+// "toward the camera" because the camera looks down in flat mode.
+const PANEL_DISMISS_LIFT = 60;
+
+interface ElevatedScopePanelMeshProps {
+  panel: ElevatedScopePanel;
+  centerOffset: { x: number; z: number };
+  dismissing: boolean;
+  onDismissed?: (id: string) => void;
+}
+
+// Dismiss animation duration in seconds.
+const PANEL_DISMISS_DURATION = 0.7;
+
+function ElevatedScopePanelMesh({
+  panel,
+  centerOffset,
+  dismissing,
+  onDismissed,
+}: ElevatedScopePanelMeshProps) {
+  const cx = (panel.bounds.minX + panel.bounds.maxX) / 2 - centerOffset.x;
+  const cz = (panel.bounds.minZ + panel.bounds.maxZ) / 2 - centerOffset.z;
+  const w = Math.max(1, panel.bounds.maxX - panel.bounds.minX);
+  const d = Math.max(1, panel.bounds.maxZ - panel.bounds.minZ);
+  const t = panel.thickness ?? 2;
+  const y = (panel.height ?? 4) + t / 2;
+  const baseOpacity = panel.opacity ?? 1;
+  const isOpaqueStatic = baseOpacity >= 1;
+  const topY = y + t / 2;
+  const tileMax = Math.min(w, d) / 2;
+  const requested = panel.labelSize ?? Math.min(w, d) / 6;
+  const labelSize = Math.max(4, Math.min(tileMax, requested));
+
+  // Drive the dismiss animation directly via useFrame + Three.js refs
+  // rather than react-spring. React re-renders (e.g., from FileCity3D's
+  // hover state on mouse-move) were disturbing the spring-driven
+  // animation; mutating the Three.js objects directly keeps the
+  // animation isolated from React's render cycle.
+  const groupRef = useRef<THREE.Group>(null);
+  const slabMaterialRef = useRef<THREE.MeshBasicMaterial>(null);
+  const labelMaterialRefs = useRef<THREE.MeshBasicMaterial[]>([]);
+  const startTimeRef = useRef<number | null>(null);
+  const finishedRef = useRef(false);
+  const [fullyDismissed, setFullyDismissed] = useState(false);
+
+  useFrame(({ clock }) => {
+    if (!dismissing || finishedRef.current) return;
+    if (startTimeRef.current === null) {
+      startTimeRef.current = clock.elapsedTime;
+    }
+    const elapsed = clock.elapsedTime - startTimeRef.current;
+    const t = Math.min(elapsed / PANEL_DISMISS_DURATION, 1);
+    // ease-out cubic
+    const eased = 1 - Math.pow(1 - t, 3);
+
+    if (groupRef.current) {
+      groupRef.current.position.y = eased * PANEL_DISMISS_LIFT;
+    }
+    const opacityNow = baseOpacity * (1 - eased);
+    if (slabMaterialRef.current) {
+      slabMaterialRef.current.opacity = opacityNow;
+    }
+    for (const mat of labelMaterialRefs.current) {
+      if (mat) mat.opacity = opacityNow;
+    }
+
+    if (t >= 1) {
+      finishedRef.current = true;
+      setFullyDismissed(true);
+      onDismissed?.(panel.id);
+    }
+  });
+
+  if (fullyDismissed) return null;
+
+  // Always transparent on the slab so animated opacity actually blends.
+  // (Three.js skips alpha blending entirely when transparent=false, which
+  // makes the fade invisible until the prop flips mid-animation.)
+  // depthWrite stays true while the panel is at full opacity so it still
+  // occludes buildings beneath; we drop it once dismissal starts so the
+  // fading panel doesn't punch a hole in the scene.
+  const slabDepthWrite = isOpaqueStatic && !dismissing;
+
+  const interactive = Boolean(panel.onClick || panel.onDoubleClick);
+  const handleClick = panel.onClick
+    ? (e: ThreeEvent<MouseEvent>) => {
+        e.stopPropagation();
+        panel.onClick!(e.nativeEvent);
+      }
+    : undefined;
+  const handleDoubleClick = panel.onDoubleClick
+    ? (e: ThreeEvent<MouseEvent>) => {
+        e.stopPropagation();
+        panel.onDoubleClick!(e.nativeEvent);
+      }
+    : undefined;
+  const handlePointerOver = interactive
+    ? (e: ThreeEvent<PointerEvent>) => {
+        e.stopPropagation();
+        document.body.style.cursor = 'pointer';
+      }
+    : undefined;
+  const handlePointerOut = interactive
+    ? () => {
+        document.body.style.cursor = '';
+      }
+    : undefined;
+
+  const labelColor = panel.labelColor ?? '#ffffff';
+  const displayLabelColor = panel.displayLabelColor ?? panel.labelColor ?? '#ffffff';
+
+  // Reset the array each render — the ref callbacks below will repopulate
+  // it. This avoids stale entries if labels come and go.
+  labelMaterialRefs.current = [];
+  const captureLabelMat = (mat: THREE.MeshBasicMaterial | null) => {
+    if (mat) labelMaterialRefs.current.push(mat);
+  };
+
+  return (
+    <group ref={groupRef}>
+      <mesh
+        position={[cx, y, cz]}
+        renderOrder={10}
+        onClick={dismissing ? undefined : handleClick}
+        onDoubleClick={dismissing ? undefined : handleDoubleClick}
+        onPointerOver={dismissing ? undefined : handlePointerOver}
+        onPointerOut={dismissing ? undefined : handlePointerOut}
+      >
+        <boxGeometry args={[w, t, d]} />
+        <meshBasicMaterial
+          ref={slabMaterialRef}
+          color={panel.color}
+          transparent
+          opacity={baseOpacity}
+          depthWrite={slabDepthWrite}
+        />
+      </mesh>
+      {panel.displayLabel && (
+        <>
+          <Text
+            position={[cx, topY + 0.05, cz - labelSize * 0.6]}
+            rotation={[-Math.PI / 2, 0, 0]}
+            fontSize={labelSize}
+            color={displayLabelColor}
+            anchorX="center"
+            anchorY="middle"
+            maxWidth={w * 0.9}
+            textAlign="center"
+            renderOrder={11}
+            frustumCulled={false}
+          >
+            {panel.displayLabel}
+            <meshBasicMaterial
+              ref={captureLabelMat}
+              attach="material"
+              color={displayLabelColor}
+              depthWrite={false}
+              depthTest={false}
+              transparent
+              opacity={baseOpacity}
+            />
+          </Text>
+          <mesh
+            position={[cx, topY + 0.06, cz - labelSize * 0.05]}
+            rotation={[-Math.PI / 2, 0, 0]}
+            renderOrder={11}
+          >
+            <planeGeometry
+              args={[
+                Math.min(w * 0.9, panel.displayLabel.length * labelSize * 0.55),
+                labelSize * 0.06,
+              ]}
+            />
+            <meshBasicMaterial
+              ref={captureLabelMat}
+              color={displayLabelColor}
+              depthWrite={false}
+              depthTest={false}
+              transparent
+              opacity={baseOpacity}
+            />
+          </mesh>
+        </>
+      )}
+      {panel.label && (
+        <Text
+          position={[cx, topY + 0.05, cz + (panel.displayLabel ? labelSize * 0.6 : 0)]}
+          rotation={[-Math.PI / 2, 0, 0]}
+          fontSize={labelSize}
+          color={labelColor}
+          anchorX="center"
+          anchorY="middle"
+          maxWidth={w * 0.9}
+          textAlign="center"
+          renderOrder={11}
+          frustumCulled={false}
+        >
+          {panel.label}
+          <meshBasicMaterial
+            ref={captureLabelMat}
+            attach="material"
+            color={labelColor}
+            depthWrite={false}
+            depthTest={false}
+            transparent
+            opacity={baseOpacity}
+          />
+        </Text>
+      )}
+    </group>
+  );
+}
+
+interface SelectionRingProps {
+  district: CityDistrict;
+  centerOffset: { x: number; z: number };
+  color: string;
+  borderWidth: number;
+  growProgress: number;
+}
+
+// Lifted just above the default umbrella topY (height 4 + thickness 2 → 6)
+// so the ring isn't occluded by an `ElevatedScopePanel` covering the same
+// district when the city is flat.
+const SELECTION_RING_FLAT_Y = 7;
+
+function SelectionRing({
+  district,
+  centerOffset,
+  color,
+  borderWidth,
+  growProgress,
+}: SelectionRingProps) {
+  const { worldBounds } = district;
+  const inflate = 1;
+  const minX = worldBounds.minX - inflate;
+  const maxX = worldBounds.maxX + inflate;
+  const minZ = worldBounds.minZ - inflate;
+  const maxZ = worldBounds.maxZ + inflate;
+  const cx = (minX + maxX) / 2 - centerOffset.x;
+  const cz = (minZ + maxZ) / 2 - centerOffset.z;
+  const w = maxX - minX;
+  const d = maxZ - minZ;
+
+  const pathDepth = district.path.split('/').length;
+  const groundY = -5 - pathDepth * 0.1 + 0.2;
+  const y = SELECTION_RING_FLAT_Y + (groundY - SELECTION_RING_FLAT_Y) * growProgress;
+
+  const t = Math.max(0.5, borderWidth);
+  const barH = 0.5;
+
+  return (
+    <group position={[cx, y, cz]}>
+      <mesh position={[0, 0, -d / 2]} renderOrder={20}>
+        <boxGeometry args={[w + t, barH, t]} />
+        <meshBasicMaterial color={color} transparent opacity={0.95} />
+      </mesh>
+      <mesh position={[0, 0, d / 2]} renderOrder={20}>
+        <boxGeometry args={[w + t, barH, t]} />
+        <meshBasicMaterial color={color} transparent opacity={0.95} />
+      </mesh>
+      <mesh position={[-w / 2, 0, 0]} renderOrder={20}>
+        <boxGeometry args={[t, barH, d + t]} />
+        <meshBasicMaterial color={color} transparent opacity={0.95} />
+      </mesh>
+      <mesh position={[w / 2, 0, 0]} renderOrder={20}>
+        <boxGeometry args={[t, barH, d + t]} />
+        <meshBasicMaterial color={color} transparent opacity={0.95} />
+      </mesh>
+    </group>
+  );
+}
+
 // Main scene component
 interface CitySceneProps {
   cityData: CityData;
@@ -2401,6 +2716,8 @@ interface CitySceneProps {
   onBuildingClick?: (building: CityBuilding, event: MouseEvent) => void;
   hoveredBuilding: CityBuilding | null;
   selectedBuilding: CityBuilding | null;
+  selectedDistrict: CityDistrict | null;
+  selectionStyle?: SelectionStyle;
   growProgress: number;
   animationConfig: AnimationConfig;
   highlightLayers: HighlightLayer[];
@@ -2412,7 +2729,10 @@ interface CitySceneProps {
   focusColor?: string | null;
   adaptCameraToBuildings?: boolean;
   elevatedScopePanels?: ElevatedScopePanel[];
+  dismissingPanelIds?: ReadonlySet<string>;
+  onPanelDismissed?: (id: string) => void;
   cameraControls?: CameraControlsConfig;
+  defaultBuildingColor?: string;
 }
 
 function CityScene({
@@ -2421,6 +2741,8 @@ function CityScene({
   onBuildingClick,
   hoveredBuilding,
   selectedBuilding,
+  selectedDistrict,
+  selectionStyle,
   growProgress,
   animationConfig,
   highlightLayers,
@@ -2432,7 +2754,10 @@ function CityScene({
   focusColor,
   adaptCameraToBuildings = false,
   elevatedScopePanels,
+  dismissingPanelIds,
+  onPanelDismissed,
   cameraControls,
+  defaultBuildingColor,
   onCameraReady,
 }: CitySceneProps & { onCameraReady?: () => void }) {
   const centerOffset = useMemo(
@@ -2739,6 +3064,7 @@ function CityScene({
         focusDirectory={buildingFocusDirectory}
         highlightLayers={highlightLayers}
         isolationMode={isolationMode}
+        defaultBuildingColor={defaultBuildingColor}
       />
 
       <BuildingIcons
@@ -2754,137 +3080,25 @@ function CityScene({
       />
 
       {growProgress === 0 &&
-        elevatedScopePanels?.map(panel => {
-          const cx = (panel.bounds.minX + panel.bounds.maxX) / 2 - centerOffset.x;
-          const cz = (panel.bounds.minZ + panel.bounds.maxZ) / 2 - centerOffset.z;
-          const w = Math.max(1, panel.bounds.maxX - panel.bounds.minX);
-          const d = Math.max(1, panel.bounds.maxZ - panel.bounds.minZ);
-          const t = panel.thickness ?? 2;
-          const y = (panel.height ?? 4) + t / 2;
-          const opacity = panel.opacity ?? 1;
-          const isOpaque = opacity >= 1;
-          const topY = y + t / 2;
-          // Size text to the panel: roughly fit longest reasonable label,
-          // clamped so tiny tiles still render legibly and huge ones don't
-          // get absurd. Callers may override via panel.labelSize, but we
-          // still cap to the tile footprint so the label fits.
-          const tileMax = Math.min(w, d) / 2;
-          const requested = panel.labelSize ?? Math.min(w, d) / 6;
-          const labelSize = Math.max(4, Math.min(tileMax, requested));
-
-          const interactive = Boolean(panel.onClick || panel.onDoubleClick);
-          const handleClick = panel.onClick
-            ? (e: ThreeEvent<MouseEvent>) => {
-                e.stopPropagation();
-                panel.onClick!(e.nativeEvent);
-              }
-            : undefined;
-          const handleDoubleClick = panel.onDoubleClick
-            ? (e: ThreeEvent<MouseEvent>) => {
-                e.stopPropagation();
-                panel.onDoubleClick!(e.nativeEvent);
-              }
-            : undefined;
-          const handlePointerOver = interactive
-            ? (e: ThreeEvent<PointerEvent>) => {
-                e.stopPropagation();
-                document.body.style.cursor = 'pointer';
-              }
-            : undefined;
-          const handlePointerOut = interactive
-            ? () => {
-                document.body.style.cursor = '';
-              }
-            : undefined;
-
-          return (
-            <group key={panel.id}>
-              <mesh
-                position={[cx, y, cz]}
-                renderOrder={10}
-                onClick={handleClick}
-                onDoubleClick={handleDoubleClick}
-                onPointerOver={handlePointerOver}
-                onPointerOut={handlePointerOut}
-              >
-                <boxGeometry args={[w, t, d]} />
-                <meshBasicMaterial
-                  color={panel.color}
-                  transparent={!isOpaque}
-                  opacity={opacity}
-                  depthWrite={isOpaque}
-                />
-              </mesh>
-              {panel.displayLabel && (
-                <>
-                  <Text
-                    position={[cx, topY + 0.05, cz - labelSize * 0.6]}
-                    rotation={[-Math.PI / 2, 0, 0]}
-                    fontSize={labelSize}
-                    color={panel.displayLabelColor ?? panel.labelColor ?? '#ffffff'}
-                    anchorX="center"
-                    anchorY="middle"
-                    maxWidth={w * 0.9}
-                    textAlign="center"
-                    renderOrder={11}
-                    frustumCulled={false}
-                  >
-                    {panel.displayLabel}
-                    <meshBasicMaterial
-                      attach="material"
-                      color={panel.displayLabelColor ?? panel.labelColor ?? '#ffffff'}
-                      depthWrite={false}
-                      depthTest={false}
-                    />
-                  </Text>
-                  {/* Underline rendered as a thin plane just below the
-                      displayLabel. Width approximated from character count
-                      (~0.55em advance) and clamped to the panel footprint. */}
-                  <mesh
-                    position={[cx, topY + 0.06, cz - labelSize * 0.05]}
-                    rotation={[-Math.PI / 2, 0, 0]}
-                    renderOrder={11}
-                  >
-                    <planeGeometry
-                      args={[
-                        Math.min(w * 0.9, panel.displayLabel.length * labelSize * 0.55),
-                        labelSize * 0.06,
-                      ]}
-                    />
-                    <meshBasicMaterial
-                      color={panel.displayLabelColor ?? panel.labelColor ?? '#ffffff'}
-                      depthWrite={false}
-                      depthTest={false}
-                      transparent
-                    />
-                  </mesh>
-                </>
-              )}
-              {panel.label && (
-                <Text
-                  position={[cx, topY + 0.05, cz + (panel.displayLabel ? labelSize * 0.6 : 0)]}
-                  rotation={[-Math.PI / 2, 0, 0]}
-                  fontSize={labelSize}
-                  color={panel.labelColor ?? '#ffffff'}
-                  anchorX="center"
-                  anchorY="middle"
-                  maxWidth={w * 0.9}
-                  textAlign="center"
-                  renderOrder={11}
-                  frustumCulled={false}
-                >
-                  {panel.label}
-                  <meshBasicMaterial
-                    attach="material"
-                    color={panel.labelColor ?? '#ffffff'}
-                    depthWrite={false}
-                    depthTest={false}
-                  />
-                </Text>
-              )}
-            </group>
-          );
-        })}
+        elevatedScopePanels?.map(panel => (
+          <ElevatedScopePanelMesh
+            key={panel.id}
+            panel={panel}
+            centerOffset={centerOffset}
+            dismissing={dismissingPanelIds?.has(panel.id) ?? false}
+            onDismissed={onPanelDismissed}
+          />
+        ))}
+
+      {selectedDistrict && (
+        <SelectionRing
+          district={selectedDistrict}
+          centerOffset={centerOffset}
+          color={selectionStyle?.color ?? '#facc15'}
+          borderWidth={selectionStyle?.borderWidth ?? 2}
+          growProgress={growProgress}
+        />
+      )}
     </>
   );
 }
@@ -2902,6 +3116,8 @@ export interface FileCity3DProps {
   height?: number | string;
   /** Callback when a building is clicked */
   onBuildingClick?: (building: CityBuilding, event: MouseEvent) => void;
+  /** Callback when the hovered building changes (fires with null on hover-out) */
+  onBuildingHover?: (building: CityBuilding | null) => void;
   /** CSS class name */
   className?: string;
   /** Inline styles */
@@ -2942,20 +3158,58 @@ export interface FileCity3DProps {
   backgroundColor?: string;
   /** Text color for secondary/placeholder text */
   textColor?: string;
-  /** Currently selected building (controlled by host) */
+  /**
+   * @deprecated Use `selectedPath` instead. When both are set, `selectedPath`
+   * wins. This prop will be removed in a future release.
+   */
   selectedBuilding?: CityBuilding | null;
+
+  /**
+   * Path of the selected building or directory. The component resolves the
+   * path against `cityData.buildings` (file selection — emphasizes the
+   * building and shows the InfoPanel) and `cityData.districts` (directory
+   * selection — draws a ring around the district). When both `selectedPath`
+   * and `selectedBuilding` are set, `selectedPath` wins.
+   */
+  selectedPath?: string | null;
+
+  /** Visual style for the directory selection ring drawn for `selectedPath`. */
+  selectionStyle?: SelectionStyle;
   /** When true, camera height adjusts based on tallest building when grown */
   adaptCameraToBuildings?: boolean;
 
   /** Base file type color layers (resolved with highlightLayers) */
   fileColorLayers?: HighlightLayer[];
 
+  /**
+   * Override the per-building color fallback. When unset (default), buildings
+   * not matched by a fill highlight layer are colored by file extension via
+   * the built-in file-type palette. Set to a CSS color (e.g. `'#475569'`) to
+   * render unmatched buildings in a neutral tone — useful for debug stories
+   * that want to isolate highlight-layer rendering.
+   */
+  defaultBuildingColor?: string;
+
   /**
    * Translucent slabs rendered above the city showing scope coverage as
    * elevated planes over the directories they own.
    */
   elevatedScopePanels?: ElevatedScopePanel[];
 
+  /**
+   * Set of panel ids that should play the "lift up and fade out" dismiss
+   * animation. Add an id here to start the animation; once it settles,
+   * `onPanelDismissed` fires so the host can drop the panel from
+   * `elevatedScopePanels`.
+   */
+  dismissingPanelIds?: ReadonlySet<string>;
+
+  /**
+   * Fires once a panel's dismiss animation has settled. The host should
+   * remove the id from both `dismissingPanelIds` and `elevatedScopePanels`.
+   */
+  onPanelDismissed?: (id: string) => void;
+
   /**
    * Configure how mouse / trackpad / touch input drives the camera.
    * Defaults match Google Maps style: left-drag pans, right-drag rotates,
@@ -2965,6 +3219,15 @@ export interface FileCity3DProps {
    * Memoize this object to avoid unnecessary camera re-mounts.
    */
   cameraControls?: CameraControlsConfig;
+
+  /**
+   * Fires once per R3F render frame with the live camera and canvas size.
+   * Use to project world points to canvas pixels for HTML/SVG overlays that
+   * need to track buildings as the camera pans / zooms / rotates.
+   *
+   * Memoize the callback to avoid re-mounting the bridge.
+   */
+  onCameraFrame?: OnCameraFrame;
 }
 
 /**
@@ -2978,6 +3241,7 @@ export function FileCity3D({
   width = '100%',
   height = 600,
   onBuildingClick,
+  onBuildingHover,
   className,
   style,
   animation,
@@ -2985,6 +3249,8 @@ export function FileCity3D({
   onGrowChange,
   showControls = false,
   elevatedScopePanels,
+  dismissingPanelIds,
+  onPanelDismissed,
   highlightLayers: externalHighlightLayers,
   isolationMode: externalIsolationMode,
   dimOpacity: _dimOpacity = 0.15,
@@ -3000,14 +3266,26 @@ export function FileCity3D({
   backgroundColor = '#0f172a',
   textColor = '#94a3b8',
   selectedBuilding = null,
+  selectedPath = null,
+  selectionStyle,
   adaptCameraToBuildings = false,
   fileColorLayers,
+  defaultBuildingColor,
   cameraControls,
+  onCameraFrame,
 }: FileCity3DProps) {
   const [hoveredBuilding, setHoveredBuilding] = useState<CityBuilding | null>(null);
   const [internalIsGrown, setInternalIsGrown] = useState(false);
   const [cameraReady, setCameraReady] = useState(false);
 
+  const handleBuildingHover = useCallback(
+    (building: CityBuilding | null) => {
+      setHoveredBuilding(building);
+      onBuildingHover?.(building);
+    },
+    [onBuildingHover],
+  );
+
   const animationConfig = useMemo(() => ({ ...DEFAULT_ANIMATION, ...animation }), [animation]);
 
   // ============================================================================
@@ -3045,6 +3323,22 @@ export function FileCity3D({
   const focusColor = resolved.focusColor;
   const isolationMode = resolved.isolationMode as IsolationMode;
 
+  // `selectedPath` wins over the deprecated `selectedBuilding` when both are
+  // set. A path resolves to either a building (file selection) or a district
+  // (directory selection) — never both.
+  const resolvedSelection = useMemo<{
+    building: CityBuilding | null;
+    district: CityDistrict | null;
+  }>(() => {
+    if (selectedPath != null) {
+      const building = cityData.buildings.find(b => b.path === selectedPath) ?? null;
+      if (building) return { building, district: null };
+      const district = cityData.districts.find(d => d.path === selectedPath) ?? null;
+      return { building: null, district };
+    }
+    return { building: selectedBuilding ?? null, district: null };
+  }, [selectedPath, selectedBuilding, cityData.buildings, cityData.districts]);
+
   const isGrown = externalIsGrown !== undefined ? externalIsGrown : internalIsGrown;
   const setIsGrown = (value: boolean) => {
     setInternalIsGrown(value);
@@ -3145,10 +3439,12 @@ export function FileCity3D({
       >
         <CityScene
           cityData={cityData}
-          onBuildingHover={setHoveredBuilding}
+          onBuildingHover={handleBuildingHover}
           onBuildingClick={onBuildingClick}
           hoveredBuilding={hoveredBuilding}
-          selectedBuilding={selectedBuilding}
+          selectedBuilding={resolvedSelection.building}
+          selectedDistrict={resolvedSelection.district}
+          selectionStyle={selectionStyle}
           growProgress={growProgress}
           animationConfig={animationConfig}
           highlightLayers={highlightLayers}
@@ -3160,11 +3456,15 @@ export function FileCity3D({
           focusColor={focusColor}
           adaptCameraToBuildings={adaptCameraToBuildings}
           elevatedScopePanels={elevatedScopePanels}
+          dismissingPanelIds={dismissingPanelIds}
+          onPanelDismissed={onPanelDismissed}
           cameraControls={cameraControls}
+          defaultBuildingColor={defaultBuildingColor}
           onCameraReady={() => setCameraReady(true)}
         />
+        {onCameraFrame && <CameraFrameBridge onCameraFrame={onCameraFrame} />}
       </Canvas>
-      <InfoPanel building={selectedBuilding} />
+      <InfoPanel building={resolvedSelection.building} />
       {showControls && (
         <ControlsOverlay
           isFlat={!isGrown}