Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

fix(ui): keep folder and lane names clear of the map chips

Bernhard Jackiewiczca9382d511f9
diff --git a/graph-ui/src/architecture/ArchitectureScene.tsx b/graph-ui/src/architecture/ArchitectureScene.tsx
index 4a6688cd0..2f8638e79 100644
--- a/graph-ui/src/architecture/ArchitectureScene.tsx
+++ b/graph-ui/src/architecture/ArchitectureScene.tsx
@@ -6,7 +6,7 @@ import type { OrbitControls as OrbitControlsImpl } from 'three-stdlib';
import type { SemanticEdge, SemanticGraph, SemanticNode, SemanticPlatform } from './semantic-graph';
import { languageColor, measureSourceNode, scopeBrickHeights, sourceLanguage, sourceNodeSizePercent, type SourceCatalog, type SourceMeasure } from './source-metrics';
import { gravityPercent, gravityStrength, hotspotsForNode, type HotspotCatalog, type HotspotGroup } from './hotspot-map';
-import { labelEdges, labelInset, labelRect, labelsCollide, type LabelBox, type LabelRect } from './label-space';
+import { labelEdges, labelInset, labelRect, labelsCollide, placeSecondaryLabels, type LabelBox, type LabelRect, type SecondaryLabel } from './label-space';
import { edgeColor, isDirectedEdge } from '../graph/edge-style';
import { EdgePulseLayer } from '../graph/EdgePulseLayer';
import './architecture-scene.css';
@@ -49,17 +49,29 @@ function centerOf(node: RenderNode): Vector3 {
return new Vector3(...node.position).add(new Vector3(0, dimensions(node)[1] / 2, 0));
}
+/**
+ * The corners a platform name may take, relative to the platform centre: the
+ * front-left corner first (where it always sat), then the others. The label
+ * manager picks the first one no chip or other name covers.
+ */
+function folderSpots(platform: SemanticPlatform): { local: [number, number, number]; align: 'start' | 'end' }[] {
+ const x = platform.width / 2 - 3, front = platform.depth / 2 - 2, back = -platform.depth / 2 + 2;
+ return [{ local: [-x, 0.12, front], align: 'start' }, { local: [-x, 0.12, back], align: 'start' },
+ { local: [x, 0.12, front], align: 'end' }, { local: [x, 0.12, back], align: 'end' }];
+}
+
/** Folder containment is scenery, never an extra dependency or selectable symbol. */
-function FolderPlatform({ platform }: { platform: SemanticPlatform }) {
+function FolderPlatform({ platform, spot = 0 }: { platform: SemanticPlatform; spot?: number }) {
+ const place = folderSpots(platform)[Math.max(0, spot)]!;
return <group position={platform.position}>
<mesh position={[0, -0.225, 0]} raycast={() => null}>
<boxGeometry args={[platform.width, 0.45, platform.depth]} />
<meshStandardMaterial color={SCENE_PALETTE.plate} roughness={0.95} transparent opacity={0.11 + platform.level * 0.015} depthWrite={false} />
<Edges color={SCENE_PALETTE.plateEdge} transparent opacity={0.3} />
</mesh>
- <Html position={[-platform.width / 2 + 3, 0.12, platform.depth / 2 - 2]} zIndexRange={[5, 1]} style={{ pointerEvents: 'none' }}>
- <span className="architecture-folder-label" data-folder-path={platform.path} data-level={platform.level}
- data-position={platform.position.join(',')} data-width={platform.width} data-depth={platform.depth}
+ <Html position={place.local} zIndexRange={[5, 1]} style={{ pointerEvents: 'none' }}>
+ <span className={`architecture-folder-label${spot < 0 ? ' is-hidden' : ''}`} data-folder-id={platform.id} data-folder-path={platform.path} data-level={platform.level}
+ data-position={platform.position.join(',')} data-width={platform.width} data-depth={platform.depth} data-align={place.align}
title={platform.path}>{platform.path ? platform.path.split('/').at(-1) : platform.label}</span>
</Html>
</group>;
@@ -182,31 +194,52 @@ function ArchitectureNode({ node, selected, highlighted, dimmed, labelVisible =
</group>;
}
+/** Folder names claim space outermost first; the lane of outside areas first of all. */
+const folderPriority = (a: SemanticPlatform, b: SemanticPlatform) => Number(b.id === 'hierarchy:outside') - Number(a.id === 'hierarchy:outside')
+ || a.level - b.level || b.width * b.depth - a.width * a.depth || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
/**
* Screen-space label density changes with zoom; source positions never do.
* Label boxes are measured once per model, so culling follows the CSS of the
* map that shows them (the compact Overview labels are far smaller than the
* service map's); the estimate only covers a label not laid out yet.
+ *
+ * Without culling every chip stays, but the folder names still go where no
+ * chip and no other name lies: the chips are placed first, then each folder
+ * name takes a free corner of its platform or hides.
*/
-function HotspotLabels({ model, priorityId, onVisible }: { model: RenderGraph; priorityId?: string; onVisible: (ids: Set<string>) => void }) {
+function SceneLabels({ model, priorityId, cull, onVisible, onFolders }: {
+ model: RenderGraph; priorityId?: string; cull: boolean;
+ onVisible: (ids: Set<string>) => void; onFolders: (spots: Map<string, number>) => void;
+}) {
const { camera, size, gl, events, invalidate } = useThree();
// Html labels mount where drei puts them: the event source, else the canvas parent.
const labelHost = (events.connected as HTMLElement | undefined) ?? gl.domElement.parentElement;
const previous = useRef('');
+ const previousFolders = useRef('');
const boxes = useRef(new Map<string, LabelBox>());
+ const folderBoxes = useRef(new Map<string, { width: number; height: number }>());
const attempts = useRef(0);
- useEffect(() => { boxes.current.clear(); attempts.current = 0; }, [model]);
+ useEffect(() => { boxes.current.clear(); folderBoxes.current.clear(); attempts.current = 0; }, [model]);
useFrame(() => {
- const unmeasured = () => model.nodes.some(node => !boxes.current.has(node.id));
- if (unmeasured()) labelHost?.querySelectorAll<HTMLElement>('.architecture-node-label[data-node-id]').forEach(label => {
- // A selected label carries extra rows; it is the priority label and keeps its reserve below.
- if (!label.offsetWidth || label.classList.contains('is-selected')) return;
- const [edgeX, edgeY] = labelEdges(getComputedStyle(label));
- boxes.current.set(label.dataset.nodeId!, { width: label.offsetWidth, height: label.offsetHeight, edgeX, edgeY });
- });
+ const platforms = model.platforms ?? [];
+ const unmeasured = () => model.nodes.some(node => !boxes.current.has(node.id)) || platforms.some(platform => !folderBoxes.current.has(platform.id));
+ if (unmeasured()) {
+ labelHost?.querySelectorAll<HTMLElement>('.architecture-node-label[data-node-id]').forEach(label => {
+ // A selected label carries extra rows; it is the priority label and keeps its reserve below.
+ if (!label.offsetWidth || label.classList.contains('is-selected')) return;
+ const [edgeX, edgeY] = labelEdges(getComputedStyle(label));
+ boxes.current.set(label.dataset.nodeId!, { width: label.offsetWidth, height: label.offsetHeight, edgeX, edgeY });
+ });
+ labelHost?.querySelectorAll<HTMLElement>('.architecture-folder-label[data-folder-id]').forEach(label => {
+ if (label.offsetWidth) folderBoxes.current.set(label.dataset.folderId!, { width: label.offsetWidth, height: label.offsetHeight });
+ });
+ }
// A measured label may overlap a neighbour by its padding, never by its text.
const inset = labelInset(boxes.current.values());
const occupied: LabelRect[] = [];
+ // A folder name may not sit under any part of a chip: its whole box counts.
+ const chips: LabelRect[] = [];
const ids = new Set<string>();
// Hotspot wells, then larger parts, claim their label space first.
const ordered = [...model.nodes].sort((a, b) => Number(b.id === priorityId) - Number(a.id === priorityId)
@@ -218,12 +251,24 @@ function HotspotLabels({ model, priorityId, onVisible }: { model: RenderGraph; p
const width = box?.width ?? Math.min(178, Math.max(78, (node.shortLabel ?? node.label).length * 7 + (node.gravityPercent === undefined ? 26 : 68)));
const height = node.id === priorityId ? 96 : box?.height ?? 38;
const rect = labelRect(x, y, width, height, box ? inset : [-5, 0]);
- if (node.id !== priorityId && (rect.right < 0 || rect.left > size.width || rect.bottom < 0 || rect.top > size.height
+ if (cull && node.id !== priorityId && (rect.right < 0 || rect.left > size.width || rect.bottom < 0 || rect.top > size.height
|| occupied.some(other => labelsCollide(rect, other)))) continue;
- ids.add(node.id); occupied.push(rect);
+ ids.add(node.id); occupied.push(rect); chips.push(labelRect(x, y, width, height, [0, 0]));
}
const key = [...ids].sort().join('|');
if (previous.current !== key) { previous.current = key; onVisible(ids); }
+ const names: SecondaryLabel[] = [...platforms].sort(folderPriority).map(platform => {
+ const measured = folderBoxes.current.get(platform.id);
+ const text = platform.path ? platform.path.split('/').at(-1) ?? '' : platform.label;
+ return { id: platform.id, width: measured?.width ?? Math.min(150, text.length * 6.5 + 4), height: measured?.height ?? 14,
+ spots: folderSpots(platform).map(({ local, align }) => {
+ const point = new Vector3(...platform.position).add(new Vector3(...local)).project(camera);
+ return { x: (point.x + 1) * size.width / 2, y: (1 - point.y) * size.height / 2, align };
+ }) };
+ });
+ const spots = placeSecondaryLabels(names, chips, size.width, size.height);
+ const folderKey = [...spots].map(([id, spot]) => `${id}:${spot}`).join('|');
+ if (previousFolders.current !== folderKey) { previousFolders.current = folderKey; onFolders(spots); }
// Labels mount a moment after the scene; a few extra frames pick up their real size.
if (unmeasured() && attempts.current++ < 8) invalidate();
});
@@ -301,6 +346,7 @@ export function ArchitectureScene({ model: graphModel, selectedId, selectedEdgeI
const [hoveredId, setHoveredId] = useState<string>();
const [hoveredEdgeId, setHoveredEdgeId] = useState<string>();
const [visibleHotspotLabels, setVisibleHotspotLabels] = useState<Set<string>>();
+ const [folderSpotsShown, setFolderSpotsShown] = useState<Map<string, number>>();
const background = useGraphBackgroundReset(() => { setHoveredId(undefined); setHoveredEdgeId(undefined); onClearSelection?.(); });
const controls = useRef<OrbitControlsImpl | null>(null);
const nodesById = useMemo(() => new Map(model.nodes.map(node => [node.id, node])), [model.nodes]);
@@ -354,7 +400,7 @@ export function ArchitectureScene({ model: graphModel, selectedId, selectedEdgeI
<directionalLight position={[30, 80, 20]} intensity={2.4} color={SCENE_PALETTE.keyLight} />
<directionalLight position={[-20, 20, -30]} intensity={1.2} color={SCENE_PALETTE.fillLight} />
<gridHelper args={[extent, Math.min(80, Math.ceil(extent / 12)), SCENE_PALETTE.gridMajor, SCENE_PALETTE.gridMinor]} position={[0, floorY, 0]} />
- {model.platforms?.map(platform => <FolderPlatform key={platform.id} platform={platform} />)}
+ {model.platforms?.map(platform => <FolderPlatform key={platform.id} platform={platform} spot={folderSpotsShown?.get(platform.id)} />)}
{model.nodes.filter(node => node.gravity).map(node => <GravityWell key={`gravity:${node.id}`} node={node} floorY={floorY} dimmed={related.size > 0 && !related.has(node.id)} />)}
{model.edges.map(edge => {
const geometry = edgeGeometry.get(edge.id);
@@ -374,7 +420,7 @@ export function ArchitectureScene({ model: graphModel, selectedId, selectedEdgeI
touches={{ ONE: planar ? TOUCH.PAN : TOUCH.ROTATE, TWO: TOUCH.DOLLY_PAN }}
minZoom={0.15} maxZoom={60} rotateSpeed={0.5} zoomSpeed={0.8} maxPolarAngle={SCENE_MAX_TILT} zoomToCursor />
<FitArchitecture model={model} planar={planar} resetKey={resetKey} controls={controls} active={active} />
- {(adaptiveLabels || model.view === 'hotspots') && <HotspotLabels model={model} priorityId={selectedId ?? hoveredId} onVisible={setVisibleHotspotLabels} />}
+ <SceneLabels model={model} priorityId={selectedId ?? hoveredId} cull={adaptiveLabels || model.view === 'hotspots'} onVisible={setVisibleHotspotLabels} onFolders={setFolderSpotsShown} />
</Canvas>
<div className="architecture-scene-guide" aria-hidden="true"><span>{planar ? 'PLAN' : '3D MAP'}</span>{planar ? 'Drag to pan · Scroll to zoom' : 'Drag to orbit · Right-drag to pan · Scroll to zoom'}</div>
</div>;
diff --git a/graph-ui/src/architecture/SpatialArchitecture.test.tsx b/graph-ui/src/architecture/SpatialArchitecture.test.tsx
index 73e758271..aaf18b215 100644
--- a/graph-ui/src/architecture/SpatialArchitecture.test.tsx
+++ b/graph-ui/src/architecture/SpatialArchitecture.test.tsx
@@ -47,6 +47,19 @@ it('returns from a file symbol to the repository map on empty background', async
expect(host.textContent).not.toContain('Analyze selected symbol');
expect(clear).toHaveBeenCalledOnce();
});
+it('summarizes the opened area in the inspector instead of the whole repository', async () => {
+ const nested: GraphData = { nodes: [{ ...node, file_path: 'django/contrib/admin/options.py' }, { ...node, id: 2, name: 'render', qualified_name: 'sample.render', file_path: 'django/shortcuts.py' },
+ { ...node, id: 3, name: 'setup', qualified_name: 'sample.setup', file_path: 'setup.py' }], edges: [], total_nodes: 3 };
+ await act(async () => root.render(<SpatialArchitecture project="sample" graph={nested} overview={overview} view="overview" filter="" active onNavigate={vi.fn()} onView={vi.fn()} />));
+ const inspector = () => host.querySelector('[aria-label="Architecture inspector"]');
+ expect(inspector()?.querySelector('h3')?.textContent).toBe('3 files');
+ await click('django'); await click('Open area →');
+ // Nothing is selected inside the opened area: the column speaks about django (2 of the 3 files), not the repository.
+ expect(inspector()?.querySelector('.spatial-eyebrow')?.textContent).toBe('Opened area');
+ expect(inspector()?.querySelector('h3')?.textContent).toBe('django');
+ expect(inspector()?.textContent).toContain('2 files');
+ expect(inspector()?.textContent).not.toContain('3 files');
+});
it('opens nested areas level by level and walks back through the location trail', async () => {
const nested: GraphData = { nodes: [{ ...node, file_path: 'django/contrib/admin/options.py' }, { ...node, id: 2, name: 'render', qualified_name: 'sample.render', file_path: 'django/shortcuts.py' }], edges: [], total_nodes: 2 };
await act(async () => root.render(<SpatialArchitecture project="sample" graph={nested} overview={overview} view="overview" filter="" active onNavigate={vi.fn()} onView={vi.fn()} />));
diff --git a/graph-ui/src/architecture/SpatialArchitecture.tsx b/graph-ui/src/architecture/SpatialArchitecture.tsx
index 9eb1694b4..4319c9093 100644
--- a/graph-ui/src/architecture/SpatialArchitecture.tsx
+++ b/graph-ui/src/architecture/SpatialArchitecture.tsx
@@ -97,6 +97,10 @@ export default function SpatialArchitecture({ project, generation, graph, overvi
const selectedNode = selection?.scope === scope ? model.nodes.find(node => node.id === selection.node) : undefined;
const selectedEdge = selection?.scope === scope ? model.edges.find(edge => edge.id === selection.edge) : undefined;
const selectedMeasure = selectedNode ? measureSourceNode(selectedNode, catalog) : undefined;
+ // Inside an opened area or file the inspector speaks about that scope, not the repository.
+ const openedScope = (view === 'overview' || view === 'dependencies') && (filePath || areaPath) ? filePath
+ ? { eyebrow: text.openedFile, title: filePath.split('/').at(-1) ?? filePath, path: filePath, measure: measureSourceNode({ id: `file:${filePath}`, kind: 'file', label: filePath, detail: '', position: [0, 0, 0], count: 0, members: [], filePath }, catalog) }
+ : { eyebrow: text.openedArea, title: areaPath!, path: areaPath!, measure: catalog.areas.get(areaPath!) } : undefined;
const selectedHotspots = selectedNode ? hotspotsForNode(selectedNode, hotspotCatalog) : undefined;
const nodesById = useMemo(() => new Map(model.nodes.map(node => [node.id, node])), [model.nodes]);
const edges = selectedNode ? model.edges.filter(edge => edge.source === selectedNode.id || edge.target === selectedNode.id) : model.edges;
@@ -189,6 +193,9 @@ export default function SpatialArchitecture({ project, generation, graph, overvi
{!!selectedNode.members.length && <details className="spatial-selection-details"><summary>Source members · {selectedNode.members.length}</summary><div className="spatial-members">{selectedNode.members.slice(0, memberLimit).map(node => <button key={`${node.qualified_name}:${node.id}`} onClick={() => inspectMember(node)}>{node.name}<small>{node.file_path}{node.start_line ? `:${node.start_line}` : ''}</small></button>)}</div>
{selectedNode.members.length > memberLimit && <button onClick={() => setMemberLimit(value => value + 16)}>More members</button>}</details>}
{selectedNode.graphNode && selectionPanel}
+ </> : openedScope ? <><span className="spatial-eyebrow">{openedScope.eyebrow}</span><h3 title={openedScope.path}>{openedScope.title}</h3>
+ {openedScope.measure && <details className="spatial-selection-details"><summary>{text.scopeMeasure(openedScope.measure.files, openedScope.measure.lines)}</summary><SourceMetricsDetails measure={openedScope.measure} catalog={catalog} /></details>}
+ <p>{text.openedScopeHint}</p>
</> : <><span className="spatial-eyebrow">{view === 'hotspots' ? 'Review areas' : 'Repository'}</span><h3>{view === 'hotspots' ? `${hotspotCatalog.findings.length} hotspot findings` : `${catalog.files.size.toLocaleString()} files`}</h3>
{view === 'hotspots' ? <><p>Grouped by source area. Outside dependents are distinct files with direct incoming relationships in the loaded graph.</p><div className="spatial-area-summary" aria-label="Hotspots by source area">{areas.slice(0, 5).map(area => <button key={area.path} aria-pressed={hotspotArea === area.path} onClick={() => { setHotspotArea(area.path); setSelection(undefined); setResetKey(value => value + 1); }}><strong>{area.path}</strong><small>{area.findings} findings · {area.files} files</small><small>{area.dependentFiles} outside dependent files</small></button>)}</div>{areas.length > 5 && <details className="spatial-selection-details"><summary>{areas.length - 5} more areas</summary><div className="spatial-area-summary">{areas.slice(5).map(area => <button key={area.path} onClick={() => { setHotspotArea(area.path); setSelection(undefined); setResetKey(value => value + 1); }}><strong>{area.path}</strong><small>{area.findings} findings · {area.dependentFiles} outside dependent files</small></button>)}</div></details>}</>
: <p>Select a part or connection to inspect it. Open an area to explore its files.</p>}
diff --git a/graph-ui/src/architecture/SystemArchitectureScene.tsx b/graph-ui/src/architecture/SystemArchitectureScene.tsx
index a61adcacb..e0860e346 100644
--- a/graph-ui/src/architecture/SystemArchitectureScene.tsx
+++ b/graph-ui/src/architecture/SystemArchitectureScene.tsx
@@ -1,13 +1,14 @@
-import { Component, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { Component, useEffect, useLayoutEffect, useMemo, useRef, useState, type CSSProperties, type ReactNode } from 'react';
import { Canvas, useFrame, useThree } from '@react-three/fiber';
import { Edges, Html, Line, OrbitControls, OrthographicCamera } from '@react-three/drei';
import { Box3, Color, MOUSE, TOUCH, OrthographicCamera as ThreeOrthographicCamera, QuadraticBezierCurve3, Vector3 } from 'three';
-import type { SystemSceneEdge, SystemSceneLane, SystemSceneModel, SystemSceneNode } from './system-architecture-model';
+import { laneRepeatsMember, type SystemSceneEdge, type SystemSceneLane, type SystemSceneModel, type SystemSceneNode } from './system-architecture-model';
import { edgeColor, isDirectedEdge, normalizeEdgeType } from '../graph/edge-style';
import { EdgePulseLayer } from '../graph/EdgePulseLayer';
import { useGraphBackgroundReset } from '../graph/useGraphBackgroundReset';
import { connectionLoad, type ConnectionLoad } from '../graph/connection-load';
import { SCENE_MAX_TILT, SCENE_PALETTE } from './scene-palette';
+import { placeSecondaryLabels, type LabelRect, type SecondaryLabel } from './label-space';
/** The model keeps its stable XY layout; rendering places that footprint on XZ. */
const groundPosition = ([x, y, z]: [number, number, number]): Vector3 => new Vector3(x, z, -y);
@@ -77,7 +78,7 @@ function ScopeCamera({ model, resetKey, planar, presentation }: { model: SystemS
return null;
}
-/** Folder backplates are visual containment, never selectable nodes or relationships. */
+/** Folder backplates are visual containment, never selectable nodes or relationships; NodeLabels names them. */
function FolderBackplate({ lane }: { lane: SystemSceneLane }) {
const height = lane.height ?? 24;
return <group position={groundPosition(lane.position)}>
@@ -86,12 +87,17 @@ function FolderBackplate({ lane }: { lane: SystemSceneLane }) {
<meshStandardMaterial color={SCENE_PALETTE.plate} roughness={0.95} transparent opacity={0.09} depthWrite={false} />
<Edges color={SCENE_PALETTE.plateEdge} transparent opacity={0.24} />
</mesh>
- <Html position={[-lane.width / 2 + 3, lane.depth / 2 + 0.2, -height / 2 + 3]} zIndexRange={[5, 1]} style={{ pointerEvents: 'none' }}>
- <span className="system-scene-lane-label" data-folder-id={lane.id} title={lane.label}>{lane.label}</span>
- </Html>
</group>;
}
+/** The corners a lane name may take, the far left first (where it always sat). */
+function laneSpots(lane: SystemSceneLane): { point: [number, number, number]; align: 'start' | 'end' }[] {
+ const height = lane.height ?? 24, base = groundPosition(lane.position), top = lane.depth / 2 + 0.2;
+ const x = lane.width / 2 - 3, far = -height / 2 + 3, near = height / 2 - 6;
+ return ([[-x, far, 'start'], [-x, near, 'start'], [x, far, 'end'], [x, near, 'end']] as const)
+ .map(([dx, dz, align]) => ({ point: base.clone().add(new Vector3(dx, top, dz)).toArray() as [number, number, number], align }));
+}
+
/** Source-to-target geometry is shared by the base edge and the GPU pulse batch. */
function connectionGeometry(source: SystemSceneNode, target: SystemSceneNode, offset: number) {
const start = center(source), end = center(target), sourceSize = dimensions(source);
@@ -139,14 +145,23 @@ const labelPosition = (node: SystemSceneNode): [number, number, number] => {
return [point.x, point.y + size[1] / 2 + (node.parentId ? 2.6 : 4), point.z - (node.expanded ? size[2] / 2 + 2 : 0)];
};
-/** Corridor labels take priority; neither hovering nor ordinary selection changes membership. */
+/**
+ * Corridor labels take priority; neither hovering nor ordinary selection changes membership.
+ * Lane names come last and take a free corner of their lane, or wait hidden; a
+ * lane that only repeats its one visible group name gives way to that chip.
+ */
function NodeLabels({ model, selectedNode, highlightedPathIndex, onSelect, onExpand, loads, presentation }: {
model: SystemSceneModel; selectedNode?: string; highlightedPathIndex?: number;
onSelect: (id: string) => void; onExpand?: (id: string) => void;
loads?: Map<string, ConnectionLoad>; presentation?: 'system' | 'journey';
}) {
- const { camera, size, gl } = useThree(), previous = useRef('');
+ const { camera, size, gl, events } = useThree(), previous = useRef(''), previousLanes = useRef('');
+ // Html labels mount where drei puts them: the event source, else the canvas parent.
+ const labelHost = (events.connected as HTMLElement | undefined) ?? gl.domElement.parentElement;
const [visible, setVisible] = useState<Set<string>>(new Set());
+ const [laneSpot, setLaneSpot] = useState<Map<string, number>>(new Map());
+ const laneBoxes = useRef(new Map<string, { width: number; height: number }>());
+ useEffect(() => { laneBoxes.current.clear(); }, [model.lanes]);
const [captionHeight, setCaptionHeight] = useState(36);
const ordered = useMemo(() => [...model.nodes].sort((a, b) => (model.highlightActive
? Number(Boolean(activeNode(model, b, highlightedPathIndex))) - Number(Boolean(activeNode(model, a, highlightedPathIndex))) : 0)
@@ -160,13 +175,16 @@ function NodeLabels({ model, selectedNode, highlightedPathIndex, onSelect, onExp
return () => observer.disconnect();
}, [gl]);
useFrame(() => {
- const boxes: { left: number; right: number; top: number; bottom: number }[] = [], ids: string[] = [];
+ const boxes: LabelRect[] = [], ids: string[] = [];
const zoom = 'zoom' in camera ? Number(camera.zoom) : 1;
+ const screen = (point: [number, number, number]) => {
+ const projected = new Vector3(...point).project(camera);
+ return { x: (projected.x + 1) * size.width / 2, y: (1 - projected.y) * size.height / 2, z: projected.z };
+ };
for (const node of ordered) {
if (node.parentId && zoom < 5) continue;
- const projected = new Vector3(...labelPosition(node)).project(camera);
- if (projected.z < -1 || projected.z > 1) continue;
- const x = (projected.x + 1) * size.width / 2, y = (1 - projected.y) * size.height / 2;
+ const { x, y, z } = screen(labelPosition(node));
+ if (z < -1 || z > 1) continue;
const compact = node.kind === 'group' && !node.expanded;
const width = presentation === 'journey' ? 116 : compact ? 76 : node.parentId ? 110 : node.expanded ? 126 : 96, height = presentation === 'journey' ? 58 : compact ? 24 : 28;
const box = { left: x - width / 2, right: x + width / 2, top: y - height / 2, bottom: y + height / 2 };
@@ -176,8 +194,30 @@ function NodeLabels({ model, selectedNode, highlightedPathIndex, onSelect, onExp
}
const key = ids.join('|');
if (key !== previous.current) { previous.current = key; setVisible(new Set(ids)); }
+ const shown = new Set(ids);
+ const names: SecondaryLabel[] = [], given: string[] = [];
+ for (const lane of [...(model.lanes ?? [])].sort((a, b) => b.width * (b.height ?? 24) - a.width * (a.height ?? 24) || a.id.localeCompare(b.id))) {
+ if (laneRepeatsMember(lane, model.nodes) && lane.memberIds!.some(id => shown.has(id))) { given.push(lane.id); continue; }
+ const measured = laneBoxes.current.get(lane.id) ?? (() => {
+ const element = [...labelHost?.querySelectorAll<HTMLElement>('.system-scene-lane-label[data-folder-id]') ?? []].find(item => item.dataset.folderId === lane.id);
+ const box = element?.offsetWidth ? { width: element.offsetWidth, height: element.offsetHeight } : undefined;
+ if (box) laneBoxes.current.set(lane.id, box);
+ return box;
+ })();
+ names.push({ id: lane.id, width: measured?.width ?? Math.min(180, lane.label.length * 6 + 14), height: measured?.height ?? 20,
+ spots: laneSpots(lane).map(({ point, align }) => ({ ...screen(point), align })) });
+ }
+ const spots = placeSecondaryLabels(names, boxes, size.width, size.height - captionHeight);
+ for (const id of given) spots.set(id, -1);
+ const laneKey = [...spots].map(([id, spot]) => `${id}:${spot}`).sort().join('|');
+ if (laneKey !== previousLanes.current) { previousLanes.current = laneKey; setLaneSpot(spots); }
});
- return <>{ordered.filter(node => visible.has(node.id)).map(node => <Html key={node.id}
+ return <>{(model.lanes ?? []).map(lane => {
+ const spot = laneSpot.get(lane.id) ?? 0, place = laneSpots(lane)[Math.max(0, spot)]!;
+ return <Html key={`lane:${lane.id}`} position={place.point} zIndexRange={[5, 1]} style={{ pointerEvents: 'none' }}>
+ <span className={`system-scene-lane-label${spot < 0 ? ' is-hidden' : ''}`} data-folder-id={lane.id} data-align={place.align} title={lane.label}>{lane.label}</span>
+ </Html>;
+ })}{ordered.filter(node => visible.has(node.id)).map(node => <Html key={node.id}
position={labelPosition(node)} center zIndexRange={[10, 6]}>
<button className="system-scene-node-label" data-presentation={presentation} data-kind={node.kind} data-expanded={node.expanded} data-child={Boolean(node.parentId)}
data-selected={selectedNode === node.id} data-focus={model.focusId === node.id}
diff --git a/graph-ui/src/architecture/architecture-scene.css b/graph-ui/src/architecture/architecture-scene.css
index 236354c61..d7676d7e9 100644
--- a/graph-ui/src/architecture/architecture-scene.css
+++ b/graph-ui/src/architecture/architecture-scene.css
@@ -12,6 +12,9 @@
.architecture-scene canvas { display: block; outline: none; touch-action: none; }
.architecture-scene button { font-family: inherit; }
.architecture-folder-label { display: block; max-width: 150px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--arch-folder-label); font: 10px/1.4 var(--atlas-mono, monospace); letter-spacing: 0.02em; text-shadow: 0 1px 5px var(--arch-background); }
+/* A name on a right-hand corner ends at it; a name without a free corner waits hidden (SceneLabels). */
+.architecture-folder-label[data-align="end"] { transform: translateX(-100%); }
+.architecture-folder-label.is-hidden { visibility: hidden; }
.architecture-node-label {
display: flex;
diff --git a/graph-ui/src/architecture/behavior-journey-model.ts b/graph-ui/src/architecture/behavior-journey-model.ts
index f3fc79532..500ec1bb6 100644
--- a/graph-ui/src/architecture/behavior-journey-model.ts
+++ b/graph-ui/src/architecture/behavior-journey-model.ts
@@ -42,7 +42,7 @@ function laneLayout(data: SystemProjection, nodes: SystemSceneNode[]): SystemSce
const left = Math.min(...xs), right = Math.max(...xs), bottom = Math.min(...ys), top = Math.max(...ys);
return { id: `journey-component:${id}`, label: labels.get(id) ?? id,
position: [(left + right) / 2, (bottom + top) / 2, -2] as [number, number, number],
- width: right - left + 62, height: top - bottom + 32, depth: 0.4 };
+ width: right - left + 62, height: top - bottom + 32, depth: 0.4, memberIds: members.map(node => node.id) };
});
}
diff --git a/graph-ui/src/architecture/label-space.test.ts b/graph-ui/src/architecture/label-space.test.ts
index 517149b86..975569c40 100644
--- a/graph-ui/src/architecture/label-space.test.ts
+++ b/graph-ui/src/architecture/label-space.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { labelEdges, labelInset, labelRect, labelsCollide, type LabelBox } from './label-space';
+import { labelEdges, labelInset, labelRect, labelsCollide, placeSecondaryLabels, spotRect, type LabelBox } from './label-space';
// The compact Overview and Endpoints label: padding 5px 7px and a 1px border (spatial-architecture.css).
const compact: LabelBox = { width: 100, height: 24, edgeX: 8, edgeY: 6 };
@@ -28,4 +28,19 @@ describe('label space', () => {
expect(labelInset([])).toEqual([0, 0]);
expect(labelRect(100, 50, 80, 38, [-5, 0])).toEqual({ left: 55, right: 145, top: 31, bottom: 69 });
});
+ it('moves a folder or lane name to the next free corner instead of under a chip, and hides it only when no corner is free', () => {
+ // "Outsi ◉ (root)": the lane name at its first corner runs into the (root) chip.
+ const chip = labelRect(160, 108, 70, 24, [0, 0]);
+ const outside = { id: 'hierarchy:outside', width: 44, height: 14, spots: [{ x: 120, y: 100, align: 'start' as const }, { x: 120, y: 30, align: 'start' as const }] };
+ expect(placeSecondaryLabels([outside], [chip], 400, 300)).toEqual(new Map([['hierarchy:outside', 1]]));
+ expect(labelsCollide(spotRect(outside.spots[1]!, 44, 14), chip)).toBe(false);
+ // Two names that want the same corner: the first keeps it, the second takes its other corner.
+ const a = { id: 'a', width: 40, height: 14, spots: [{ x: 10, y: 10, align: 'start' as const }] };
+ const b = { id: 'b', width: 40, height: 14, spots: [{ x: 20, y: 12, align: 'start' as const }, { x: 200, y: 12, align: 'end' as const }] };
+ expect(placeSecondaryLabels([a, b], [], 400, 300)).toEqual(new Map([['a', 0], ['b', 1]]));
+ expect(spotRect(b.spots[1]!, 40, 14)).toMatchObject({ left: 160, right: 200 });
+ // Covered everywhere or outside the canvas: hidden, never stacked.
+ const covered = { id: 'c', width: 40, height: 14, spots: [{ x: 10, y: 10, align: 'start' as const }, { x: 390, y: 10, align: 'start' as const }] };
+ expect(placeSecondaryLabels([covered], [labelRect(30, 17, 60, 20, [0, 0])], 400, 300).get('c')).toBe(-1);
+ });
});
diff --git a/graph-ui/src/architecture/label-space.ts b/graph-ui/src/architecture/label-space.ts
index c55213909..742188dc0 100644
--- a/graph-ui/src/architecture/label-space.ts
+++ b/graph-ui/src/architecture/label-space.ts
@@ -28,3 +28,35 @@ export function labelRect(x: number, y: number, width: number, height: number, [
export const labelsCollide = (a: LabelRect, b: LabelRect): boolean =>
a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
+
+/** Where a folder or lane name may sit: its top-left ('start') or top-right ('end') corner on the point. */
+export interface LabelSpot { x: number; y: number; align: 'start' | 'end' }
+export interface SecondaryLabel { id: string; width: number; height: number; spots: readonly LabelSpot[] }
+
+export function spotRect(spot: LabelSpot, width: number, height: number): LabelRect {
+ const left = spot.align === 'start' ? spot.x : spot.x - width;
+ return { left, right: left + width, top: spot.y, bottom: spot.y + height };
+}
+
+/**
+ * Folder and lane names come after the chips. Each takes the first of its
+ * spots that stays inside the canvas and touches no label placed before it
+ * (with a small margin), or stays hidden: a name under a chip reads as
+ * "Outsi ◉ (root)", two names on one corner as "djdbmodels". Returns the
+ * chosen spot per label, -1 for hidden.
+ */
+export function placeSecondaryLabels(labels: readonly SecondaryLabel[], occupied: readonly LabelRect[], width: number, height: number, margin = 3): Map<string, number> {
+ const taken = [...occupied];
+ const result = new Map<string, number>();
+ for (const label of labels) {
+ const chosen = label.spots.findIndex(spot => {
+ const rect = spotRect(spot, label.width, label.height);
+ const padded = { left: rect.left - margin, right: rect.right + margin, top: rect.top - margin, bottom: rect.bottom + margin };
+ return rect.left >= 0 && rect.top >= 0 && rect.right <= width && rect.bottom <= height && !taken.some(other => labelsCollide(padded, other));
+ });
+ result.set(label.id, chosen);
+ if (chosen >= 0) taken.push(spotRect(label.spots[chosen]!, label.width, label.height));
+ }
+ return result;
+}
+
diff --git a/graph-ui/src/architecture/strings.ts b/graph-ui/src/architecture/strings.ts
index ce77bdc3c..94f210c9e 100644
--- a/graph-ui/src/architecture/strings.ts
+++ b/graph-ui/src/architecture/strings.ts
@@ -88,4 +88,8 @@ export const architectureText = {
compareFailed: 'Could not read that project. Its index may be unavailable.',
},
showEndpoints: 'Show endpoints →',
+ openedArea: 'Opened area',
+ openedFile: 'Opened file',
+ scopeMeasure: (files: number, lines?: number) => `${files.toLocaleString()} files · ${lines === undefined ? 'unknown' : lines.toLocaleString()} indexed lines`,
+ openedScopeHint: 'Select a part or connection to inspect it. The location above leads back to the repository.',
};
diff --git a/graph-ui/src/architecture/system-architecture-model.test.ts b/graph-ui/src/architecture/system-architecture-model.test.ts
index d7df53b06..63c41f9e4 100644
--- a/graph-ui/src/architecture/system-architecture-model.test.ts
+++ b/graph-ui/src/architecture/system-architecture-model.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { isContiguousPath, projectionLimits, projectionUnavailable, rankSystemPaths, systemBehaviorGraph, systemComponentGraph, systemOverviewGraph, systemBehaviorOverviewGraph } from './system-architecture-model';
+import { isContiguousPath, laneRepeatsMember, projectionLimits, projectionUnavailable, rankSystemPaths, systemBehaviorGraph, systemComponentGraph, systemOverviewGraph, systemBehaviorOverviewGraph } from './system-architecture-model';
import type { SystemComponent, SystemDependency, SystemPath, SystemProjection, SystemSymbol } from './system-architecture-source';
const symbol = (id: number, component = 'app'): SystemSymbol => ({ id, name: `f${id}`, qualified_name: `app.f${id}`, label: 'Function', component_id: component, file_path: `src/${component}.ts`, start_line: id });
@@ -62,6 +62,20 @@ describe('persistent system overview', () => {
for (const node of base.nodes) expect(renamed.nodes.find(item => item.label === node.label)?.position).toEqual(node.position);
expect(new Set(base.nodes.map(node => node.position.join(','))).size).toBe(4);
});
+ it('names a group once: a directory lane that only repeats its single group name gives way to the chip', () => {
+ // Django: the lanes "django", "js_tests" and "Repository root" each hold one group of the same name.
+ const data = overviewProjection(['g-django', 'g-js', 'g-root', 'g-a', 'g-b'], []);
+ data.overview!.groups.forEach((group, index) => { group.label = ['django', 'js_tests', '(root)', 'src/a', 'src/b'][index]; });
+ const model = systemOverviewGraph(data);
+ const lane = (label: string) => model.lanes.find(item => item.label === label)!;
+ expect(lane('django').memberIds).toEqual(['g-django']);
+ expect(laneRepeatsMember(lane('django'), model.nodes)).toBe(true);
+ expect(laneRepeatsMember(lane('js_tests'), model.nodes)).toBe(true);
+ expect(laneRepeatsMember(lane('Repository root'), model.nodes)).toBe(true);
+ // A lane that holds several groups, or names a different one, keeps its own name.
+ expect(lane('src').memberIds).toEqual(['g-a', 'g-b']);
+ expect(laneRepeatsMember(lane('src'), model.nodes)).toBe(false);
+ });
it('uses common source directories as layout hints when no aggregate directory is reported', () => {
const data = projection([{ ...component('opaque'), representatives: [
{ ...symbol(1), file_path: 'client/api/start.ts' }, { ...symbol(2), file_path: 'client/api/end.ts' },
diff --git a/graph-ui/src/architecture/system-architecture-model.ts b/graph-ui/src/architecture/system-architecture-model.ts
index c4347ba56..0683769a2 100644
--- a/graph-ui/src/architecture/system-architecture-model.ts
+++ b/graph-ui/src/architecture/system-architecture-model.ts
@@ -19,6 +19,8 @@ export interface SystemSceneEdge {
export interface SystemSceneLane {
id: string; label: string; position: [number, number, number]; width: number; depth: number;
height?: number; pathIndices?: number[];
+ /** The scene nodes laid out on this lane. */
+ memberIds?: string[];
}
export interface SystemSceneModel {
nodes: SystemSceneNode[]; edges: SystemSceneEdge[]; lanes: SystemSceneLane[];
@@ -125,7 +127,8 @@ function overviewLayout(groups: readonly SystemOverviewGroup[], groupingBasis?:
if (x && x + region.width > rowWidth) { x = 0; y += rowHeight + 18; rowHeight = 0; }
region.members.forEach(({ group }, index) => positions.set(group.id, [x + 46 + index % region.columns * 76, -y - 28 - Math.floor(index / region.columns) * 34, 0]));
lanes.push({ id: `directory:${region.path}`, label: region.path === '\uffff' ? 'Location unavailable' : region.path || 'Repository root',
- position: [x + region.width / 2, -y - region.height / 2, -4], width: region.width, height: region.height, depth: .5 });
+ position: [x + region.width / 2, -y - region.height / 2, -4], width: region.width, height: region.height, depth: .5,
+ memberIds: region.members.map(({ group }) => group.id) });
width = Math.max(width, x + region.width); rowHeight = Math.max(rowHeight, region.height); x += region.width + 18;
}
const height = y + rowHeight;
@@ -240,6 +243,18 @@ export function systemBehaviorOverviewGraph(data: SystemProjection, base: System
nodes: base.nodes.map(node => ({ ...node, inCorridor: corridorNodes.has(node.id), pathIndices: [...(nodePaths.get(node.id) ?? [])] })), edges };
}
+const sameName = (name: string) => name.trim().toLowerCase().replace(/^(?:\(root\)|\.|repository root)$/, '(root)');
+
+/**
+ * A lane that holds one group of its own name ("django" on the django lane,
+ * "(root)" on the repository root) would print the name twice, one over the
+ * other. The chip names the group; the lane name gives way while it is shown.
+ */
+export function laneRepeatsMember(lane: SystemSceneLane, nodes: readonly SystemSceneNode[]): boolean {
+ const members = nodes.filter(node => lane.memberIds?.includes(node.id));
+ return members.length === 1 && sameName(members[0]!.label) === sameName(lane.label);
+}
+
/** A component cycle does not establish a contiguous symbol path through that component. */
export function isContiguousPath(path: SystemPath): boolean {
return path.nodes.length > 0 && path.entrypoint_id === path.nodes[0].id && path.edges.length === path.nodes.length - 1
@@ -395,7 +410,7 @@ export function systemBehaviorGraph(data: SystemProjection, input: SystemPath |
return { id, label: components.get(componentId)?.label ?? componentId,
position: [(left + right) / 2, (bottom + top) / 2 + 1, -3] as [number, number, number],
width: right - left + 10, height: top - bottom + 6, depth: 0.65,
- pathIndices: [...new Set(members.flatMap(node => node.pathIndices ?? []))] };
+ pathIndices: [...new Set(members.flatMap(node => node.pathIndices ?? []))], memberIds: members.map(node => node.id) };
});
return { nodes, edges, lanes, omittedNodes: allNodes.size - nodes.length, omittedEdges: allEdges.size - edges.length,
preferredPathIndex: ranked[0], scopeKey: `behavior:${nodes.map(node => node.id).join('|')}` };
diff --git a/graph-ui/src/architecture/system-architecture.css b/graph-ui/src/architecture/system-architecture.css
index 6849d8145..6f3d9f117 100644
--- a/graph-ui/src/architecture/system-architecture.css
+++ b/graph-ui/src/architecture/system-architecture.css
@@ -114,6 +114,9 @@
.system-architecture .system-scene .system-scene-node-label[data-focus=true] { border-color: color-mix(in srgb, var(--arch-label-focus) 50%, transparent); background: var(--arch-label-selected); color: var(--arch-label-text); }
.system-architecture .system-scene .system-scene-node-label[data-selected=true] { border-color: var(--arch-label-focus); color: var(--arch-selected); background: var(--arch-label-selected); }
.system-architecture .system-scene .system-scene-node-label:focus-visible { outline: 2px solid var(--arch-label-focus); outline-offset: 2px; }
+/* A lane name on a right-hand corner ends at it; one without a free corner waits hidden. */
+.system-scene-lane-label[data-align=end] { transform: translateX(-100%); }
+.system-scene-lane-label.is-hidden { visibility: hidden; }
.system-architecture .system-scene .system-scene-lane-label { display: inline-block; max-width: 180px; overflow: hidden; text-overflow: ellipsis; color: var(--arch-folder-label); background: color-mix(in srgb, var(--arch-background) 80%, transparent); font-size: 10px; }
.system-architecture .system-scene .system-scene-edge-label { background: var(--arch-edge-label); border-color: color-mix(in srgb, var(--arch-node) 25%, transparent); }