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

package/dist/components/FileCityExplorer/ScopeInfoOverlay.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import type { Event, Namespace, Scope } from './model';
+export declare const ScopeInfoOverlay: React.FC<{
+    info: {
+        scope: Scope;
+        ns: Namespace | null;
+        ev: Event | null;
+    };
+}>;
+//# sourceMappingURL=ScopeInfoOverlay.d.ts.map

package/dist/components/FileCityExplorer/ScopeInfoOverlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScopeInfoOverlay.d.ts","sourceRoot":"","sources":["../../../src/components/FileCityExplorer/ScopeInfoOverlay.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGvD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC;IACtC,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAC;QAAC,EAAE,EAAE,KAAK,GAAG,IAAI,CAAA;KAAE,CAAC;CAChE,CA6NA,CAAC"}

package/dist/components/FileCityExplorer/ScopeInfoOverlay.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useTheme } from '@principal-ade/industry-theme';
+import { makeOverlayStyle, makeSectionLabelStyle } from './styles';
+export const ScopeInfoOverlay = ({ info }) => {
+    const { theme } = useTheme();
+    const overlayStyle = makeOverlayStyle(theme);
+    const sectionLabelStyle = makeSectionLabelStyle(theme);
+    const severityBg = {
+        ERROR: theme.colors.error,
+        WARN: theme.colors.warning,
+        INFO: theme.colors.info,
+    };
+    const defaultSeverityBg = theme.colors.backgroundSecondary;
+    const sectionDivider = `1px solid ${theme.colors.backgroundSecondary}`;
+    const codeChipStyle = {
+        fontSize: theme.fontSizes[0],
+        color: theme.colors.textSecondary,
+        background: theme.colors.backgroundDark ?? theme.colors.background,
+        padding: '4px 6px',
+        borderRadius: theme.radii[2],
+        wordBreak: 'break-all',
+    };
+    const { scope, ns, ev } = info;
+    // Event leaf selected — show event detail.
+    if (ns && ev) {
+        return (_jsxs("div", { style: overlayStyle, children: [_jsxs("div", { style: { padding: '14px 16px', borderBottom: sectionDivider }, children: [_jsx("div", { style: sectionLabelStyle, children: "Event" }), _jsx("div", { style: { fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[1], marginTop: 6 }, children: ev.name }), ev.severity && (_jsx("div", { style: {
+                                display: 'inline-block',
+                                fontSize: theme.fontSizes[0],
+                                marginTop: theme.space[2],
+                                padding: '2px 6px',
+                                borderRadius: theme.radii[1],
+                                background: severityBg[ev.severity] ?? defaultSeverityBg,
+                                color: theme.colors.highlight,
+                            }, children: ev.severity })), ev.description && (_jsx("div", { style: { fontSize: theme.fontSizes[0], color: theme.colors.textSecondary, marginTop: 10, lineHeight: 1.5 }, children: ev.description }))] }), _jsxs("div", { style: { padding: '14px 16px' }, children: [_jsx("div", { style: sectionLabelStyle, children: "Owning namespace" }), _jsxs("div", { style: { marginTop: 6, display: 'flex', alignItems: 'center', gap: theme.space[2] }, children: [_jsx("span", { style: { width: 12, height: 12, borderRadius: theme.radii[1], background: ns.color, flexShrink: 0 } }), _jsx("span", { style: { fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[1] }, children: ns.name })] }), _jsx("div", { style: { fontSize: theme.fontSizes[0], color: theme.colors.textTertiary, marginTop: 14, fontStyle: 'italic' }, children: "Files-per-event mapping not wired yet \u2014 for now the event highlights its parent namespace's paths." })] })] }));
+    }
+    // Namespace selected — show namespace detail.
+    if (ns) {
+        return (_jsxs("div", { style: overlayStyle, children: [_jsxs("div", { style: { padding: '14px 16px', borderBottom: sectionDivider }, children: [_jsx("div", { style: sectionLabelStyle, children: "Namespace" }), _jsxs("div", { style: { marginTop: 6, display: 'flex', alignItems: 'center', gap: theme.space[2] }, children: [_jsx("span", { style: { width: 12, height: 12, borderRadius: theme.radii[1], background: ns.color, flexShrink: 0 } }), _jsx("span", { style: { fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[1] }, children: ns.name })] }), _jsx("div", { style: { fontSize: theme.fontSizes[0], color: theme.colors.textMuted, marginTop: theme.space[2], lineHeight: 1.5 }, children: ns.description }), _jsxs("div", { style: { fontSize: theme.fontSizes[0], color: theme.colors.textTertiary, marginTop: theme.space[2] }, children: ["in ", _jsx("span", { style: { fontFamily: theme.fonts.monospace }, children: scope.id })] })] }), _jsxs("div", { style: { padding: '14px 16px', borderBottom: sectionDivider }, children: [_jsxs("div", { style: sectionLabelStyle, children: ["Claimed paths (", ns.paths.length, ")"] }), _jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: theme.space[1], marginTop: 6 }, children: ns.paths.map(p => (_jsx("code", { style: codeChipStyle, children: p }, p))) })] }), _jsxs("div", { style: { padding: '14px 16px' }, children: [_jsxs("div", { style: sectionLabelStyle, children: ["Events (", ns.events.length, ")"] }), _jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: theme.space[1], marginTop: 6 }, children: ns.events.map(e => (_jsxs("div", { style: {
+                                    display: 'flex',
+                                    alignItems: 'center',
+                                    gap: 6,
+                                    padding: '4px 6px',
+                                    background: theme.colors.backgroundDark ?? theme.colors.background,
+                                    borderRadius: theme.radii[2],
+                                }, children: [e.severity && (_jsx("span", { style: {
+                                            fontSize: theme.fontSizes[0],
+                                            padding: '1px 4px',
+                                            borderRadius: theme.radii[1],
+                                            background: severityBg[e.severity] ?? defaultSeverityBg,
+                                            color: theme.colors.highlight,
+                                            flexShrink: 0,
+                                        }, children: e.severity })), _jsx("code", { style: { fontSize: theme.fontSizes[0], color: theme.colors.textSecondary }, children: e.name })] }, e.name))) })] })] }));
+    }
+    // Scope selected — show scope summary.
+    const totalEvents = scope.namespaces.reduce((n, x) => n + x.events.length, 0);
+    return (_jsxs("div", { style: overlayStyle, children: [_jsxs("div", { style: { padding: '14px 16px', borderBottom: sectionDivider }, children: [_jsx("div", { style: sectionLabelStyle, children: "Scope" }), _jsx("div", { style: { fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[1], marginTop: 6 }, children: scope.id }), _jsx("div", { style: { fontSize: theme.fontSizes[0], color: theme.colors.textMuted, marginTop: theme.space[2], lineHeight: 1.5 }, children: scope.description }), _jsxs("div", { style: { display: 'flex', gap: theme.space[3], marginTop: 12, fontSize: theme.fontSizes[0], color: theme.colors.textTertiary }, children: [_jsxs("div", { children: [_jsx("div", { children: scope.paths.length }), _jsx("div", { style: sectionLabelStyle, children: "scope paths" })] }), _jsxs("div", { children: [_jsx("div", { children: scope.namespaces.length }), _jsx("div", { style: sectionLabelStyle, children: "namespaces" })] }), _jsxs("div", { children: [_jsx("div", { children: totalEvents }), _jsx("div", { style: sectionLabelStyle, children: "events" })] })] })] }), scope.paths.length > 0 && (_jsxs("div", { style: { padding: '14px 16px', borderBottom: sectionDivider }, children: [_jsxs("div", { style: sectionLabelStyle, children: ["Scope-level paths (", scope.paths.length, ")"] }), _jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: theme.space[1], marginTop: 6 }, children: scope.paths.map(p => (_jsx("code", { style: codeChipStyle, children: p }, p))) })] })), _jsxs("div", { style: { padding: '14px 16px' }, children: [_jsx("div", { style: sectionLabelStyle, children: "Namespaces" }), _jsx("div", { style: { display: 'flex', flexDirection: 'column', gap: theme.space[2], marginTop: theme.space[2] }, children: scope.namespaces.map(n => (_jsxs("div", { style: {
+                                padding: theme.space[2],
+                                background: theme.colors.backgroundDark ?? theme.colors.background,
+                                borderRadius: theme.radii[3],
+                            }, children: [_jsxs("div", { style: { display: 'flex', alignItems: 'center', gap: theme.space[2] }, children: [_jsx("span", { style: {
+                                                width: 10,
+                                                height: 10,
+                                                borderRadius: theme.radii[1],
+                                                background: n.color,
+                                                flexShrink: 0,
+                                            } }), _jsx("span", { style: { fontFamily: theme.fonts.monospace, fontSize: theme.fontSizes[0] }, children: n.name }), _jsxs("span", { style: { fontSize: theme.fontSizes[0], color: theme.colors.textTertiary, marginLeft: 'auto' }, children: [n.events.length, " event", n.events.length === 1 ? '' : 's'] })] }), _jsx("div", { style: {
+                                        fontSize: theme.fontSizes[0],
+                                        color: theme.colors.textTertiary,
+                                        fontFamily: theme.fonts.monospace,
+                                        marginTop: theme.space[1],
+                                        wordBreak: 'break-all',
+                                    }, children: n.paths.join(' · ') })] }, n.name))) })] })] }));
+};

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

@@ -0,0 +1,3 @@
+export { FileCityExplorer, type FileCityExplorerProps } from './FileCityExplorer';
+export type { Event, Namespace, ProjectArea, Scope } from './model';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/FileCityExplorer/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/FileCityExplorer/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAClF,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC"}

package/dist/components/FileCityExplorer/index.js

@@ -0,0 +1 @@
+export { FileCityExplorer } from './FileCityExplorer';

package/dist/components/FileCityExplorer/layers.d.ts

@@ -0,0 +1,16 @@
+import type { HighlightLayer } from '../FileCity3D';
+import type { Scope } from './model';
+export declare const NAMESPACE_PALETTE: string[];
+/** Colour used for area umbrella tiles and their picker swatches. */
+export declare const AREA_PANEL_COLOR = "#64748b";
+export declare function pickNamespaceColor(scopes: readonly Scope[]): string;
+/**
+ * Build highlight layers for a scope: one fill layer per namespace plus a
+ * border-only layer for scope-level paths. Priority is path depth (longest-
+ * prefix wins) per the partition convention in docs/scope-namespace-overlay.md.
+ *
+ * `toCityPath` translates scope-relative paths back to city paths so
+ * districts can be matched.
+ */
+export declare function buildLayersForScope(scope: Scope, toCityPath: (scopePath: string) => string): HighlightLayer[];
+//# sourceMappingURL=layers.d.ts.map

package/dist/components/FileCityExplorer/layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layers.d.ts","sourceRoot":"","sources":["../../../src/components/FileCityExplorer/layers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,eAAO,MAAM,iBAAiB,UAW7B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,YAAY,CAAC;AAE1C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,CAMnE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,KAAK,EACZ,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,GACxC,cAAc,EAAE,CAiClB"}

package/dist/components/FileCityExplorer/layers.js

@@ -0,0 +1,61 @@
+export const NAMESPACE_PALETTE = [
+    '#22c55e',
+    '#3b82f6',
+    '#f59e0b',
+    '#ec4899',
+    '#8b5cf6',
+    '#06b6d4',
+    '#ef4444',
+    '#14b8a6',
+    '#a855f7',
+    '#eab308',
+];
+/** Colour used for area umbrella tiles and their picker swatches. */
+export const AREA_PANEL_COLOR = '#64748b';
+export function pickNamespaceColor(scopes) {
+    const used = new Set(scopes.flatMap(s => s.namespaces.map(n => n.color)));
+    return (NAMESPACE_PALETTE.find(c => !used.has(c)) ??
+        NAMESPACE_PALETTE[scopes.length % NAMESPACE_PALETTE.length]);
+}
+/**
+ * Build highlight layers for a scope: one fill layer per namespace plus a
+ * border-only layer for scope-level paths. Priority is path depth (longest-
+ * prefix wins) per the partition convention in docs/scope-namespace-overlay.md.
+ *
+ * `toCityPath` translates scope-relative paths back to city paths so
+ * districts can be matched.
+ */
+export function buildLayersForScope(scope, toCityPath) {
+    const layers = scope.namespaces.map(ns => {
+        const maxDepth = Math.max(1, ...ns.paths.map(p => p.split('/').length));
+        return {
+            id: `${scope.id}::${ns.name}`,
+            name: ns.name,
+            enabled: true,
+            color: ns.color,
+            opacity: 0.55,
+            priority: maxDepth,
+            items: ns.paths.map(p => ({
+                path: toCityPath(p),
+                type: 'directory',
+                renderStrategy: 'fill',
+            })),
+        };
+    });
+    if (scope.paths.length > 0) {
+        layers.push({
+            id: `${scope.id}::__scope__`,
+            name: `${scope.id} (scope-level)`,
+            enabled: true,
+            color: '#64748b',
+            opacity: 0.4,
+            priority: 0,
+            items: scope.paths.map(p => ({
+                path: toCityPath(p),
+                type: 'directory',
+                renderStrategy: 'fill',
+            })),
+        });
+    }
+    return layers;
+}

package/dist/components/FileCityExplorer/model.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Scope / namespace / area model for the explorer.
+ *
+ * `Event` and `Namespace` are derived from the upstream
+ * `EventNamespaceNode['namespace']` shape in `@principal-ai/principal-view-core`.
+ * `Namespace` adds a UI-required `color` (palette pick).
+ *
+ * `Scope` stays local: it flattens namespaces inline (`scope.namespaces[]`),
+ * which the upstream canvas-node split (`OtelScopeNode` + per-scope
+ * `*.events.canvas`) doesn't model. Treat as an explorer view-model.
+ *
+ * `ProjectArea` is re-exported directly from upstream.
+ */
+import type { EventNamespaceNode } from '@principal-ai/principal-view-core';
+export type { ProjectArea } from '@principal-ai/principal-view-core';
+export type Event = EventNamespaceNode['namespace']['events'][number];
+export type Namespace = EventNamespaceNode['namespace'] & {
+    /** UI palette pick — not part of the upstream canvas-node shape. */
+    color: string;
+    /** Required here even though upstream allows `paths?` — explorer always sets it. */
+    paths: string[];
+};
+export interface Scope {
+    /** Maps to `OtelScopeNode.otel.scope` upstream. */
+    id: string;
+    name: string;
+    description: string;
+    /** Scope-level paths — corresponds to optional `OtelScopeNode.paths` upstream. */
+    paths: string[];
+    namespaces: Namespace[];
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/components/FileCityExplorer/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/components/FileCityExplorer/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,YAAY,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAErE,MAAM,MAAM,KAAK,GAAG,kBAAkB,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,MAAM,MAAM,SAAS,GAAG,kBAAkB,CAAC,WAAW,CAAC,GAAG;IACxD,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,WAAW,KAAK;IACpB,mDAAmD;IACnD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,SAAS,EAAE,CAAC;CACzB"}

package/dist/components/FileCityExplorer/model.js

@@ -0,0 +1,14 @@
+/**
+ * Scope / namespace / area model for the explorer.
+ *
+ * `Event` and `Namespace` are derived from the upstream
+ * `EventNamespaceNode['namespace']` shape in `@principal-ai/principal-view-core`.
+ * `Namespace` adds a UI-required `color` (palette pick).
+ *
+ * `Scope` stays local: it flattens namespaces inline (`scope.namespaces[]`),
+ * which the upstream canvas-node split (`OtelScopeNode` + per-scope
+ * `*.events.canvas`) doesn't model. Treat as an explorer view-model.
+ *
+ * `ProjectArea` is re-exported directly from upstream.
+ */
+export {};

package/dist/components/FileCityExplorer/pathConversion.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Path converters for the explorer.
+ *
+ * City data is rooted at `packageRoot` (e.g. `electron-app/`). Scope/namespace
+ * paths are authored relative to the package root (matching how principal-view
+ * canvases are stored). These converters round-trip between the two
+ * representations.
+ *
+ * `packageRoot` should include a trailing slash. Pass `''` if the city data
+ * is already rooted at the project root.
+ */
+export interface PathConverters {
+    /** City path → scope/namespace path (strip the package-root prefix). */
+    toScopePath: (cityPath: string) => string;
+    /** Scope/namespace path → city path (re-add the package-root prefix). */
+    toCityPath: (scopePath: string) => string;
+}
+export declare function createPathConverters(packageRoot: string): PathConverters;
+//# sourceMappingURL=pathConversion.d.ts.map

package/dist/components/FileCityExplorer/pathConversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathConversion.d.ts","sourceRoot":"","sources":["../../../src/components/FileCityExplorer/pathConversion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1C,yEAAyE;IACzE,UAAU,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAED,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAYxE"}

package/dist/components/FileCityExplorer/pathConversion.js

@@ -0,0 +1,26 @@
+/**
+ * Path converters for the explorer.
+ *
+ * City data is rooted at `packageRoot` (e.g. `electron-app/`). Scope/namespace
+ * paths are authored relative to the package root (matching how principal-view
+ * canvases are stored). These converters round-trip between the two
+ * representations.
+ *
+ * `packageRoot` should include a trailing slash. Pass `''` if the city data
+ * is already rooted at the project root.
+ */
+export function createPathConverters(packageRoot) {
+    return {
+        toScopePath(cityPath) {
+            let p = cityPath.endsWith('/') ? cityPath.slice(0, -1) : cityPath;
+            if (packageRoot && p.startsWith(packageRoot))
+                p = p.slice(packageRoot.length);
+            return p;
+        },
+        toCityPath(scopePath) {
+            if (!packageRoot)
+                return scopePath;
+            return scopePath.startsWith(packageRoot) ? scopePath : packageRoot + scopePath;
+        },
+    };
+}

package/dist/components/FileCityExplorer/scopeTreePaths.d.ts

@@ -0,0 +1,21 @@
+import type { Scope } from './model';
+export interface ScopeTreeSelection {
+    scopeId: string;
+    namespaceName?: string;
+    eventName?: string;
+}
+/**
+ * Sentinel leaves used when a scope has no namespaces or a namespace has no
+ * events — the trees library infers directories from paths, so empty branches
+ * need a placeholder leaf to render.
+ */
+export declare const EMPTY_NS_SENTINEL = "(no namespaces)";
+export declare const EMPTY_EVENTS_SENTINEL = "(no events)";
+/**
+ * Build canonical paths for the scope tree: `<scope.id>/<namespace.name>/<event.name>`.
+ * Scopes are top-level directories, namespaces children, events leaves.
+ * Empty scopes/namespaces emit a sentinel leaf so they still appear.
+ */
+export declare function buildScopeTreePaths(scopes: readonly Scope[]): string[];
+export declare function parseScopeTreePath(path: string): ScopeTreeSelection;
+//# sourceMappingURL=scopeTreePaths.d.ts.map

package/dist/components/FileCityExplorer/scopeTreePaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeTreePaths.d.ts","sourceRoot":"","sources":["../../../src/components/FileCityExplorer/scopeTreePaths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AACnD,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,EAAE,CAkBtE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAUnE"}

package/dist/components/FileCityExplorer/scopeTreePaths.js

@@ -0,0 +1,42 @@
+/**
+ * Sentinel leaves used when a scope has no namespaces or a namespace has no
+ * events — the trees library infers directories from paths, so empty branches
+ * need a placeholder leaf to render.
+ */
+export const EMPTY_NS_SENTINEL = '(no namespaces)';
+export const EMPTY_EVENTS_SENTINEL = '(no events)';
+/**
+ * Build canonical paths for the scope tree: `<scope.id>/<namespace.name>/<event.name>`.
+ * Scopes are top-level directories, namespaces children, events leaves.
+ * Empty scopes/namespaces emit a sentinel leaf so they still appear.
+ */
+export function buildScopeTreePaths(scopes) {
+    const out = [];
+    for (const scope of scopes) {
+        if (scope.namespaces.length === 0) {
+            out.push(`${scope.id}/${EMPTY_NS_SENTINEL}`);
+            continue;
+        }
+        for (const ns of scope.namespaces) {
+            if (ns.events.length === 0) {
+                out.push(`${scope.id}/${ns.name}/${EMPTY_EVENTS_SENTINEL}`);
+                continue;
+            }
+            for (const ev of ns.events) {
+                out.push(`${scope.id}/${ns.name}/${ev.name}`);
+            }
+        }
+    }
+    return out;
+}
+export function parseScopeTreePath(path) {
+    const [scopeId, namespaceName, eventName] = path.split('/');
+    const result = { scopeId };
+    if (namespaceName && namespaceName !== EMPTY_NS_SENTINEL) {
+        result.namespaceName = namespaceName;
+    }
+    if (eventName && eventName !== EMPTY_EVENTS_SENTINEL) {
+        result.eventName = eventName;
+    }
+    return result;
+}

package/dist/components/FileCityExplorer/styles.d.ts

@@ -0,0 +1,9 @@
+import type React from 'react';
+import type { Theme } from '@principal-ade/industry-theme';
+/** Translucent overlay using the theme's background colour. */
+export declare const withAlpha: (color: string, percent: number) => string;
+/** Reused across overlays, modals, and the selected-folder card. */
+export declare const makeSectionLabelStyle: (theme: Theme) => React.CSSProperties;
+/** Frame style for the right-side info overlay. */
+export declare const makeOverlayStyle: (theme: Theme) => React.CSSProperties;
+//# sourceMappingURL=styles.d.ts.map

package/dist/components/FileCityExplorer/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../../src/components/FileCityExplorer/styles.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AAE3D,+DAA+D;AAC/D,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,EAAE,SAAS,MAAM,KAAG,MACD,CAAC;AAE3D,oEAAoE;AACpE,eAAO,MAAM,qBAAqB,GAAI,OAAO,KAAK,KAAG,KAAK,CAAC,aAKzD,CAAC;AAEH,mDAAmD;AACnD,eAAO,MAAM,gBAAgB,GAAI,OAAO,KAAK,KAAG,KAAK,CAAC,aAiBpD,CAAC"}

package/dist/components/FileCityExplorer/styles.js

@@ -0,0 +1,28 @@
+/** Translucent overlay using the theme's background colour. */
+export const withAlpha = (color, percent) => `color-mix(in oklab, ${color} ${percent}%, transparent)`;
+/** Reused across overlays, modals, and the selected-folder card. */
+export const makeSectionLabelStyle = (theme) => ({
+    fontSize: theme.fontSizes[0],
+    color: theme.colors.textTertiary,
+    textTransform: 'uppercase',
+    letterSpacing: 0.5,
+});
+/** Frame style for the right-side info overlay. */
+export const makeOverlayStyle = (theme) => ({
+    position: 'absolute',
+    top: 16,
+    left: 16,
+    width: 360,
+    maxHeight: 'calc(100vh - 32px)',
+    overflowY: 'auto',
+    background: withAlpha(theme.colors.background, 72),
+    backdropFilter: 'blur(8px)',
+    WebkitBackdropFilter: 'blur(8px)',
+    border: `1px solid ${theme.colors.border}`,
+    borderRadius: theme.radii[4],
+    color: theme.colors.text,
+    fontFamily: theme.fonts.body,
+    fontSize: theme.fontSizes[1],
+    zIndex: 100,
+    boxShadow: theme.shadows[3],
+});

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,62 @@
+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, event: MouseEvent) => void;
+    /** Double-click handler for an umbrella tile. */
+    onDoubleClickFolder?: (folderPath: string, event: MouseEvent) => 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,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACjE,iDAAiD;IACjD,mBAAmB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACtE;;;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,CA0CtB"}

package/dist/utils/folderElevatedPanels.js

@@ -0,0 +1,130 @@
+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, onDoubleClickFolder, 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 ? (event) => onToggleFolder(folderPath, event) : undefined,
+            onDoubleClick: onDoubleClickFolder
+                ? (event) => onDoubleClickFolder(folderPath, event)
+                : undefined,
+        });
+    };
+    for (const top of index.children.get('') ?? [])
+        walk(top);
+    return panels;
+}