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

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

@@ -7,7 +7,7 @@
  * Supports animated transition from 2D (flat) to 3D (grown buildings).
  */
 import React from 'react';
-import type { CityData, CityBuilding, CityDistrict } from '@principal-ai/file-city-builder';
+import type { CityData, CityBuilding, CityDistrict, HighlightLayer as BuilderHighlightLayer, LayerItem, LayerRenderStrategy } from '@principal-ai/file-city-builder';
 import type { ThreeElements } from '@react-three/fiber';
 declare module 'react' {
     namespace JSX {
@@ -15,31 +15,8 @@ declare module 'react' {
         }
     }
 }
-export type { CityData, CityBuilding, CityDistrict };
-export interface HighlightLayer {
-    /** Unique identifier */
-    id: string;
-    /** Display name */
-    name: string;
-    /** Whether layer is active */
-    enabled: boolean;
-    /** Highlight color (hex) */
-    color: string;
-    /** Items to highlight */
-    items: HighlightItem[];
-    /** Opacity for highlighted items (0-1) */
-    opacity?: number;
-    /** Rendering priority (higher renders on top) */
-    priority?: number;
-    /** Border width in pixels */
-    borderWidth?: number;
-}
-export interface HighlightItem {
-    /** File or directory path */
-    path: string;
-    /** Type of item */
-    type: 'file' | 'directory';
-}
+export type { CityData, CityBuilding, CityDistrict, LayerItem, LayerRenderStrategy };
+export type HighlightLayer = BuilderHighlightLayer;
 /** What to do with non-highlighted buildings */
 export type IsolationMode = 'none' | 'transparent' | 'collapse' | 'hide';
 export interface AnimationConfig {

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

@@ -155,21 +155,48 @@ function getColorForFile(building) {
     return getConfigForFile(building).color;
 }
 /**
- * Check if a path is highlighted by any enabled layer.
+ * Get ALL layer matches for a path, sorted by priority (highest first).
+ * Returns array to support multiple layers rendering together (e.g., fill + border).
  */
-function getHighlightForPath(path, layers) {
+function getLayerMatchesForPath(path, layers) {
+    const matches = [];
     for (const layer of layers) {
         if (!layer.enabled)
             continue;
         for (const item of layer.items) {
+            let isMatch = false;
             if (item.type === 'file' && item.path === path) {
-                return { color: layer.color, opacity: layer.opacity ?? 1 };
+                isMatch = true;
+            }
+            else if (item.type === 'directory' && (path === item.path || path.startsWith(item.path + '/'))) {
+                isMatch = true;
             }
-            if (item.type === 'directory' && (path === item.path || path.startsWith(item.path + '/'))) {
-                return { color: layer.color, opacity: layer.opacity ?? 1 };
+            if (isMatch) {
+                matches.push({
+                    layer,
+                    item,
+                    color: layer.color,
+                    opacity: layer.opacity ?? 1,
+                    borderWidth: layer.borderWidth,
+                    renderStrategy: item.renderStrategy || 'border', // Default from 2D renderer
+                });
             }
         }
     }
+    // Sort by priority (highest first)
+    return matches.sort((a, b) => (b.layer.priority ?? 0) - (a.layer.priority ?? 0));
+}
+/**
+ * Get the highest-priority fill color for a path (backward compatibility).
+ * Returns the first matching layer with 'fill' strategy.
+ */
+function getHighlightForPath(path, layers) {
+    const matches = getLayerMatchesForPath(path, layers);
+    // Find first fill match
+    const fillMatch = matches.find(m => m.renderStrategy === 'fill');
+    if (fillMatch) {
+        return { color: fillMatch.color, opacity: fillMatch.opacity };
+    }
     return null;
 }
 function hasActiveHighlights(layers) {
@@ -233,6 +260,177 @@ function BuildingEdges({ buildings, growProgress, minHeight, baseOffset, springD
         return null;
     return (_jsxs("instancedMesh", { ref: meshRef, args: [undefined, undefined, numEdges], frustumCulled: false, children: [_jsx("boxGeometry", { args: [1, 1, 1] }), _jsx("meshBasicMaterial", { color: "#1a1a2e", transparent: true, opacity: 0.7 })] }));
 }
+function BorderHighlights({ buildings, centerOffset, highlightLayers, growProgress, minHeight, baseOffset, springDuration, heightMultipliersRef, heightScaling, linearScale, flatPatterns, staggerIndices, animationConfig, }) {
+    const meshRef = useRef(null);
+    const startTimeRef = useRef(null);
+    const tempObject = useMemo(() => new THREE.Object3D(), []);
+    const tempColor = useMemo(() => new THREE.Color(), []);
+    // Pre-compute border edge data from buildings with border highlights
+    const borderEdgeData = useMemo(() => {
+        const edges = [];
+        buildings.forEach((building, buildingIndex) => {
+            const matches = getLayerMatchesForPath(building.path, highlightLayers);
+            // Find border matches
+            const borderMatches = matches.filter(m => m.renderStrategy === 'border');
+            if (borderMatches.length === 0)
+                return;
+            // Use highest priority border match
+            const borderMatch = borderMatches[0];
+            const [width, , depth] = building.dimensions;
+            const fullHeight = calculateBuildingHeight(building, heightScaling, linearScale, flatPatterns);
+            const x = building.position.x - centerOffset.x;
+            const z = building.position.z - centerOffset.z;
+            const staggerIndex = staggerIndices[buildingIndex] ?? buildingIndex;
+            const staggerDelayMs = (animationConfig.staggerDelay || 15) * staggerIndex;
+            const halfW = width / 2;
+            const halfD = depth / 2;
+            // Create 4 vertical corner edges
+            const corners = [
+                { x: x - halfW, z: z - halfD },
+                { x: x + halfW, z: z - halfD },
+                { x: x - halfW, z: z + halfD },
+                { x: x + halfW, z: z + halfD },
+            ];
+            corners.forEach(corner => {
+                edges.push({
+                    x: corner.x,
+                    z: corner.z,
+                    fullHeight,
+                    buildingIndex,
+                    staggerDelayMs,
+                    color: borderMatch.color,
+                    opacity: borderMatch.opacity,
+                    borderWidth: borderMatch.borderWidth ?? 2,
+                    edgeType: 'vertical',
+                });
+            });
+            // Create 4 horizontal edges on top (roof outline)
+            // Two edges along X axis (front and back)
+            edges.push({
+                x: x,
+                z: z - halfD,
+                fullHeight,
+                buildingIndex,
+                staggerDelayMs,
+                color: borderMatch.color,
+                opacity: borderMatch.opacity,
+                borderWidth: borderMatch.borderWidth ?? 2,
+                edgeType: 'horizontal-x',
+                width,
+            });
+            edges.push({
+                x: x,
+                z: z + halfD,
+                fullHeight,
+                buildingIndex,
+                staggerDelayMs,
+                color: borderMatch.color,
+                opacity: borderMatch.opacity,
+                borderWidth: borderMatch.borderWidth ?? 2,
+                edgeType: 'horizontal-x',
+                width,
+            });
+            // Two edges along Z axis (left and right)
+            edges.push({
+                x: x - halfW,
+                z: z,
+                fullHeight,
+                buildingIndex,
+                staggerDelayMs,
+                color: borderMatch.color,
+                opacity: borderMatch.opacity,
+                borderWidth: borderMatch.borderWidth ?? 2,
+                edgeType: 'horizontal-z',
+                depth,
+            });
+            edges.push({
+                x: x + halfW,
+                z: z,
+                fullHeight,
+                buildingIndex,
+                staggerDelayMs,
+                color: borderMatch.color,
+                opacity: borderMatch.opacity,
+                borderWidth: borderMatch.borderWidth ?? 2,
+                edgeType: 'horizontal-z',
+                depth,
+            });
+        });
+        return edges;
+    }, [
+        buildings,
+        centerOffset,
+        highlightLayers,
+        heightScaling,
+        linearScale,
+        flatPatterns,
+        staggerIndices,
+        animationConfig.staggerDelay,
+    ]);
+    // Animate border edges
+    useFrame(({ clock }) => {
+        if (!meshRef.current || borderEdgeData.length === 0)
+            return;
+        if (startTimeRef.current === null && growProgress > 0) {
+            startTimeRef.current = clock.elapsedTime * 1000;
+        }
+        const currentTime = clock.elapsedTime * 1000;
+        const animStartTime = startTimeRef.current ?? currentTime;
+        borderEdgeData.forEach((edge, idx) => {
+            const { x, z, fullHeight, staggerDelayMs, buildingIndex, color, opacity, borderWidth, edgeType, width, depth } = edge;
+            // Get height multiplier from shared ref (for collapse animation)
+            const heightMultiplier = heightMultipliersRef.current?.[buildingIndex] ?? 1;
+            // Calculate per-building animation progress
+            const elapsed = currentTime - animStartTime - staggerDelayMs;
+            let animProgress = growProgress;
+            if (growProgress > 0 && elapsed >= 0) {
+                const t = Math.min(elapsed / springDuration, 1);
+                const eased = 1 - Math.pow(1 - t, 3);
+                animProgress = eased * growProgress;
+            }
+            else if (growProgress > 0 && elapsed < 0) {
+                animProgress = 0;
+            }
+            // Apply both grow animation and collapse multiplier
+            const height = animProgress * fullHeight * heightMultiplier + minHeight;
+            // Fixed thickness based on borderWidth (don't scale with building size)
+            const thickness = Math.max(0.2, borderWidth * 0.1); // Convert pixels to world units
+            if (edgeType === 'vertical') {
+                // Vertical corner edges
+                const yPosition = height / 2 + baseOffset;
+                tempObject.position.set(x, yPosition, z);
+                tempObject.rotation.set(0, 0, 0);
+                tempObject.scale.set(thickness, height, thickness);
+            }
+            else if (edgeType === 'horizontal-x') {
+                // Horizontal edges along X axis (front/back of roof)
+                const yPosition = height + baseOffset;
+                tempObject.position.set(x, yPosition, z);
+                tempObject.rotation.set(0, 0, Math.PI / 2); // Rotate to horizontal along X
+                tempObject.scale.set(thickness, width, thickness);
+            }
+            else if (edgeType === 'horizontal-z') {
+                // Horizontal edges along Z axis (left/right of roof)
+                const yPosition = height + baseOffset;
+                tempObject.position.set(x, yPosition, z);
+                tempObject.rotation.set(Math.PI / 2, 0, 0); // Rotate to horizontal along Z
+                tempObject.scale.set(thickness, depth, thickness);
+            }
+            tempObject.updateMatrix();
+            meshRef.current.setMatrixAt(idx, tempObject.matrix);
+            // Set per-instance color with opacity
+            tempColor.set(color);
+            meshRef.current.setColorAt(idx, tempColor);
+        });
+        meshRef.current.instanceMatrix.needsUpdate = true;
+        if (meshRef.current.instanceColor) {
+            meshRef.current.instanceColor.needsUpdate = true;
+        }
+    });
+    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 })] }));
+}
 // Helper to check if a path is inside a directory
 function isPathInDirectory(path, directory) {
     if (!directory)
@@ -313,9 +511,10 @@ function InstancedBuildings({ buildings, centerOffset, onHover, onClick, hovered
         return buildings.map((building, index) => {
             const [width, , depth] = building.dimensions;
             const fullHeight = calculateBuildingHeight(building, heightScaling, linearScale, flatPatterns);
-            // Use highlight layer color if available, otherwise fall back to file config color
-            const highlight = getHighlightForPath(building.path, highlightLayers);
-            const color = highlight?.color ?? getColorForFile(building);
+            // 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 x = building.position.x - centerOffset.x;
             const z = building.position.z - centerOffset.z;
             const staggerIndex = staggerIndices[index] ?? index;
@@ -470,7 +669,7 @@ function InstancedBuildings({ buildings, centerOffset, onHover, onClick, hovered
                     z: d.z,
                     staggerDelayMs: d.staggerDelayMs,
                     buildingIndex: d.index,
-                })), growProgress: growProgress, minHeight: minHeight, baseOffset: baseOffset, springDuration: springDuration, heightMultipliersRef: heightMultipliersRef })] }));
+                })), growProgress: growProgress, minHeight: minHeight, baseOffset: baseOffset, springDuration: springDuration, heightMultipliersRef: heightMultipliersRef }), _jsx(BorderHighlights, { buildings: buildings, centerOffset: centerOffset, highlightLayers: highlightLayers, growProgress: growProgress, minHeight: minHeight, baseOffset: baseOffset, springDuration: springDuration, heightMultipliersRef: heightMultipliersRef, heightScaling: heightScaling, linearScale: linearScale, flatPatterns: flatPatterns, staggerIndices: staggerIndices, animationConfig: animationConfig })] }));
 }
 function AnimatedIcon({ x, z, targetHeight, iconSize, texture, opacity, growProgress, }) {
     const meshRef = useRef(null);

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

@@ -2,5 +2,5 @@
  * FileCity3D - 3D visualization component
  */
 export { FileCity3D, resetCamera, getCameraAngle, getCameraTarget, getCameraTilt, rotateCameraTo, rotateCameraBy, tiltCameraTo, tiltCameraBy, moveCameraTo, setCameraTarget, DEFAULT_FLAT_PATTERNS, } from './FileCity3D';
-export type { FileCity3DProps, AnimationConfig, HighlightLayer, HighlightItem, IsolationMode, HeightScaling, FlatPattern, CityData, CityBuilding, CityDistrict, } from './FileCity3D';
+export type { FileCity3DProps, AnimationConfig, HighlightLayer, LayerItem, LayerRenderStrategy, IsolationMode, HeightScaling, FlatPattern, 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,EACL,UAAU,EACV,WAAW,EACX,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,aAAa,EACb,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,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,EACf,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,aAAa,EACb,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export type { FileTree } from '@principal-ai/file-city-builder';
 export { CityViewWithReactFlow, type CityViewWithReactFlowProps, } from './components/CityViewWithReactFlow';
 export { ThemeProvider, useTheme } from '@principal-ade/industry-theme';
 export { FileCity3D, resetCamera, DEFAULT_FLAT_PATTERNS } from './components/FileCity3D';
-export type { FileCity3DProps, AnimationConfig, HighlightLayer as FileCity3DHighlightLayer, HighlightItem as FileCity3DHighlightItem, HighlightItem, IsolationMode, HeightScaling, FlatPattern, } from './components/FileCity3D';
+export type { FileCity3DProps, AnimationConfig, HighlightLayer as FileCity3DHighlightLayer, IsolationMode, HeightScaling, FlatPattern, } from './components/FileCity3D';
 export type { HighlightLayer as FileCity3DHL } from './components/FileCity3D';
 export { resolveVisualizationIntent } from './utils/visualizationResolution';
 export type { VisualizationIntent, ResolvedVisualizationState, } from './utils/visualizationResolution';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,8BAA8B,EAC9B,KAAK,mCAAmC,GACzC,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,UAAU,GACX,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGvF,OAAO,EACL,gCAAgC,EAChC,6BAA6B,EAC7B,oCAAoC,GACrC,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAGzF,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG7F,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,sBAAsB,EACtB,QAAQ,EACR,UAAU,GACX,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAG1E,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAG7F,YAAY,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAGhE,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACzF,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,IAAI,wBAAwB,EAC1C,aAAa,IAAI,uBAAuB,EACxC,aAAa,EACb,aAAa,EACb,aAAa,EACb,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAIjC,YAAY,EAAE,cAAc,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAI9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EACV,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,8BAA8B,EAC9B,KAAK,mCAAmC,GACzC,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,UAAU,GACX,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,KAAK,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAGvF,OAAO,EACL,gCAAgC,EAChC,6BAA6B,EAC7B,oCAAoC,GACrC,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,kCAAkC,CAAC;AAE1C,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAGzF,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAG7F,YAAY,EACV,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,sBAAsB,EACtB,QAAQ,EACR,UAAU,GACX,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAG1E,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC1D,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAG7F,YAAY,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAGhE,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,oCAAoC,CAAC;AAG5C,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AAGxE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AACzF,YAAY,EACV,eAAe,EACf,eAAe,EACf,cAAc,IAAI,wBAAwB,EAC1C,aAAa,EACb,aAAa,EACb,WAAW,GACZ,MAAM,yBAAyB,CAAC;AAIjC,YAAY,EAAE,cAAc,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAI9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EACV,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,iCAAiC,CAAC"}

package/package.json

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

package/src/components/FileCity3D/FileCity3D.tsx

@@ -18,6 +18,9 @@ import type {
   CityBuilding,
   CityDistrict,
   FileConfigResult,
+  HighlightLayer as BuilderHighlightLayer,
+  LayerItem,
+  LayerRenderStrategy,
 } from '@principal-ai/file-city-builder';
 import * as THREE from 'three';
 import type { ThreeElements } from '@react-three/fiber';
@@ -33,34 +36,8 @@ declare module 'react' {
 }
 
 // Re-export types for convenience
-export type { CityData, CityBuilding, CityDistrict };
-
-// Highlight layer types
-export interface HighlightLayer {
-  /** Unique identifier */
-  id: string;
-  /** Display name */
-  name: string;
-  /** Whether layer is active */
-  enabled: boolean;
-  /** Highlight color (hex) */
-  color: string;
-  /** Items to highlight */
-  items: HighlightItem[];
-  /** Opacity for highlighted items (0-1) */
-  opacity?: number;
-  /** Rendering priority (higher renders on top) */
-  priority?: number;
-  /** Border width in pixels */
-  borderWidth?: number;
-}
-
-export interface HighlightItem {
-  /** File or directory path */
-  path: string;
-  /** Type of item */
-  type: 'file' | 'directory';
-}
+export type { CityData, CityBuilding, CityDistrict, LayerItem, LayerRenderStrategy };
+export type HighlightLayer = BuilderHighlightLayer;
 
 /** What to do with non-highlighted buildings */
 export type IsolationMode =
@@ -273,25 +250,71 @@ function getColorForFile(building: CityBuilding): string {
   return getConfigForFile(building).color;
 }
 
+interface LayerMatch {
+  layer: HighlightLayer;
+  item: LayerItem;
+  color: string;
+  opacity: number;
+  borderWidth?: number;
+  renderStrategy: LayerRenderStrategy;
+}
+
 /**
- * Check if a path is highlighted by any enabled layer.
+ * Get ALL layer matches for a path, sorted by priority (highest first).
+ * Returns array to support multiple layers rendering together (e.g., fill + border).
  */
-function getHighlightForPath(
+function getLayerMatchesForPath(
   path: string,
   layers: HighlightLayer[],
-): { color: string; opacity: number } | null {
+): LayerMatch[] {
+  const matches: LayerMatch[] = [];
+
   for (const layer of layers) {
     if (!layer.enabled) continue;
 
     for (const item of layer.items) {
+      let isMatch = false;
+
       if (item.type === 'file' && item.path === path) {
-        return { color: layer.color, opacity: layer.opacity ?? 1 };
+        isMatch = true;
+      } else if (item.type === 'directory' && (path === item.path || path.startsWith(item.path + '/'))) {
+        isMatch = true;
       }
-      if (item.type === 'directory' && (path === item.path || path.startsWith(item.path + '/'))) {
-        return { color: layer.color, opacity: layer.opacity ?? 1 };
+
+      if (isMatch) {
+        matches.push({
+          layer,
+          item,
+          color: layer.color,
+          opacity: layer.opacity ?? 1,
+          borderWidth: layer.borderWidth,
+          renderStrategy: item.renderStrategy || 'border', // Default from 2D renderer
+        });
       }
     }
   }
+
+  // Sort by priority (highest first)
+  return matches.sort((a, b) => (b.layer.priority ?? 0) - (a.layer.priority ?? 0));
+}
+
+/**
+ * Get the highest-priority fill color for a path (backward compatibility).
+ * Returns the first matching layer with 'fill' strategy.
+ */
+function getHighlightForPath(
+  path: string,
+  layers: HighlightLayer[],
+): { color: string; opacity: number } | null {
+  const matches = getLayerMatchesForPath(path, layers);
+
+  // Find first fill match
+  const fillMatch = matches.find(m => m.renderStrategy === 'fill');
+
+  if (fillMatch) {
+    return { color: fillMatch.color, opacity: fillMatch.opacity };
+  }
+
   return null;
 }
 
@@ -406,6 +429,252 @@ function BuildingEdges({
   );
 }
 
+// ============================================================================
+// Border Highlights - Colored edge outlines for highlighted buildings
+// ============================================================================
+
+interface BorderEdgeData {
+  x: number;
+  z: number;
+  fullHeight: number;
+  buildingIndex: number;
+  staggerDelayMs: number;
+  color: string;
+  opacity: number;
+  borderWidth: number;
+  edgeType: 'vertical' | 'horizontal-x' | 'horizontal-z'; // Edge orientation
+  width?: number; // For horizontal edges (length along X axis)
+  depth?: number; // For horizontal edges (length along Z axis)
+}
+
+interface BorderHighlightsProps {
+  buildings: CityBuilding[];
+  centerOffset: { x: number; z: number };
+  highlightLayers: HighlightLayer[];
+  growProgress: number;
+  minHeight: number;
+  baseOffset: number;
+  springDuration: number;
+  heightMultipliersRef: React.MutableRefObject<Float32Array | null>;
+  heightScaling: HeightScaling;
+  linearScale: number;
+  flatPatterns: FlatPattern[];
+  staggerIndices: number[];
+  animationConfig: AnimationConfig;
+}
+
+function BorderHighlights({
+  buildings,
+  centerOffset,
+  highlightLayers,
+  growProgress,
+  minHeight,
+  baseOffset,
+  springDuration,
+  heightMultipliersRef,
+  heightScaling,
+  linearScale,
+  flatPatterns,
+  staggerIndices,
+  animationConfig,
+}: BorderHighlightsProps) {
+  const meshRef = useRef<THREE.InstancedMesh>(null);
+  const startTimeRef = useRef<number | null>(null);
+  const tempObject = useMemo(() => new THREE.Object3D(), []);
+  const tempColor = useMemo(() => new THREE.Color(), []);
+
+  // Pre-compute border edge data from buildings with border highlights
+  const borderEdgeData = useMemo(() => {
+    const edges: BorderEdgeData[] = [];
+
+    buildings.forEach((building, buildingIndex) => {
+      const matches = getLayerMatchesForPath(building.path, highlightLayers);
+
+      // Find border matches
+      const borderMatches = matches.filter(m => m.renderStrategy === 'border');
+
+      if (borderMatches.length === 0) return;
+
+      // Use highest priority border match
+      const borderMatch = borderMatches[0];
+
+      const [width, , depth] = building.dimensions;
+      const fullHeight = calculateBuildingHeight(building, heightScaling, linearScale, flatPatterns);
+      const x = building.position.x - centerOffset.x;
+      const z = building.position.z - centerOffset.z;
+      const staggerIndex = staggerIndices[buildingIndex] ?? buildingIndex;
+      const staggerDelayMs = (animationConfig.staggerDelay || 15) * staggerIndex;
+
+      const halfW = width / 2;
+      const halfD = depth / 2;
+
+      // Create 4 vertical corner edges
+      const corners = [
+        { x: x - halfW, z: z - halfD },
+        { x: x + halfW, z: z - halfD },
+        { x: x - halfW, z: z + halfD },
+        { x: x + halfW, z: z + halfD },
+      ];
+
+      corners.forEach(corner => {
+        edges.push({
+          x: corner.x,
+          z: corner.z,
+          fullHeight,
+          buildingIndex,
+          staggerDelayMs,
+          color: borderMatch.color,
+          opacity: borderMatch.opacity,
+          borderWidth: borderMatch.borderWidth ?? 2,
+          edgeType: 'vertical',
+        });
+      });
+
+      // Create 4 horizontal edges on top (roof outline)
+      // Two edges along X axis (front and back)
+      edges.push({
+        x: x,
+        z: z - halfD,
+        fullHeight,
+        buildingIndex,
+        staggerDelayMs,
+        color: borderMatch.color,
+        opacity: borderMatch.opacity,
+        borderWidth: borderMatch.borderWidth ?? 2,
+        edgeType: 'horizontal-x',
+        width,
+      });
+      edges.push({
+        x: x,
+        z: z + halfD,
+        fullHeight,
+        buildingIndex,
+        staggerDelayMs,
+        color: borderMatch.color,
+        opacity: borderMatch.opacity,
+        borderWidth: borderMatch.borderWidth ?? 2,
+        edgeType: 'horizontal-x',
+        width,
+      });
+
+      // Two edges along Z axis (left and right)
+      edges.push({
+        x: x - halfW,
+        z: z,
+        fullHeight,
+        buildingIndex,
+        staggerDelayMs,
+        color: borderMatch.color,
+        opacity: borderMatch.opacity,
+        borderWidth: borderMatch.borderWidth ?? 2,
+        edgeType: 'horizontal-z',
+        depth,
+      });
+      edges.push({
+        x: x + halfW,
+        z: z,
+        fullHeight,
+        buildingIndex,
+        staggerDelayMs,
+        color: borderMatch.color,
+        opacity: borderMatch.opacity,
+        borderWidth: borderMatch.borderWidth ?? 2,
+        edgeType: 'horizontal-z',
+        depth,
+      });
+    });
+
+    return edges;
+  }, [
+    buildings,
+    centerOffset,
+    highlightLayers,
+    heightScaling,
+    linearScale,
+    flatPatterns,
+    staggerIndices,
+    animationConfig.staggerDelay,
+  ]);
+
+  // Animate border edges
+  useFrame(({ clock }) => {
+    if (!meshRef.current || borderEdgeData.length === 0) return;
+
+    if (startTimeRef.current === null && growProgress > 0) {
+      startTimeRef.current = clock.elapsedTime * 1000;
+    }
+
+    const currentTime = clock.elapsedTime * 1000;
+    const animStartTime = startTimeRef.current ?? currentTime;
+
+    borderEdgeData.forEach((edge, idx) => {
+      const { x, z, fullHeight, staggerDelayMs, buildingIndex, color, opacity, borderWidth, edgeType, width, depth } = edge;
+
+      // Get height multiplier from shared ref (for collapse animation)
+      const heightMultiplier = heightMultipliersRef.current?.[buildingIndex] ?? 1;
+
+      // Calculate per-building animation progress
+      const elapsed = currentTime - animStartTime - staggerDelayMs;
+      let animProgress = growProgress;
+
+      if (growProgress > 0 && elapsed >= 0) {
+        const t = Math.min(elapsed / springDuration, 1);
+        const eased = 1 - Math.pow(1 - t, 3);
+        animProgress = eased * growProgress;
+      } else if (growProgress > 0 && elapsed < 0) {
+        animProgress = 0;
+      }
+
+      // Apply both grow animation and collapse multiplier
+      const height = animProgress * fullHeight * heightMultiplier + minHeight;
+
+      // Fixed thickness based on borderWidth (don't scale with building size)
+      const thickness = Math.max(0.2, borderWidth * 0.1); // Convert pixels to world units
+
+      if (edgeType === 'vertical') {
+        // Vertical corner edges
+        const yPosition = height / 2 + baseOffset;
+        tempObject.position.set(x, yPosition, z);
+        tempObject.rotation.set(0, 0, 0);
+        tempObject.scale.set(thickness, height, thickness);
+      } else if (edgeType === 'horizontal-x') {
+        // Horizontal edges along X axis (front/back of roof)
+        const yPosition = height + baseOffset;
+        tempObject.position.set(x, yPosition, z);
+        tempObject.rotation.set(0, 0, Math.PI / 2); // Rotate to horizontal along X
+        tempObject.scale.set(thickness, width!, thickness);
+      } else if (edgeType === 'horizontal-z') {
+        // Horizontal edges along Z axis (left/right of roof)
+        const yPosition = height + baseOffset;
+        tempObject.position.set(x, yPosition, z);
+        tempObject.rotation.set(Math.PI / 2, 0, 0); // Rotate to horizontal along Z
+        tempObject.scale.set(thickness, depth!, thickness);
+      }
+
+      tempObject.updateMatrix();
+      meshRef.current!.setMatrixAt(idx, tempObject.matrix);
+
+      // Set per-instance color with opacity
+      tempColor.set(color);
+      meshRef.current!.setColorAt(idx, tempColor);
+    });
+
+    meshRef.current.instanceMatrix.needsUpdate = true;
+    if (meshRef.current.instanceColor) {
+      meshRef.current.instanceColor.needsUpdate = true;
+    }
+  });
+
+  if (borderEdgeData.length === 0) return null;
+
+  return (
+    <instancedMesh ref={meshRef} args={[undefined, undefined, borderEdgeData.length]} frustumCulled={false}>
+      <boxGeometry args={[1, 1, 1]} />
+      <meshBasicMaterial transparent opacity={0.9} vertexColors />
+    </instancedMesh>
+  );
+}
+
 // ============================================================================
 // Instanced Buildings - High performance rendering for large scenes
 // ============================================================================
@@ -532,9 +801,10 @@ function InstancedBuildings({
     return buildings.map((building, index) => {
       const [width, , depth] = building.dimensions;
       const fullHeight = calculateBuildingHeight(building, heightScaling, linearScale, flatPatterns);
-      // Use highlight layer color if available, otherwise fall back to file config color
-      const highlight = getHighlightForPath(building.path, highlightLayers);
-      const color = highlight?.color ?? getColorForFile(building);
+      // 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 x = building.position.x - centerOffset.x;
       const z = building.position.z - centerOffset.z;
@@ -751,6 +1021,23 @@ function InstancedBuildings({
         springDuration={springDuration}
         heightMultipliersRef={heightMultipliersRef}
       />
+
+      {/* Border highlights (colored, layer-driven) */}
+      <BorderHighlights
+        buildings={buildings}
+        centerOffset={centerOffset}
+        highlightLayers={highlightLayers}
+        growProgress={growProgress}
+        minHeight={minHeight}
+        baseOffset={baseOffset}
+        springDuration={springDuration}
+        heightMultipliersRef={heightMultipliersRef}
+        heightScaling={heightScaling}
+        linearScale={linearScale}
+        flatPatterns={flatPatterns}
+        staggerIndices={staggerIndices}
+        animationConfig={animationConfig}
+      />
     </group>
   );
 }

package/src/components/FileCity3D/index.ts

@@ -20,7 +20,8 @@ export type {
   FileCity3DProps,
   AnimationConfig,
   HighlightLayer,
-  HighlightItem,
+  LayerItem,
+  LayerRenderStrategy,
   IsolationMode,
   HeightScaling,
   FlatPattern,

package/src/index.ts

@@ -77,8 +77,6 @@ export type {
   FileCity3DProps,
   AnimationConfig,
   HighlightLayer as FileCity3DHighlightLayer,
-  HighlightItem as FileCity3DHighlightItem,
-  HighlightItem,
   IsolationMode,
   HeightScaling,
   FlatPattern,

package/src/stories/2D3DComparison.stories.tsx

@@ -201,7 +201,7 @@ export const SideBySide: StoryObj = {
                 fontWeight: 500,
               }}
             >
-              3D FLAT
+              3D FLAT (with test border)
             </div>
             <div style={{ flex: 1, backgroundColor: '#0f1419' }}>
               <FileCity3D
@@ -210,7 +210,7 @@ export const SideBySide: StoryObj = {
                 width="100%"
                 height="100%"
                 isGrown={false}
-                showControls={false}
+                showControls={true}
                 backgroundColor="#0f1419"
               />
             </div>

package/src/stories/FileCity3D.stories.tsx

@@ -422,7 +422,7 @@ export const IsolationTransparent: Story = {
         name: 'Focus Layer',
         enabled: true,
         color: '#22c55e',
-        items: [{ path: 'src', type: 'directory' as const }],
+        items: [{ path: 'src', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
     ],
   },
@@ -442,7 +442,7 @@ export const IsolationCollapse: Story = {
         name: 'Focus Layer',
         enabled: true,
         color: '#3b82f6',
-        items: [{ path: 'src/components', type: 'directory' as const }],
+        items: [{ path: 'src/components', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
     ],
   },
@@ -462,7 +462,7 @@ export const IsolationHide: Story = {
         name: 'Focus Layer',
         enabled: true,
         color: '#f59e0b',
-        items: [{ path: 'tests', type: 'directory' as const }],
+        items: [{ path: 'tests', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
     ],
   },
@@ -483,14 +483,73 @@ export const MultipleHighlights: Story = {
         name: 'Source',
         enabled: true,
         color: '#22c55e',
-        items: [{ path: 'src', type: 'directory' as const }],
+        items: [{ path: 'src', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
       {
         id: 'tests',
         name: 'Tests',
         enabled: true,
         color: '#ef4444',
-        items: [{ path: 'tests', type: 'directory' as const }],
+        items: [{ path: 'tests', type: 'directory' as const, renderStrategy: 'fill' as const }],
+      },
+    ],
+  },
+};
+
+/**
+ * Layered Highlights - Multiple overlapping highlight layers
+ * Tests priority-based rendering with fill + border strategies
+ * Starts flat (2D) - click "Grow" button to see in 3D
+ */
+export const LayeredHighlights: Story = {
+  args: {
+    cityData: sampleCityData,
+    height: '100vh',
+    isolationMode: 'transparent',
+    dimOpacity: 0.05,
+    animation: {
+      startFlat: true,
+      autoStartDelay: null, // Stay in 2D, use button to grow
+    },
+    showControls: true,
+    highlightLayers: [
+      {
+        id: 'base-fill',
+        name: 'Base Fill (src)',
+        enabled: true,
+        color: '#3b82f6',
+        opacity: 0.7,
+        priority: 1,
+        items: [{ path: 'src', type: 'directory' as const, renderStrategy: 'fill' as const }],
+      },
+      {
+        id: 'components-fill',
+        name: 'Components Fill (src/components)',
+        enabled: true,
+        color: '#facc15',
+        opacity: 1.0,
+        priority: 2,
+        items: [{ path: 'src/components', type: 'directory' as const, renderStrategy: 'fill' as const }],
+      },
+      {
+        id: 'components-border',
+        name: 'Components Border (src/components)',
+        enabled: true,
+        color: '#ef4444',
+        opacity: 1.0,
+        priority: 3,
+        borderWidth: 6,
+        items: [{ path: 'src/components', type: 'directory' as const, renderStrategy: 'border' as const }],
+      },
+      {
+        id: 'utils-border',
+        name: 'Utils Border (src/utils)',
+        enabled: true,
+        color: '#22c55e',
+        opacity: 1.0,
+        priority: 4,
+        borderWidth: 4,
+        items: [{ path: 'src/utils', type: 'directory' as const, renderStrategy: 'border' as const }],
       },
     ],
   },
@@ -516,7 +575,7 @@ export const AnimatedWithHighlight: Story = {
         name: 'Components',
         enabled: true,
         color: '#8b5cf6',
-        items: [{ path: 'src/components', type: 'directory' as const }],
+        items: [{ path: 'src/components', type: 'directory' as const, renderStrategy: 'fill' as const }],
       },
     ],
   },