@principal-ai/file-city-react 0.5.37 → 0.5.38

package/src/components/FileCity3D/FileCity3D.tsx

@@ -11,7 +11,7 @@ import React, { useMemo, useRef, useState, useEffect, useCallback } from 'react'
 import { Canvas, useFrame, ThreeEvent, useThree } from '@react-three/fiber';
 
 import { useSpring } from '@react-spring/three';
-import { OrbitControls, PerspectiveCamera, Text } from '@react-three/drei';
+import { MapControls, PerspectiveCamera, Text } from '@react-three/drei';
 import { getFileConfig } from '@principal-ai/file-city-builder';
 import type {
   CityData,
@@ -65,6 +65,33 @@ export interface AnimationConfig {
 /** Height scaling mode for buildings */
 export type HeightScaling = 'logarithmic' | 'linear';
 
+/**
+ * An opaque slab rendered above the flat city to visualize scope coverage.
+ * Only renders when the city is in 2D (flat) mode — in 3D the buildings show
+ * through normally. When opaque, the slab's depth value occludes buildings and
+ * icons beneath its `bounds`, so the scope reads as a single colored tile.
+ */
+export interface ElevatedScopePanel {
+  /** Unique identifier (used as React key) */
+  id: string;
+  /** Hex color */
+  color: string;
+  /** 0–1 opacity. Default 1 (fully opaque). */
+  opacity?: number;
+  /** Y position (world units) above the ground when flat. Default 4. */
+  height?: number;
+  /** Slab thickness in world units (default 2) */
+  thickness?: number;
+  /** World-space bounds the slab covers */
+  bounds: { minX: number; maxX: number; minZ: number; maxZ: number };
+  /** Optional label rendered flat on top of the slab. */
+  label?: string;
+  /** Hex color for the label (default white). */
+  labelColor?: string;
+  /** Click handler. When set, the slab becomes interactive and shows a pointer cursor. */
+  onClick?: () => void;
+}
+
 /** Pattern for files that should render flat (e.g., lock files, generated files) */
 export interface FlatPattern {
   /** Glob-like pattern or regex to match file paths */
@@ -1308,6 +1335,7 @@ interface AnimatedCameraProps {
   isFlat: boolean;
   focusTarget?: FocusTarget | null;
   maxBuildingHeight?: number;
+  cameraControls?: CameraControlsConfig;
 }
 
 // Camera rotation options
@@ -1316,6 +1344,69 @@ export interface RotateOptions {
   duration?: number;
 }
 
+export type MouseDragAction = 'pan' | 'rotate' | 'zoom' | 'none';
+export type TouchOneAction = 'pan' | 'rotate' | 'none';
+export type TouchTwoAction = 'pan' | 'rotate' | 'dolly-pan' | 'dolly-rotate' | 'none';
+export type WheelAction = 'zoom' | 'pan';
+
+export interface CameraControlsConfig {
+  /** Left mouse button drag. Default: 'pan' */
+  leftDrag?: MouseDragAction;
+  /** Right mouse button drag. Default: 'rotate' */
+  rightDrag?: MouseDragAction;
+  /** Middle mouse button drag. Default: 'zoom' */
+  middleDrag?: MouseDragAction;
+  /** Mouse wheel / two-finger trackpad scroll. Default: 'zoom'.
+   *  When 'pan', ctrl/⌘+wheel still zooms (matches trackpad pinch). */
+  wheel?: WheelAction;
+  /** One-finger touch. Default: 'pan' */
+  oneFingerTouch?: TouchOneAction;
+  /** Two-finger touch. Default: 'dolly-pan' */
+  twoFingerTouch?: TouchTwoAction;
+  /** Pan speed multiplier. Default: 1 */
+  panSpeed?: number;
+  /** Rotate speed multiplier. Default: 1 */
+  rotateSpeed?: number;
+  /** Zoom speed multiplier. Default: 1 */
+  zoomSpeed?: number;
+}
+
+export const DEFAULT_CAMERA_CONTROLS: Required<Omit<CameraControlsConfig, 'panSpeed' | 'rotateSpeed' | 'zoomSpeed'>> & Pick<CameraControlsConfig, 'panSpeed' | 'rotateSpeed' | 'zoomSpeed'> = {
+  leftDrag: 'pan',
+  rightDrag: 'rotate',
+  middleDrag: 'zoom',
+  wheel: 'pan',
+  oneFingerTouch: 'pan',
+  twoFingerTouch: 'dolly-pan',
+};
+
+function mouseAction(action: MouseDragAction): number | undefined {
+  switch (action) {
+    case 'pan': return THREE.MOUSE.PAN;
+    case 'rotate': return THREE.MOUSE.ROTATE;
+    case 'zoom': return THREE.MOUSE.DOLLY;
+    case 'none': return undefined;
+  }
+}
+
+function touchOneAction(action: TouchOneAction): number | undefined {
+  switch (action) {
+    case 'pan': return THREE.TOUCH.PAN;
+    case 'rotate': return THREE.TOUCH.ROTATE;
+    case 'none': return undefined;
+  }
+}
+
+function touchTwoAction(action: TouchTwoAction): number | undefined {
+  switch (action) {
+    case 'pan': return THREE.TOUCH.PAN;
+    case 'rotate': return THREE.TOUCH.ROTATE;
+    case 'dolly-pan': return THREE.TOUCH.DOLLY_PAN;
+    case 'dolly-rotate': return THREE.TOUCH.DOLLY_ROTATE;
+    case 'none': return undefined;
+  }
+}
+
 // Camera control API - populated by AnimatedCamera
 interface CameraApi {
   reset: () => void;
@@ -1430,11 +1521,17 @@ const AnimatedCamera = React.memo(function AnimatedCamera({
   isFlat,
   focusTarget,
   maxBuildingHeight = 0,
+  cameraControls,
   onCameraReady,
 }: AnimatedCameraProps & { onCameraReady?: () => void }) {
   // Use selector to only subscribe to camera, not the entire R3F state
   // This prevents re-renders on pointer movement
   const camera = useThree((state) => state.camera);
+  const gl = useThree((state) => state.gl);
+  const controlsConfig = useMemo(
+    () => ({ ...DEFAULT_CAMERA_CONTROLS, ...cameraControls }),
+    [cameraControls],
+  );
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const controlsRef = useRef<any>(null);
   const isAnimatingRef = useRef(false);
@@ -1686,7 +1783,7 @@ const AnimatedCamera = React.memo(function AnimatedCamera({
 
       // Convert tilt angle to polar angle (0° tilt = looking down, 90° tilt = level)
       // Clamp to avoid extreme angles
-      const clampedTilt = Math.max(5, Math.min(85, currentTilt));
+      const clampedTilt = Math.max(0, Math.min(85, currentTilt));
       const polarRadians = (clampedTilt * Math.PI) / 180;
       const azimuthRadians = (azimuthAngle * Math.PI) / 180;
 
@@ -2000,26 +2097,99 @@ const AnimatedCamera = React.memo(function AnimatedCamera({
     };
   }, [resetToInitial, moveTo, setTarget, rotateTo, rotateBy, tiltTo, tiltBy, getCurrentPosition, getCurrentTarget, getCurrentAngle, getCurrentTilt]);
 
+  // Custom wheel handler for wheel === 'pan'. We disable MapControls' built-in
+  // zoom (otherwise it competes with our handler) and handle both axes here:
+  // ctrl/⌘+wheel = zoom (matches trackpad pinch), plain wheel = pan along the
+  // camera-relative ground plane.
+  useEffect(() => {
+    if (controlsConfig.wheel !== 'pan') return;
+    const canvas = gl.domElement;
+    const right = new THREE.Vector3();
+    const forward = new THREE.Vector3();
+    const offset = new THREE.Vector3();
+    const direction = new THREE.Vector3();
+    const panSpeed = controlsConfig.panSpeed ?? 1;
+    const zoomSpeed = controlsConfig.zoomSpeed ?? 1;
+
+    const onWheel = (e: WheelEvent) => {
+      const controls = controlsRef.current;
+      if (!controls) return;
+      e.preventDefault();
+      const target = controls.target as THREE.Vector3;
+
+      if (e.ctrlKey || e.metaKey) {
+        direction.subVectors(camera.position, target);
+        const distance = direction.length();
+        const scale = Math.exp(e.deltaY * 0.01 * zoomSpeed);
+        const minD = controls.minDistance ?? 0;
+        const maxD = controls.maxDistance ?? Infinity;
+        const newDistance = Math.min(Math.max(distance * scale, minD), maxD);
+        direction.normalize().multiplyScalar(newDistance);
+        camera.position.copy(target).add(direction);
+        controls.update();
+        return;
+      }
+
+      const distance = camera.position.distanceTo(target);
+      const factor = distance * 0.0015 * panSpeed;
+
+      camera.getWorldDirection(forward);
+      forward.y = 0;
+      if (forward.lengthSq() < 1e-6) forward.set(0, 0, -1);
+      forward.normalize();
+      right.crossVectors(forward, camera.up).normalize();
+
+      offset.set(0, 0, 0);
+      offset.addScaledVector(right, e.deltaX * factor);
+      offset.addScaledVector(forward, -e.deltaY * factor);
+
+      camera.position.add(offset);
+      target.add(offset);
+      controls.update();
+    };
+
+    canvas.addEventListener('wheel', onWheel, { passive: false });
+    return () => canvas.removeEventListener('wheel', onWheel);
+  }, [camera, gl, controlsConfig.wheel, controlsConfig.panSpeed, controlsConfig.zoomSpeed]);
+
+  const mouseButtons = useMemo(() => ({
+    LEFT: mouseAction(controlsConfig.leftDrag),
+    MIDDLE: mouseAction(controlsConfig.middleDrag),
+    RIGHT: mouseAction(controlsConfig.rightDrag),
+  }), [controlsConfig.leftDrag, controlsConfig.middleDrag, controlsConfig.rightDrag]);
+
+  const touches = useMemo(() => ({
+    ONE: touchOneAction(controlsConfig.oneFingerTouch),
+    TWO: touchTwoAction(controlsConfig.twoFingerTouch),
+  }), [controlsConfig.oneFingerTouch, controlsConfig.twoFingerTouch]);
+
   return (
     <>
       <PerspectiveCamera makeDefault fov={50} near={1} far={citySize * 10} />
-      <OrbitControls
+      <MapControls
         ref={controlsRef}
         enableDamping
         dampingFactor={0.05}
         minDistance={10}
         maxDistance={citySize * 3}
         maxPolarAngle={Math.PI / 2.1}
+        mouseButtons={mouseButtons}
+        touches={touches}
+        enableZoom={controlsConfig.wheel !== 'pan'}
+        panSpeed={controlsConfig.panSpeed ?? 1}
+        rotateSpeed={controlsConfig.rotateSpeed ?? 1}
+        zoomSpeed={controlsConfig.zoomSpeed ?? 1}
       />
     </>
   );
 }, (prevProps, nextProps) => {
-  // Custom comparison: only re-render if isFlat, citySize, or maxBuildingHeight changes
+  // Custom comparison: only re-render if isFlat, citySize, maxBuildingHeight, or cameraControls changes
   // Skip re-render when only focusTarget changes (handled internally by useEffect on isFlat)
   return (
     prevProps.isFlat === nextProps.isFlat &&
     prevProps.citySize === nextProps.citySize &&
-    prevProps.maxBuildingHeight === nextProps.maxBuildingHeight
+    prevProps.maxBuildingHeight === nextProps.maxBuildingHeight &&
+    prevProps.cameraControls === nextProps.cameraControls
   );
 });
 
@@ -2039,7 +2209,7 @@ function InfoPanel({ building }: InfoPanelProps) {
       style={{
         position: 'absolute',
         bottom: 16,
-        left: 16,
+        left: 60,
         background: 'rgba(15, 23, 42, 0.9)',
         border: '1px solid #334155',
         borderRadius: 8,
@@ -2076,9 +2246,10 @@ interface ControlsOverlayProps {
   isFlat: boolean;
   onToggle: () => void;
   onResetCamera: () => void;
+  onLookDown: () => void;
 }
 
-function ControlsOverlay({ isFlat, onToggle, onResetCamera }: ControlsOverlayProps) {
+function ControlsOverlay({ isFlat, onToggle, onResetCamera, onLookDown }: ControlsOverlayProps) {
   const buttonStyle = {
     background: 'rgba(15, 23, 42, 0.9)',
     border: '1px solid #334155',
@@ -2123,6 +2294,20 @@ function ControlsOverlay({ isFlat, onToggle, onResetCamera }: ControlsOverlayPro
       >
         ↻
       </button>
+
+      {/* Look Down - Bottom Left */}
+      <button
+        onClick={onLookDown}
+        style={{
+          ...buttonStyle,
+          position: 'absolute',
+          bottom: 8,
+          left: 8,
+        }}
+        title="Look down"
+      >
+        ⬇
+      </button>
     </>
   );
 }
@@ -2144,6 +2329,8 @@ interface CitySceneProps {
   focusDirectory: string | null;
   focusColor?: string | null;
   adaptCameraToBuildings?: boolean;
+  elevatedScopePanels?: ElevatedScopePanel[];
+  cameraControls?: CameraControlsConfig;
 }
 
 function CityScene({
@@ -2162,6 +2349,8 @@ function CityScene({
   focusDirectory,
   focusColor,
   adaptCameraToBuildings = false,
+  elevatedScopePanels,
+  cameraControls,
   onCameraReady,
 }: CitySceneProps & { onCameraReady?: () => void }) {
   const centerOffset = useMemo(
@@ -2381,6 +2570,7 @@ function CityScene({
         isFlat={growProgress === 0}
         focusTarget={focusTarget}
         maxBuildingHeight={maxBuildingHeight}
+        cameraControls={cameraControls}
         onCameraReady={onCameraReady}
       />
 
@@ -2462,6 +2652,81 @@ function CityScene({
         isolationMode={isolationMode}
         hasActiveHighlights={activeHighlights}
       />
+
+      {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.
+          const labelSize = Math.max(4, Math.min(24, Math.min(w, d) / 6));
+
+          const handleClick = panel.onClick
+            ? (e: ThreeEvent<MouseEvent>) => {
+                e.stopPropagation();
+                panel.onClick!();
+              }
+            : undefined;
+          const handlePointerOver = panel.onClick
+            ? (e: ThreeEvent<PointerEvent>) => {
+                e.stopPropagation();
+                document.body.style.cursor = 'pointer';
+              }
+            : undefined;
+          const handlePointerOut = panel.onClick
+            ? () => {
+                document.body.style.cursor = '';
+              }
+            : undefined;
+
+          return (
+            <group key={panel.id}>
+              <mesh
+                position={[cx, y, cz]}
+                renderOrder={10}
+                onClick={handleClick}
+                onPointerOver={handlePointerOver}
+                onPointerOut={handlePointerOut}
+              >
+                <boxGeometry args={[w, t, d]} />
+                <meshBasicMaterial
+                  color={panel.color}
+                  transparent={!isOpaque}
+                  opacity={opacity}
+                  depthWrite={isOpaque}
+                />
+              </mesh>
+              {panel.label && (
+                <Text
+                  position={[cx, topY + 0.05, cz]}
+                  rotation={[-Math.PI / 2, 0, 0]}
+                  fontSize={labelSize}
+                  color={panel.labelColor ?? '#ffffff'}
+                  anchorX="center"
+                  anchorY="middle"
+                  maxWidth={w * 0.9}
+                  textAlign="center"
+                  renderOrder={11}
+                >
+                  {panel.label}
+                  <meshBasicMaterial
+                    attach="material"
+                    color={panel.labelColor ?? '#ffffff'}
+                    depthWrite={false}
+                  />
+                </Text>
+              )}
+            </group>
+          );
+        })}
     </>
   );
 }
@@ -2526,6 +2791,22 @@ export interface FileCity3DProps {
 
   /** Base file type color layers (resolved with highlightLayers) */
   fileColorLayers?: HighlightLayer[];
+
+  /**
+   * Translucent slabs rendered above the city showing scope coverage as
+   * elevated planes over the directories they own.
+   */
+  elevatedScopePanels?: ElevatedScopePanel[];
+
+  /**
+   * Configure how mouse / trackpad / touch input drives the camera.
+   * Defaults match Google Maps style: left-drag pans, right-drag rotates,
+   * wheel zooms. Set `wheel: 'pan'` to make trackpad two-finger scroll pan
+   * (ctrl/⌘+wheel still zooms so pinch-zoom keeps working).
+   *
+   * Memoize this object to avoid unnecessary camera re-mounts.
+   */
+  cameraControls?: CameraControlsConfig;
 }
 
 /**
@@ -2545,6 +2826,7 @@ export function FileCity3D({
   isGrown: externalIsGrown,
   onGrowChange,
   showControls = false,
+  elevatedScopePanels,
   highlightLayers: externalHighlightLayers,
   isolationMode: externalIsolationMode,
   dimOpacity: _dimOpacity = 0.15,
@@ -2562,6 +2844,7 @@ export function FileCity3D({
   selectedBuilding = null,
   adaptCameraToBuildings = false,
   fileColorLayers,
+  cameraControls,
 }: FileCity3DProps) {
   const [hoveredBuilding, setHoveredBuilding] = useState<CityBuilding | null>(null);
   const [internalIsGrown, setInternalIsGrown] = useState(false);
@@ -2718,12 +3001,19 @@ export function FileCity3D({
           focusDirectory={focusDirectory}
           focusColor={focusColor}
           adaptCameraToBuildings={adaptCameraToBuildings}
+          elevatedScopePanels={elevatedScopePanels}
+          cameraControls={cameraControls}
           onCameraReady={() => setCameraReady(true)}
         />
       </Canvas>
       <InfoPanel building={selectedBuilding} />
       {showControls && (
-        <ControlsOverlay isFlat={!isGrown} onToggle={handleToggle} onResetCamera={resetCamera} />
+        <ControlsOverlay
+          isFlat={!isGrown}
+          onToggle={handleToggle}
+          onResetCamera={resetCamera}
+          onLookDown={() => tiltCameraTo(0)}
+        />
       )}
     </div>
   );

package/src/components/FileCity3D/index.ts

@@ -15,6 +15,7 @@ export {
   moveCameraTo,
   setCameraTarget,
   DEFAULT_FLAT_PATTERNS,
+  DEFAULT_CAMERA_CONTROLS,
 } from './FileCity3D';
 export type {
   FileCity3DProps,
@@ -25,7 +26,13 @@ export type {
   IsolationMode,
   HeightScaling,
   FlatPattern,
+  ElevatedScopePanel,
   CityData,
   CityBuilding,
   CityDistrict,
+  CameraControlsConfig,
+  MouseDragAction,
+  TouchOneAction,
+  TouchTwoAction,
+  WheelAction,
 } from './FileCity3D';

package/src/index.ts

@@ -80,6 +80,7 @@ export type {
   IsolationMode,
   HeightScaling,
   FlatPattern,
+  ElevatedScopePanel,
 } from './components/FileCity3D';
 
 // Re-export HighlightLayer from FileCity3D with distinct name to avoid conflict