@principal-ai/file-city-react 0.5.43 → 0.5.45

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

@@ -8,6 +8,7 @@
  */
 import React from 'react';
 import type { CityData, CityBuilding, CityDistrict, HighlightLayer as BuilderHighlightLayer, LayerItem, LayerRenderStrategy } from '@principal-ai/file-city-builder';
+import * as THREE from 'three';
 import type { ThreeElements } from '@react-three/fiber';
 declare module 'react' {
     namespace JSX {
@@ -24,6 +25,23 @@ export interface SelectionStyle {
     /** 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' | 'transparent' | 'collapse' | 'hide';
 export interface AnimationConfig {
@@ -125,6 +143,13 @@ export interface CameraControlsConfig {
 export declare const DEFAULT_CAMERA_CONTROLS: Required<Omit<CameraControlsConfig, 'panSpeed' | 'rotateSpeed' | 'zoomSpeed'>> & Pick<CameraControlsConfig, 'panSpeed' | 'rotateSpeed' | 'zoomSpeed'>;
 export declare function resetCamera(): void;
 export declare function moveCameraTo(x: number, z: number, size?: number): void;
+/**
+ * Position the camera straight overhead a target at a specific height (flat
+ * top-down view). Use to fit the city inside a sub-rect of the canvas — e.g.
+ * when overlays cover part of the viewport. Larger `height` = city appears
+ * smaller; smaller `height` = zoomed in.
+ */
+export declare function setCameraFlatView(x: number, z: number, height: number, options?: RotateOptions): void;
 /**
  * Set the camera's look-at target (center point for orbiting).
  * Camera maintains its current distance and angles relative to the new target.
@@ -254,6 +279,14 @@ export interface FileCity3DProps {
     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.
@@ -280,6 +313,14 @@ 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;
 }
 /**
  * FileCity3D - 3D visualization of codebase structure
@@ -287,6 +328,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, onBuildingHover, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls, elevatedScopePanels, dismissingPanelIds, onPanelDismissed, highlightLayers: externalHighlightLayers, isolationMode: externalIsolationMode, dimOpacity: _dimOpacity, isLoading, loadingMessage, emptyMessage, heightScaling, linearScale, flatPatterns, focusDirectory: externalFocusDirectory, focusColor: externalFocusColor, onDirectorySelect: _onDirectorySelect, backgroundColor, textColor, selectedBuilding, selectedPath, selectionStyle, adaptCameraToBuildings, fileColorLayers, cameraControls, }: FileCity3DProps): import("react/jsx-runtime").JSX.Element;
+export declare function FileCity3D({ cityData, width, height, onBuildingClick, onBuildingHover, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls, elevatedScopePanels, dismissingPanelIds, onPanelDismissed, highlightLayers: externalHighlightLayers, isolationMode: externalIsolationMode, dimOpacity: _dimOpacity, isLoading, loadingMessage, emptyMessage, heightScaling, linearScale, flatPatterns, focusDirectory: externalFocusDirectory, focusColor: externalFocusColor, onDirectorySelect: _onDirectorySelect, backgroundColor, textColor, selectedBuilding, selectedPath, selectionStyle, adaptCameraToBuildings, fileColorLayers, defaultBuildingColor, cameraControls, onCameraFrame, }: 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

@@ -430,7 +430,7 @@ function BorderHighlights({ buildings, centerOffset, highlightLayers, growProgre
     });
     if (borderEdgeData.length === 0)
         return null;
-    return (_jsxs("instancedMesh", { ref: meshRef, args: [undefined, undefined, borderEdgeData.length], frustumCulled: false, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx("meshBasicMaterial", { transparent: true, opacity: 0.9, vertexColors: true })] }));
+    return (_jsxs("instancedMesh", { ref: meshRef, args: [undefined, undefined, borderEdgeData.length], frustumCulled: false, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx("meshBasicMaterial", { transparent: true, opacity: 0.9 })] }));
 }
 // Helper to check if a path is inside a directory
 function isPathInDirectory(path, directory) {
@@ -438,7 +438,7 @@ function isPathInDirectory(path, directory) {
         return true;
     return path === directory || path.startsWith(directory + '/');
 }
-function InstancedBuildings({ buildings, centerOffset, onHover, onClick, hoveredIndex, selectedIndex, growProgress, animationConfig, heightScaling, linearScale, flatPatterns, staggerIndices, focusDirectory, highlightLayers, isolationMode, }) {
+function InstancedBuildings({ buildings, centerOffset, onHover, onClick, hoveredIndex, selectedIndex, growProgress, animationConfig, heightScaling, linearScale, flatPatterns, staggerIndices, focusDirectory, highlightLayers, isolationMode, defaultBuildingColor, }) {
     const meshRef = useRef(null);
     const startTimeRef = useRef(null);
     const tempObject = useMemo(() => new THREE.Object3D(), []);
@@ -515,7 +515,7 @@ function InstancedBuildings({ buildings, centerOffset, onHover, onClick, hovered
             // 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;
             const staggerIndex = staggerIndices[index] ?? index;
@@ -541,6 +541,7 @@ function InstancedBuildings({ buildings, centerOffset, onHover, onClick, hovered
         staggerIndices,
         animationConfig.staggerDelay,
         highlightLayers,
+        defaultBuildingColor,
     ]);
     const minHeight = 0.3;
     const baseOffset = 0.2;
@@ -817,6 +818,15 @@ export function resetCamera() {
 export function moveCameraTo(x, z, size) {
     cameraApi?.moveTo(x, z, size);
 }
+/**
+ * Position the camera straight overhead a target at a specific height (flat
+ * top-down view). Use to fit the city inside a sub-rect of the canvas — e.g.
+ * when overlays cover part of the viewport. Larger `height` = city appears
+ * smaller; smaller `height` = zoomed in.
+ */
+export function setCameraFlatView(x, z, height, options) {
+    cameraApi?.setFlatView(x, z, height, options);
+}
 /**
  * Set the camera's look-at target (center point for orbiting).
  * Camera maintains its current distance and angles relative to the new target.
@@ -886,6 +896,18 @@ export function getCameraAngle() {
 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 }) {
+    const { camera, size } = useThree();
+    useFrame(() => {
+        onCameraFrame?.(camera, { width: size.width, height: size.height });
+    });
+    return null;
+}
 const AnimatedCamera = React.memo(function AnimatedCamera({ citySize, isFlat, focusTarget, maxBuildingHeight = 0, cameraControls, onCameraReady, }) {
     // Use selector to only subscribe to camera, not the entire R3F state
     // This prevents re-renders on pointer movement
@@ -1219,6 +1241,36 @@ const AnimatedCamera = React.memo(function AnimatedCamera({ citySize, isFlat, fo
             lookZ: z,
         });
     }, [citySize, api]);
+    // Position the camera directly above a target at a given height (flat /
+    // top-down view). Useful for fitting the city into a visible sub-rect of
+    // the canvas — raise `height` to make the city appear smaller, lower it to
+    // zoom in. Pairs with `setTarget` for pan-only changes.
+    const setFlatView = useCallback((x, z, height, options) => {
+        // MapControls (drag/wheel) mutates camera.position and controls.target
+        // directly without touching our spring. If we don't resync first, a
+        // call here can no-op when the spring's stored values happen to equal
+        // the requested target even though the visible camera is elsewhere.
+        if (controlsRef.current) {
+            api.set({
+                camX: camera.position.x,
+                camY: camera.position.y,
+                camZ: camera.position.z,
+                lookX: controlsRef.current.target.x,
+                lookY: controlsRef.current.target.y,
+                lookZ: controlsRef.current.target.z,
+            });
+        }
+        const config = options?.duration ? { duration: options.duration } : undefined;
+        api.start({
+            camX: x,
+            camY: height,
+            camZ: z + 0.001, // tiny offset to avoid gimbal lock when looking straight down
+            lookX: x,
+            lookY: 0,
+            lookZ: z,
+            ...(config ? { config } : {}),
+        });
+    }, [api, camera]);
     // Set camera target (look-at point), maintaining current distance and angles
     const setTarget = useCallback((x, y, z, options) => {
         // Get current offset from target
@@ -1409,6 +1461,7 @@ const AnimatedCamera = React.memo(function AnimatedCamera({ citySize, isFlat, fo
         cameraApi = {
             reset: resetToInitial,
             moveTo,
+            setFlatView,
             setTarget,
             rotateTo,
             rotateBy,
@@ -1422,7 +1475,7 @@ const AnimatedCamera = React.memo(function AnimatedCamera({ citySize, isFlat, fo
         return () => {
             cameraApi = null;
         };
-    }, [resetToInitial, moveTo, setTarget, rotateTo, rotateBy, tiltTo, tiltBy, getCurrentPosition, getCurrentTarget, getCurrentAngle, getCurrentTilt]);
+    }, [resetToInitial, moveTo, setFlatView, 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
@@ -1679,7 +1732,7 @@ function SelectionRing({ district, centerOffset, color, borderWidth, growProgres
     const barH = 0.5;
     return (_jsxs("group", { position: [cx, y, cz], children: [_jsxs("mesh", { position: [0, 0, -d / 2], renderOrder: 20, children: [_jsx("boxGeometry", { args: [w + t, barH, t] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.95 })] }), _jsxs("mesh", { position: [0, 0, d / 2], renderOrder: 20, children: [_jsx("boxGeometry", { args: [w + t, barH, t] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.95 })] }), _jsxs("mesh", { position: [-w / 2, 0, 0], renderOrder: 20, children: [_jsx("boxGeometry", { args: [t, barH, d + t] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.95 })] }), _jsxs("mesh", { position: [w / 2, 0, 0], renderOrder: 20, children: [_jsx("boxGeometry", { args: [t, barH, d + t] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.95 })] })] }));
 }
-function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding, selectedBuilding, selectedDistrict, selectionStyle, growProgress, animationConfig, highlightLayers, isolationMode, heightScaling, linearScale, flatPatterns, focusDirectory, focusColor, adaptCameraToBuildings = false, elevatedScopePanels, dismissingPanelIds, onPanelDismissed, cameraControls, onCameraReady, }) {
+function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding, selectedBuilding, selectedDistrict, selectionStyle, growProgress, animationConfig, highlightLayers, isolationMode, heightScaling, linearScale, flatPatterns, focusDirectory, focusColor, adaptCameraToBuildings = false, elevatedScopePanels, dismissingPanelIds, onPanelDismissed, cameraControls, defaultBuildingColor, onCameraReady, }) {
     const centerOffset = useMemo(() => ({
         x: (cityData.bounds.minX + cityData.bounds.maxX) / 2,
         z: (cityData.bounds.minZ + cityData.bounds.maxZ) / 2,
@@ -1883,7 +1936,7 @@ function CityScene({ cityData, onBuildingHover, onBuildingClick, hoveredBuilding
                 // 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, 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, flatPatterns: flatPatterns, staggerIndices: staggerIndices, focusDirectory: buildingFocusDirectory, highlightLayers: highlightLayers, isolationMode: isolationMode }), _jsx(BuildingIcons, { buildings: cityData.buildings, centerOffset: centerOffset, growProgress: growProgress, heightScaling: heightScaling, linearScale: linearScale, flatPatterns: flatPatterns, highlightLayers: highlightLayers, isolationMode: isolationMode, hasActiveHighlights: activeHighlights }), growProgress === 0 &&
+            }), _jsx(InstancedBuildings, { buildings: cityData.buildings, centerOffset: centerOffset, onHover: onBuildingHover, onClick: onBuildingClick, hoveredIndex: hoveredIndex, selectedIndex: selectedIndex, growProgress: growProgress, animationConfig: animationConfig, heightScaling: heightScaling, linearScale: linearScale, flatPatterns: flatPatterns, staggerIndices: staggerIndices, focusDirectory: buildingFocusDirectory, highlightLayers: highlightLayers, isolationMode: isolationMode, defaultBuildingColor: defaultBuildingColor }), _jsx(BuildingIcons, { buildings: cityData.buildings, centerOffset: centerOffset, growProgress: growProgress, heightScaling: heightScaling, linearScale: linearScale, flatPatterns: flatPatterns, highlightLayers: highlightLayers, isolationMode: isolationMode, hasActiveHighlights: activeHighlights }), growProgress === 0 &&
                 elevatedScopePanels?.map(panel => (_jsx(ElevatedScopePanelMesh, { panel: panel, centerOffset: centerOffset, dismissing: dismissingPanelIds?.has(panel.id) ?? false, onDismissed: onPanelDismissed }, panel.id))), selectedDistrict && (_jsx(SelectionRing, { district: selectedDistrict, centerOffset: centerOffset, color: selectionStyle?.color ?? '#facc15', borderWidth: selectionStyle?.borderWidth ?? 2, growProgress: growProgress }))] }));
 }
 /**
@@ -1892,7 +1945,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, onBuildingHover, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls = false, elevatedScopePanels, dismissingPanelIds, onPanelDismissed, highlightLayers: externalHighlightLayers, isolationMode: externalIsolationMode, dimOpacity: _dimOpacity = 0.15, isLoading = false, loadingMessage = 'Loading file city...', emptyMessage = 'No file tree data available', heightScaling = 'linear', linearScale = 1, flatPatterns = DEFAULT_FLAT_PATTERNS, focusDirectory: externalFocusDirectory, focusColor: externalFocusColor, onDirectorySelect: _onDirectorySelect, backgroundColor = '#0f172a', textColor = '#94a3b8', selectedBuilding = null, selectedPath = null, selectionStyle, adaptCameraToBuildings = false, fileColorLayers, cameraControls, }) {
+export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingClick, onBuildingHover, className, style, animation, isGrown: externalIsGrown, onGrowChange, showControls = false, elevatedScopePanels, dismissingPanelIds, onPanelDismissed, highlightLayers: externalHighlightLayers, isolationMode: externalIsolationMode, dimOpacity: _dimOpacity = 0.15, isLoading = false, loadingMessage = 'Loading file city...', emptyMessage = 'No file tree data available', heightScaling = 'linear', linearScale = 1, flatPatterns = DEFAULT_FLAT_PATTERNS, focusDirectory: externalFocusDirectory, focusColor: externalFocusColor, onDirectorySelect: _onDirectorySelect, backgroundColor = '#0f172a', textColor = '#94a3b8', selectedBuilding = null, selectedPath = null, selectionStyle, adaptCameraToBuildings = false, fileColorLayers, defaultBuildingColor, cameraControls, onCameraFrame, }) {
     const [hoveredBuilding, setHoveredBuilding] = useState(null);
     const [internalIsGrown, setInternalIsGrown] = useState(false);
     const [cameraReady, setCameraReady] = useState(false);
@@ -2007,7 +2060,7 @@ export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingC
             background: backgroundColor,
             overflow: 'hidden',
             ...style,
-        }, children: [_jsx(Canvas, { shadows: true, flat // Disables tone mapping for true colors
+        }, children: [_jsxs(Canvas, { shadows: true, flat // Disables tone mapping for true colors
                 : true, style: {
                     position: 'absolute',
                     top: 0,
@@ -2016,6 +2069,6 @@ export function FileCity3D({ cityData, width = '100%', height = 600, onBuildingC
                     height: '100%',
                     opacity: cameraReady ? 1 : 0,
                     transition: 'opacity 0.1s ease-in',
-                }, children: _jsx(CityScene, { cityData: cityData, onBuildingHover: handleBuildingHover, onBuildingClick: onBuildingClick, hoveredBuilding: hoveredBuilding, selectedBuilding: resolvedSelection.building, selectedDistrict: resolvedSelection.district, selectionStyle: selectionStyle, growProgress: growProgress, animationConfig: animationConfig, highlightLayers: highlightLayers, isolationMode: isolationMode, heightScaling: heightScaling, linearScale: linearScale, flatPatterns: flatPatterns, focusDirectory: focusDirectory, focusColor: focusColor, adaptCameraToBuildings: adaptCameraToBuildings, elevatedScopePanels: elevatedScopePanels, dismissingPanelIds: dismissingPanelIds, onPanelDismissed: onPanelDismissed, cameraControls: cameraControls, onCameraReady: () => setCameraReady(true) }) }), _jsx(InfoPanel, { building: resolvedSelection.building }), showControls && (_jsx(ControlsOverlay, { isFlat: !isGrown, onToggle: handleToggle, onResetCamera: resetCamera, onLookDown: () => tiltCameraTo(0) }))] }));
+                }, children: [_jsx(CityScene, { cityData: cityData, onBuildingHover: handleBuildingHover, onBuildingClick: onBuildingClick, hoveredBuilding: hoveredBuilding, selectedBuilding: resolvedSelection.building, selectedDistrict: resolvedSelection.district, selectionStyle: selectionStyle, growProgress: growProgress, animationConfig: animationConfig, highlightLayers: highlightLayers, isolationMode: isolationMode, heightScaling: heightScaling, linearScale: linearScale, flatPatterns: flatPatterns, focusDirectory: focusDirectory, focusColor: focusColor, adaptCameraToBuildings: adaptCameraToBuildings, elevatedScopePanels: elevatedScopePanels, dismissingPanelIds: dismissingPanelIds, onPanelDismissed: onPanelDismissed, cameraControls: cameraControls, defaultBuildingColor: defaultBuildingColor, onCameraReady: () => setCameraReady(true) }), onCameraFrame && _jsx(CameraFrameBridge, { onCameraFrame: onCameraFrame })] }), _jsx(InfoPanel, { building: resolvedSelection.building }), showControls && (_jsx(ControlsOverlay, { isFlat: !isGrown, onToggle: handleToggle, onResetCamera: resetCamera, onLookDown: () => tiltCameraTo(0) }))] }));
 }
 export default FileCity3D;

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

@@ -1,6 +1,6 @@
 /**
  * FileCity3D - 3D visualization component
  */
-export { FileCity3D, resetCamera, getCameraAngle, getCameraTarget, getCameraTilt, rotateCameraTo, rotateCameraBy, tiltCameraTo, tiltCameraBy, moveCameraTo, setCameraTarget, DEFAULT_FLAT_PATTERNS, DEFAULT_CAMERA_CONTROLS, } from './FileCity3D';
-export type { FileCity3DProps, AnimationConfig, HighlightLayer, LayerItem, LayerRenderStrategy, IsolationMode, HeightScaling, FlatPattern, ElevatedScopePanel, SelectionStyle, CityData, CityBuilding, CityDistrict, CameraControlsConfig, MouseDragAction, TouchOneAction, TouchTwoAction, WheelAction, } from './FileCity3D';
+export { FileCity3D, resetCamera, getCameraAngle, getCameraPosition, getCameraTarget, getCameraTilt, rotateCameraTo, rotateCameraBy, tiltCameraTo, tiltCameraBy, moveCameraTo, setCameraFlatView, setCameraTarget, DEFAULT_FLAT_PATTERNS, DEFAULT_CAMERA_CONTROLS, } from './FileCity3D';
+export type { FileCity3DProps, AnimationConfig, HighlightLayer, LayerItem, LayerRenderStrategy, IsolationMode, HeightScaling, FlatPattern, ElevatedScopePanel, SelectionStyle, CityData, CityBuilding, CityDistrict, CameraControlsConfig, MouseDragAction, TouchOneAction, TouchTwoAction, WheelAction, OnCameraFrame, } 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,EACL,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,cAAc,EACd,WAAW,GACZ,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,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,uBAAuB,GACxB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,oBAAoB,EACpB,eAAe,EACf,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,GACd,MAAM,cAAc,CAAC"}

package/dist/components/FileCity3D/index.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/file-city-react",
-  "version": "0.5.43",
+  "version": "0.5.45",
   "type": "module",
   "description": "React components for File City visualization",
   "main": "dist/index.js",
@@ -30,6 +30,7 @@
     "@principal-ade/industry-theme": "^0.1.19",
     "@principal-ai/file-city-builder": "^0.4.5",
     "@principal-ai/principal-view-core": "^0.28.5",
+    "@principal-ai/principal-view-react": "^0.15.6",
     "@react-spring/three": "^10.0.3",
     "@react-three/drei": "^10.0.6",
     "@react-three/fiber": "^9.1.2",

package/src/components/FileCity3D/FileCity3D.tsx

@@ -49,6 +49,24 @@ export interface SelectionStyle {
   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
@@ -718,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>
   );
 }
@@ -743,6 +761,7 @@ interface InstancedBuildingsProps {
   focusDirectory: string | null;
   highlightLayers: HighlightLayer[];
   isolationMode: IsolationMode;
+  defaultBuildingColor?: string;
 }
 
 // Helper to check if a path is inside a directory
@@ -767,6 +786,7 @@ function InstancedBuildings({
   focusDirectory,
   highlightLayers,
   isolationMode,
+  defaultBuildingColor,
 }: InstancedBuildingsProps) {
   const meshRef = useRef<THREE.InstancedMesh>(null);
   const startTimeRef = useRef<number | null>(null);
@@ -852,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;
@@ -881,6 +901,7 @@ function InstancedBuildings({
     staggerIndices,
     animationConfig.staggerDelay,
     highlightLayers,
+    defaultBuildingColor,
   ]);
 
   const minHeight = 0.3;
@@ -1432,6 +1453,7 @@ function touchTwoAction(action: TouchTwoAction): number | undefined {
 interface CameraApi {
   reset: () => void;
   moveTo: (x: number, z: number, size?: number) => void;
+  setFlatView: (x: number, z: number, height: number, options?: RotateOptions) => void;
   setTarget: (x: number, y: number, z: number, options?: RotateOptions) => void;
   rotateTo: (angleOrDirection: number | 'north' | 'south' | 'east' | 'west', options?: RotateOptions) => void;
   rotateBy: (degrees: number, options?: RotateOptions) => void;
@@ -1453,6 +1475,21 @@ export function moveCameraTo(x: number, z: number, size?: number) {
   cameraApi?.moveTo(x, z, size);
 }
 
+/**
+ * Position the camera straight overhead a target at a specific height (flat
+ * top-down view). Use to fit the city inside a sub-rect of the canvas — e.g.
+ * when overlays cover part of the viewport. Larger `height` = city appears
+ * smaller; smaller `height` = zoomed in.
+ */
+export function setCameraFlatView(
+  x: number,
+  z: number,
+  height: number,
+  options?: RotateOptions,
+) {
+  cameraApi?.setFlatView(x, z, height, options);
+}
+
 /**
  * Set the camera's look-at target (center point for orbiting).
  * Camera maintains its current distance and angles relative to the new target.
@@ -1537,6 +1574,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,
@@ -1934,6 +1984,40 @@ const AnimatedCamera = React.memo(function AnimatedCamera({
     });
   }, [citySize, api]);
 
+  // Position the camera directly above a target at a given height (flat /
+  // top-down view). Useful for fitting the city into a visible sub-rect of
+  // the canvas — raise `height` to make the city appear smaller, lower it to
+  // zoom in. Pairs with `setTarget` for pan-only changes.
+  const setFlatView = useCallback(
+    (x: number, z: number, height: number, options?: RotateOptions) => {
+      // MapControls (drag/wheel) mutates camera.position and controls.target
+      // directly without touching our spring. If we don't resync first, a
+      // call here can no-op when the spring's stored values happen to equal
+      // the requested target even though the visible camera is elsewhere.
+      if (controlsRef.current) {
+        api.set({
+          camX: camera.position.x,
+          camY: camera.position.y,
+          camZ: camera.position.z,
+          lookX: controlsRef.current.target.x,
+          lookY: controlsRef.current.target.y,
+          lookZ: controlsRef.current.target.z,
+        });
+      }
+      const config = options?.duration ? { duration: options.duration } : undefined;
+      api.start({
+        camX: x,
+        camY: height,
+        camZ: z + 0.001, // tiny offset to avoid gimbal lock when looking straight down
+        lookX: x,
+        lookY: 0,
+        lookZ: z,
+        ...(config ? { config } : {}),
+      });
+    },
+    [api, camera],
+  );
+
   // Set camera target (look-at point), maintaining current distance and angles
   const setTarget = useCallback((x: number, y: number, z: number, options?: RotateOptions) => {
     // Get current offset from target
@@ -2167,6 +2251,7 @@ const AnimatedCamera = React.memo(function AnimatedCamera({
     cameraApi = {
       reset: resetToInitial,
       moveTo,
+      setFlatView,
       setTarget,
       rotateTo,
       rotateBy,
@@ -2180,7 +2265,7 @@ const AnimatedCamera = React.memo(function AnimatedCamera({
     return () => {
       cameraApi = null;
     };
-  }, [resetToInitial, moveTo, setTarget, rotateTo, rotateBy, tiltTo, tiltBy, getCurrentPosition, getCurrentTarget, getCurrentAngle, getCurrentTilt]);
+  }, [resetToInitial, moveTo, setFlatView, 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:
@@ -2698,6 +2783,7 @@ interface CitySceneProps {
   dismissingPanelIds?: ReadonlySet<string>;
   onPanelDismissed?: (id: string) => void;
   cameraControls?: CameraControlsConfig;
+  defaultBuildingColor?: string;
 }
 
 function CityScene({
@@ -2722,6 +2808,7 @@ function CityScene({
   dismissingPanelIds,
   onPanelDismissed,
   cameraControls,
+  defaultBuildingColor,
   onCameraReady,
 }: CitySceneProps & { onCameraReady?: () => void }) {
   const centerOffset = useMemo(
@@ -3028,6 +3115,7 @@ function CityScene({
         focusDirectory={buildingFocusDirectory}
         highlightLayers={highlightLayers}
         isolationMode={isolationMode}
+        defaultBuildingColor={defaultBuildingColor}
       />
 
       <BuildingIcons
@@ -3144,6 +3232,15 @@ export interface FileCity3DProps {
   /** 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.
@@ -3173,6 +3270,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;
 }
 
 /**
@@ -3215,7 +3321,9 @@ export function FileCity3D({
   selectionStyle,
   adaptCameraToBuildings = false,
   fileColorLayers,
+  defaultBuildingColor,
   cameraControls,
+  onCameraFrame,
 }: FileCity3DProps) {
   const [hoveredBuilding, setHoveredBuilding] = useState<CityBuilding | null>(null);
   const [internalIsGrown, setInternalIsGrown] = useState(false);
@@ -3402,8 +3510,10 @@ export function FileCity3D({
           dismissingPanelIds={dismissingPanelIds}
           onPanelDismissed={onPanelDismissed}
           cameraControls={cameraControls}
+          defaultBuildingColor={defaultBuildingColor}
           onCameraReady={() => setCameraReady(true)}
         />
+        {onCameraFrame && <CameraFrameBridge onCameraFrame={onCameraFrame} />}
       </Canvas>
       <InfoPanel building={resolvedSelection.building} />
       {showControls && (

package/src/components/FileCity3D/index.ts

@@ -6,6 +6,7 @@ export {
   FileCity3D,
   resetCamera,
   getCameraAngle,
+  getCameraPosition,
   getCameraTarget,
   getCameraTilt,
   rotateCameraTo,
@@ -13,6 +14,7 @@ export {
   tiltCameraTo,
   tiltCameraBy,
   moveCameraTo,
+  setCameraFlatView,
   setCameraTarget,
   DEFAULT_FLAT_PATTERNS,
   DEFAULT_CAMERA_CONTROLS,
@@ -36,4 +38,5 @@ export type {
   TouchOneAction,
   TouchTwoAction,
   WheelAction,
+  OnCameraFrame,
 } from './FileCity3D';