@principal-ai/file-city-react 0.5.39 → 0.5.40

package/dist/index.d.ts

@@ -16,6 +16,8 @@ export { ThemeProvider, useTheme } from '@principal-ade/industry-theme';
 export { FileCity3D, resetCamera, DEFAULT_FLAT_PATTERNS } from './components/FileCity3D';
 export type { FileCity3DProps, AnimationConfig, HighlightLayer as FileCity3DHighlightLayer, IsolationMode, HeightScaling, FlatPattern, ElevatedScopePanel, } from './components/FileCity3D';
 export type { HighlightLayer as FileCity3DHL } from './components/FileCity3D';
+export { buildFolderElevatedPanels, buildFolderIndex, hashFolderColor, } from './utils/folderElevatedPanels';
+export type { BuildFolderElevatedPanelsOptions } from './utils/folderElevatedPanels';
 export { resolveVisualizationIntent } from './utils/visualizationResolution';
 export type { VisualizationIntent, ResolvedVisualizationState, } from './utils/visualizationResolution';
 //# sourceMappingURL=index.d.ts.map

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,EACb,aAAa,EACb,WAAW,EACX,kBAAkB,GACnB,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,EACX,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AAIjC,YAAY,EAAE,cAAc,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG9E,OAAO,EACL,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,GAChB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,gCAAgC,EAAE,MAAM,8BAA8B,CAAC;AAIrF,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,YAAY,EACV,mBAAmB,EACnB,0BAA0B,GAC3B,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -20,6 +20,8 @@ export { CityViewWithReactFlow, } from './components/CityViewWithReactFlow';
 export { ThemeProvider, useTheme } from '@principal-ade/industry-theme';
 // 3D visualization component
 export { FileCity3D, resetCamera, DEFAULT_FLAT_PATTERNS } from './components/FileCity3D';
+// Folder-driven elevated panels (file-tree expansion → 3D umbrella tiles)
+export { buildFolderElevatedPanels, buildFolderIndex, hashFolderColor, } from './utils/folderElevatedPanels';
 // Visualization resolution utilities
 // See docs/VISUALIZATION_STATE_RESOLUTION.md for documentation
 export { resolveVisualizationIntent } from './utils/visualizationResolution';

package/dist/utils/folderElevatedPanels.d.ts

@@ -0,0 +1,60 @@
+import type { CityData } from '@principal-ai/file-city-builder';
+import type { ElevatedScopePanel } from '../components/FileCity3D';
+/**
+ * Stable color for a folder path, picked from a small palette via a string
+ * hash. Two folders at the same depth get visibly different colors; the
+ * same folder always gets the same color across renders.
+ */
+export declare function hashFolderColor(path: string): string;
+interface Bounds {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+}
+interface FolderIndex {
+    /** Parent directory → list of immediate child directories. Top-level folders live under '' (empty string). */
+    children: Map<string, string[]>;
+    /** Folder path → world bounds spanning every descendant district. */
+    bounds: Map<string, Bounds>;
+    /** Folder path → number of descendant files. */
+    fileCounts: Map<string, number>;
+}
+/**
+ * Precompute the data structures `buildFolderElevatedPanels` needs from a
+ * `CityData`. Cache this when the city data is stable to avoid redoing the
+ * O(districts × depth) walk on every render.
+ */
+export declare function buildFolderIndex(cityData: CityData): FolderIndex;
+export interface BuildFolderElevatedPanelsOptions {
+    cityData: CityData;
+    /**
+     * Set of folder paths that are currently expanded in the file tree. A folder
+     * not in this set is treated as collapsed.
+     */
+    expandedFolders: ReadonlySet<string>;
+    /** Toggle handler invoked when an umbrella tile is clicked. */
+    onToggleFolder?: (folderPath: string) => void;
+    /**
+     * Scale label font size by descendant file count. Default true. When false,
+     * the renderer's auto-sized label is used (size derived from tile footprint).
+     */
+    scaleLabelByFileCount?: boolean;
+    /**
+     * Pre-built index from `buildFolderIndex(cityData)`. Pass when you cache the
+     * city's index across renders to avoid recomputing it.
+     */
+    index?: FolderIndex;
+}
+/**
+ * Walks the folder hierarchy from the top-level folders of a `CityData`. For
+ * each folder:
+ *   - if expanded → recurse into child folders
+ *   - if collapsed → emit one elevated panel covering the union of every
+ *     descendant district's world bounds, colored via `hashFolderColor`.
+ *
+ * Mirror of the scope-tree expansion behavior, applied to file-tree folders.
+ */
+export declare function buildFolderElevatedPanels(options: BuildFolderElevatedPanelsOptions): ElevatedScopePanel[];
+export {};
+//# sourceMappingURL=folderElevatedPanels.d.ts.map

package/dist/utils/folderElevatedPanels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folderElevatedPanels.d.ts","sourceRoot":"","sources":["../../src/utils/folderElevatedPanels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAenE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMpD;AAED,UAAU,MAAM;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,WAAW;IACnB,8GAA8G;IAC9G,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,qEAAqE;IACrE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,gDAAgD;IAChD,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,CA+ChE;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;OAGG;IACH,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,+DAA+D;IAC/D,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,gCAAgC,GACxC,kBAAkB,EAAE,CAsCtB"}

package/dist/utils/folderElevatedPanels.js

@@ -0,0 +1,127 @@
+const FOLDER_PALETTE = [
+    '#3b82f6',
+    '#22c55e',
+    '#f59e0b',
+    '#ec4899',
+    '#8b5cf6',
+    '#06b6d4',
+    '#ef4444',
+    '#14b8a6',
+    '#a855f7',
+    '#eab308',
+];
+/**
+ * Stable color for a folder path, picked from a small palette via a string
+ * hash. Two folders at the same depth get visibly different colors; the
+ * same folder always gets the same color across renders.
+ */
+export function hashFolderColor(path) {
+    let h = 0;
+    for (let i = 0; i < path.length; i++) {
+        h = (h * 31 + path.charCodeAt(i)) | 0;
+    }
+    return FOLDER_PALETTE[Math.abs(h) % FOLDER_PALETTE.length];
+}
+/**
+ * Precompute the data structures `buildFolderElevatedPanels` needs from a
+ * `CityData`. Cache this when the city data is stable to avoid redoing the
+ * O(districts × depth) walk on every render.
+ */
+export function buildFolderIndex(cityData) {
+    const children = new Map();
+    const directorySet = new Set();
+    for (const d of cityData.districts)
+        directorySet.add(d.path);
+    const dirs = Array.from(directorySet).sort();
+    for (const dir of dirs) {
+        const slash = dir.lastIndexOf('/');
+        const parent = slash >= 0 ? dir.slice(0, slash) : '';
+        const arr = children.get(parent);
+        if (arr)
+            arr.push(dir);
+        else
+            children.set(parent, [dir]);
+    }
+    const bounds = new Map();
+    for (const district of cityData.districts) {
+        const b = district.worldBounds;
+        let path = district.path;
+        while (path) {
+            const cur = bounds.get(path);
+            if (!cur) {
+                bounds.set(path, { minX: b.minX, maxX: b.maxX, minZ: b.minZ, maxZ: b.maxZ });
+            }
+            else {
+                if (b.minX < cur.minX)
+                    cur.minX = b.minX;
+                if (b.maxX > cur.maxX)
+                    cur.maxX = b.maxX;
+                if (b.minZ < cur.minZ)
+                    cur.minZ = b.minZ;
+                if (b.maxZ > cur.maxZ)
+                    cur.maxZ = b.maxZ;
+            }
+            const slash = path.lastIndexOf('/');
+            if (slash < 0)
+                break;
+            path = path.slice(0, slash);
+        }
+    }
+    const fileCounts = new Map();
+    for (const b of cityData.buildings) {
+        let path = b.path;
+        const slash = path.lastIndexOf('/');
+        path = slash >= 0 ? path.slice(0, slash) : '';
+        while (path) {
+            fileCounts.set(path, (fileCounts.get(path) ?? 0) + 1);
+            const s = path.lastIndexOf('/');
+            if (s < 0)
+                break;
+            path = path.slice(0, s);
+        }
+    }
+    return { children, bounds, fileCounts };
+}
+/**
+ * Walks the folder hierarchy from the top-level folders of a `CityData`. For
+ * each folder:
+ *   - if expanded → recurse into child folders
+ *   - if collapsed → emit one elevated panel covering the union of every
+ *     descendant district's world bounds, colored via `hashFolderColor`.
+ *
+ * Mirror of the scope-tree expansion behavior, applied to file-tree folders.
+ */
+export function buildFolderElevatedPanels(options) {
+    const { cityData, expandedFolders, onToggleFolder, scaleLabelByFileCount = true, } = options;
+    const index = options.index ?? buildFolderIndex(cityData);
+    const panels = [];
+    const walk = (folderPath) => {
+        if (expandedFolders.has(folderPath)) {
+            const kids = index.children.get(folderPath) ?? [];
+            for (const child of kids)
+                walk(child);
+            return;
+        }
+        const bounds = index.bounds.get(folderPath);
+        if (!bounds)
+            return;
+        const label = folderPath.split('/').pop() ?? folderPath;
+        const fileCount = index.fileCounts.get(folderPath) ?? 0;
+        const labelSize = scaleLabelByFileCount
+            ? Math.max(12, Math.min(240, 8 + Math.sqrt(fileCount) * 5))
+            : undefined;
+        panels.push({
+            id: `folder::${folderPath}`,
+            color: hashFolderColor(folderPath),
+            height: 4,
+            thickness: 2,
+            bounds,
+            label,
+            labelSize,
+            onClick: onToggleFolder ? () => onToggleFolder(folderPath) : undefined,
+        });
+    };
+    for (const top of index.children.get('') ?? [])
+        walk(top);
+    return panels;
+}

package/package.json

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

package/src/index.ts

@@ -87,6 +87,14 @@ export type {
 // with the 2D HighlightLayer from drawLayeredBuildings
 export type { HighlightLayer as FileCity3DHL } from './components/FileCity3D';
 
+// Folder-driven elevated panels (file-tree expansion → 3D umbrella tiles)
+export {
+  buildFolderElevatedPanels,
+  buildFolderIndex,
+  hashFolderColor,
+} from './utils/folderElevatedPanels';
+export type { BuildFolderElevatedPanelsOptions } from './utils/folderElevatedPanels';
+
 // Visualization resolution utilities
 // See docs/VISUALIZATION_STATE_RESOLUTION.md for documentation
 export { resolveVisualizationIntent } from './utils/visualizationResolution';

package/src/stories/ScopeOverlay.stories.tsx

@@ -14,6 +14,7 @@ import {
   type HighlightLayer,
 } from '../components/FileCity3D';
 import { createFileColorHighlightLayers } from '../utils/fileColorHighlightLayers';
+import { buildFolderElevatedPanels, buildFolderIndex } from '../utils/folderElevatedPanels';
 
 import electronAppCityData from '../../../../assets/electron-app-city-data.json';
 
@@ -117,97 +118,11 @@ const ELECTRON_DISTRICTS_BY_PATH: Map<string, CityDistrict> = new Map(
 );
 
 /**
- * Parent directory → list of immediate child directories. Top-level folders
- * (e.g. `electron-app`) live under the empty-string parent. Used to walk the
- * folder hierarchy when generating elevated panels for the file-tree tab.
+ * Pre-built folder index (children, bounds, file counts) for the static
+ * electron-app city. Cached once at module load so the story doesn't
+ * recompute on every render.
  */
-const ELECTRON_FOLDER_CHILDREN: Map<string, string[]> = (() => {
-  const m = new Map<string, string[]>();
-  const dirs = Array.from(ELECTRON_DIRECTORIES).sort();
-  for (const dir of dirs) {
-    const slash = dir.lastIndexOf('/');
-    const parent = slash >= 0 ? dir.slice(0, slash) : '';
-    const arr = m.get(parent);
-    if (arr) arr.push(dir);
-    else m.set(parent, [dir]);
-  }
-  return m;
-})();
-
-/**
- * Folder path → world bounds spanning every descendant district (including
- * the folder itself, when it is a district). A collapsed folder uses these
- * unioned bounds for its umbrella panel.
- */
-const ELECTRON_FOLDER_BOUNDS: Map<
-  string,
-  { minX: number; maxX: number; minZ: number; maxZ: number }
-> = (() => {
-  const m = new Map<
-    string,
-    { minX: number; maxX: number; minZ: number; maxZ: number }
-  >();
-  for (const district of (electronAppCityData as CityData).districts) {
-    const b = district.worldBounds;
-    let path = district.path;
-    while (path) {
-      const cur = m.get(path);
-      if (!cur) {
-        m.set(path, { minX: b.minX, maxX: b.maxX, minZ: b.minZ, maxZ: b.maxZ });
-      } else {
-        if (b.minX < cur.minX) cur.minX = b.minX;
-        if (b.maxX > cur.maxX) cur.maxX = b.maxX;
-        if (b.minZ < cur.minZ) cur.minZ = b.minZ;
-        if (b.maxZ > cur.maxZ) cur.maxZ = b.maxZ;
-      }
-      const slash = path.lastIndexOf('/');
-      if (slash < 0) break;
-      path = path.slice(0, slash);
-    }
-  }
-  return m;
-})();
-
-/**
- * Folder path → number of descendant files. Used to scale folder-panel
- * label text so larger folders read first when scanning the city.
- */
-const ELECTRON_FOLDER_FILE_COUNTS: Map<string, number> = (() => {
-  const m = new Map<string, number>();
-  for (const b of (electronAppCityData as CityData).buildings) {
-    let path = b.path;
-    const slash = path.lastIndexOf('/');
-    path = slash >= 0 ? path.slice(0, slash) : '';
-    while (path) {
-      m.set(path, (m.get(path) ?? 0) + 1);
-      const s = path.lastIndexOf('/');
-      if (s < 0) break;
-      path = path.slice(0, s);
-    }
-  }
-  return m;
-})();
-
-const FOLDER_PALETTE = [
-  '#3b82f6',
-  '#22c55e',
-  '#f59e0b',
-  '#ec4899',
-  '#8b5cf6',
-  '#06b6d4',
-  '#ef4444',
-  '#14b8a6',
-  '#a855f7',
-  '#eab308',
-];
-
-function hashFolderColor(path: string): string {
-  let h = 0;
-  for (let i = 0; i < path.length; i++) {
-    h = (h * 31 + path.charCodeAt(i)) | 0;
-  }
-  return FOLDER_PALETTE[Math.abs(h) % FOLDER_PALETTE.length];
-}
+const ELECTRON_FOLDER_INDEX = buildFolderIndex(electronAppCityData as CityData);
 
 // ---------------------------------------------------------------------------
 // Scope tree paths
@@ -1194,40 +1109,17 @@ const SingleScopeTemplate: React.FC = () => {
   );
 
   // Elevated folder panels — driven by the file tree's expansion state.
-  // Recursively walks from the top-level folders: an expanded folder
-  // descends into its child folders; a collapsed folder emits one panel
-  // covering the union of all descendant district bounds.
   const folderElevatedPanels = React.useMemo<ElevatedScopePanel[] | undefined>(() => {
     if (activeTab !== 'files') return undefined;
-    const panels: ElevatedScopePanel[] = [];
-    const walk = (folderPath: string): void => {
-      if (folderTreeExpansion.expanded.has(folderPath)) {
-        const children = ELECTRON_FOLDER_CHILDREN.get(folderPath) ?? [];
-        for (const child of children) walk(child);
-        return;
-      }
-      const bounds = ELECTRON_FOLDER_BOUNDS.get(folderPath);
-      if (!bounds) return;
-      const label = folderPath.split('/').pop() ?? folderPath;
-      const fileCount = ELECTRON_FOLDER_FILE_COUNTS.get(folderPath) ?? 0;
-      // sqrt growth keeps ~10x file deltas inside a ~3x label-size delta;
-      // the renderer still clamps to the tile footprint.
-      const labelSize = Math.max(12, Math.min(240, 8 + Math.sqrt(fileCount) * 5));
-      panels.push({
-        id: `folder::${folderPath}`,
-        color: hashFolderColor(folderPath),
-        height: 4,
-        thickness: 2,
-        bounds,
-        label,
-        labelSize,
-        onClick: () => {
-          const item = treeModel.getItem(folderPath);
-          if (item?.isDirectory()) item.toggle();
-        },
-      });
-    };
-    for (const top of ELECTRON_FOLDER_CHILDREN.get('') ?? []) walk(top);
+    const panels = buildFolderElevatedPanels({
+      cityData: electronAppCityData as CityData,
+      expandedFolders: folderTreeExpansion.expanded,
+      onToggleFolder: (folderPath) => {
+        const item = treeModel.getItem(folderPath);
+        if (item?.isDirectory()) item.toggle();
+      },
+      index: ELECTRON_FOLDER_INDEX,
+    });
     return panels.length > 0 ? panels : undefined;
   }, [activeTab, treeModel, folderTreeExpansion]);
 
@@ -1647,6 +1539,37 @@ const SingleScopeTemplate: React.FC = () => {
           showControls={true}
         />
 
+        {/* Debug overlay — current focusDirectory */}
+        <div
+          style={{
+            position: 'absolute',
+            top: 16,
+            left: 16,
+            padding: '8px 12px',
+            background: 'rgba(15, 23, 42, 0.92)',
+            border: '1px solid #334155',
+            borderRadius: 6,
+            color: '#e2e8f0',
+            fontFamily: 'system-ui, sans-serif',
+            fontSize: 12,
+            zIndex: 100,
+            maxWidth: 480,
+          }}
+        >
+          <div style={sectionLabelStyle}>focusDirectory</div>
+          <div
+            style={{
+              marginTop: 4,
+              fontFamily: 'monospace',
+              fontSize: 12,
+              color: focusDirectory ? '#fde68a' : '#64748b',
+              wordBreak: 'break-all',
+            }}
+          >
+            {focusDirectory ?? '(null)'}
+          </div>
+        </div>
+
         {/* Info overlay — driven by scope tree selection */}
       {scopeInfo && <ScopeInfoOverlay info={scopeInfo} />}
       </div>

package/src/utils/folderElevatedPanels.ts

@@ -0,0 +1,170 @@
+import type { CityData } from '@principal-ai/file-city-builder';
+import type { ElevatedScopePanel } from '../components/FileCity3D';
+
+const FOLDER_PALETTE = [
+  '#3b82f6',
+  '#22c55e',
+  '#f59e0b',
+  '#ec4899',
+  '#8b5cf6',
+  '#06b6d4',
+  '#ef4444',
+  '#14b8a6',
+  '#a855f7',
+  '#eab308',
+];
+
+/**
+ * Stable color for a folder path, picked from a small palette via a string
+ * hash. Two folders at the same depth get visibly different colors; the
+ * same folder always gets the same color across renders.
+ */
+export function hashFolderColor(path: string): string {
+  let h = 0;
+  for (let i = 0; i < path.length; i++) {
+    h = (h * 31 + path.charCodeAt(i)) | 0;
+  }
+  return FOLDER_PALETTE[Math.abs(h) % FOLDER_PALETTE.length];
+}
+
+interface Bounds {
+  minX: number;
+  maxX: number;
+  minZ: number;
+  maxZ: number;
+}
+
+interface FolderIndex {
+  /** Parent directory → list of immediate child directories. Top-level folders live under '' (empty string). */
+  children: Map<string, string[]>;
+  /** Folder path → world bounds spanning every descendant district. */
+  bounds: Map<string, Bounds>;
+  /** Folder path → number of descendant files. */
+  fileCounts: Map<string, number>;
+}
+
+/**
+ * Precompute the data structures `buildFolderElevatedPanels` needs from a
+ * `CityData`. Cache this when the city data is stable to avoid redoing the
+ * O(districts × depth) walk on every render.
+ */
+export function buildFolderIndex(cityData: CityData): FolderIndex {
+  const children = new Map<string, string[]>();
+  const directorySet = new Set<string>();
+  for (const d of cityData.districts) directorySet.add(d.path);
+  const dirs = Array.from(directorySet).sort();
+  for (const dir of dirs) {
+    const slash = dir.lastIndexOf('/');
+    const parent = slash >= 0 ? dir.slice(0, slash) : '';
+    const arr = children.get(parent);
+    if (arr) arr.push(dir);
+    else children.set(parent, [dir]);
+  }
+
+  const bounds = new Map<string, Bounds>();
+  for (const district of cityData.districts) {
+    const b = district.worldBounds;
+    let path = district.path;
+    while (path) {
+      const cur = bounds.get(path);
+      if (!cur) {
+        bounds.set(path, { minX: b.minX, maxX: b.maxX, minZ: b.minZ, maxZ: b.maxZ });
+      } else {
+        if (b.minX < cur.minX) cur.minX = b.minX;
+        if (b.maxX > cur.maxX) cur.maxX = b.maxX;
+        if (b.minZ < cur.minZ) cur.minZ = b.minZ;
+        if (b.maxZ > cur.maxZ) cur.maxZ = b.maxZ;
+      }
+      const slash = path.lastIndexOf('/');
+      if (slash < 0) break;
+      path = path.slice(0, slash);
+    }
+  }
+
+  const fileCounts = new Map<string, number>();
+  for (const b of cityData.buildings) {
+    let path = b.path;
+    const slash = path.lastIndexOf('/');
+    path = slash >= 0 ? path.slice(0, slash) : '';
+    while (path) {
+      fileCounts.set(path, (fileCounts.get(path) ?? 0) + 1);
+      const s = path.lastIndexOf('/');
+      if (s < 0) break;
+      path = path.slice(0, s);
+    }
+  }
+
+  return { children, bounds, fileCounts };
+}
+
+export interface BuildFolderElevatedPanelsOptions {
+  cityData: CityData;
+  /**
+   * Set of folder paths that are currently expanded in the file tree. A folder
+   * not in this set is treated as collapsed.
+   */
+  expandedFolders: ReadonlySet<string>;
+  /** Toggle handler invoked when an umbrella tile is clicked. */
+  onToggleFolder?: (folderPath: string) => void;
+  /**
+   * Scale label font size by descendant file count. Default true. When false,
+   * the renderer's auto-sized label is used (size derived from tile footprint).
+   */
+  scaleLabelByFileCount?: boolean;
+  /**
+   * Pre-built index from `buildFolderIndex(cityData)`. Pass when you cache the
+   * city's index across renders to avoid recomputing it.
+   */
+  index?: FolderIndex;
+}
+
+/**
+ * Walks the folder hierarchy from the top-level folders of a `CityData`. For
+ * each folder:
+ *   - if expanded → recurse into child folders
+ *   - if collapsed → emit one elevated panel covering the union of every
+ *     descendant district's world bounds, colored via `hashFolderColor`.
+ *
+ * Mirror of the scope-tree expansion behavior, applied to file-tree folders.
+ */
+export function buildFolderElevatedPanels(
+  options: BuildFolderElevatedPanelsOptions,
+): ElevatedScopePanel[] {
+  const {
+    cityData,
+    expandedFolders,
+    onToggleFolder,
+    scaleLabelByFileCount = true,
+  } = options;
+  const index = options.index ?? buildFolderIndex(cityData);
+
+  const panels: ElevatedScopePanel[] = [];
+
+  const walk = (folderPath: string): void => {
+    if (expandedFolders.has(folderPath)) {
+      const kids = index.children.get(folderPath) ?? [];
+      for (const child of kids) walk(child);
+      return;
+    }
+    const bounds = index.bounds.get(folderPath);
+    if (!bounds) return;
+    const label = folderPath.split('/').pop() ?? folderPath;
+    const fileCount = index.fileCounts.get(folderPath) ?? 0;
+    const labelSize = scaleLabelByFileCount
+      ? Math.max(12, Math.min(240, 8 + Math.sqrt(fileCount) * 5))
+      : undefined;
+    panels.push({
+      id: `folder::${folderPath}`,
+      color: hashFolderColor(folderPath),
+      height: 4,
+      thickness: 2,
+      bounds,
+      label,
+      labelSize,
+      onClick: onToggleFolder ? () => onToggleFolder(folderPath) : undefined,
+    });
+  };
+
+  for (const top of index.children.get('') ?? []) walk(top);
+  return panels;
+}