Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
TypeScript antigravity-skillsbusiness-knowledgeclaude-codeclaude-skillscodebase-analysiscodexcodex-skillsdeveloper-tools-ai-agentgemini-cli-skillskarpathy-llm-wikiknowledge-baseknowledge-graphmemoryopencode-skillspi-agentunderstandcodevibe-coding
feat(dashboard): layer-detail Stage 1 — containers + ELK
Lum11044efeccc70280
diff --git a/understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx b/understand-anything-plugin/packages/dashboard/src/components/GraphView.tsxindex 67c1d6b1..983f2307 100644--- a/understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx+++ b/understand-anything-plugin/packages/dashboard/src/components/GraphView.tsx@@ -19,32 +19,39 @@ import LayerClusterNode from "./LayerClusterNode";import type { LayerClusterFlowNode } from "./LayerClusterNode";import PortalNode from "./PortalNode";import type { PortalFlowNode } from "./PortalNode";+import ContainerNode from "./ContainerNode";+import type { ContainerFlowNode } from "./ContainerNode";import Breadcrumb from "./Breadcrumb";import { useDashboardStore } from "../store";-import type { KnowledgeGraph, NodeType } from "@understand-anything/core/types";+import type { GraphEdge, KnowledgeGraph, NodeType } from "@understand-anything/core/types";import { useTheme } from "../themes/index.ts";import {- applyDagreLayout,NODE_WIDTH,NODE_HEIGHT,LAYER_CLUSTER_WIDTH,LAYER_CLUSTER_HEIGHT,PORTAL_NODE_WIDTH,PORTAL_NODE_HEIGHT,+ ELK_DEFAULT_LAYOUT_OPTIONS,nodesToElkInput,mergeElkPositions,} from "../utils/layout";import { applyElkLayout } from "../utils/elk-layout";+import type { ElkChild, ElkEdge, ElkInput } from "../utils/elk-layout";import {+ aggregateContainerEdges,aggregateLayerEdges,computePortals,findCrossLayerFileNodes,} from "../utils/edgeAggregation";+import { deriveContainers } from "../utils/containers";+import type { DerivedContainer } from "../utils/containers";const nodeTypes = {custom: CustomNode,"layer-cluster": LayerClusterNode,portal: PortalNode,+ container: ContainerNode,};import type { NodeCategory } from "../store";@@ -249,14 +256,39 @@ function useOverviewGraph() {return overview;}-// ── Layer detail level: topology (dagre) + visual overlay ───────────────+// ── Layer detail level: topology (ELK Stage 1) + visual overlay ─────────++interface LayerDetailTopology {+ nodes: Node[];+ edges: Edge[];+ portalNodes: PortalFlowNode[];+ portalEdges: Edge[];+ filteredEdges: KnowledgeGraph["edges"];+ containers: DerivedContainer[];+ nodeToContainer: Map<string, string>;+ intraContainer: GraphEdge[];+}++const EMPTY_TOPOLOGY: LayerDetailTopology = {+ nodes: [],+ edges: [],+ portalNodes: [],+ portalEdges: [],+ filteredEdges: [],+ containers: [],+ nodeToContainer: new Map(),+ intraContainer: [],+};/**- * Topology memo: computes node positions via dagre. Only recomputes when- * the graph structure, active layer, persona, diff, or focus changes.- * Does NOT depend on selectedNodeId, searchResults, or tourHighlightedNodeIds.+ * Topology hook: derives containers, aggregates inter-container edges, then+ * runs Stage 1 ELK on container atoms (no children rendered yet — Task 12+ * lazy-expands them). Only recomputes when the graph structure, active+ * layer, persona, diff state, focus, or filters change. Does NOT depend on+ * selectedNodeId, searchResults, tourHighlightedNodeIds, or+ * expandedContainers (Stage 2 concern).*/-function useLayerDetailTopology() {+function useLayerDetailTopology(): LayerDetailTopology {const graph = useDashboardStore((s) => s.graph);const activeLayerId = useDashboardStore((s) => s.activeLayerId);const selectNode = useDashboardStore((s) => s.selectNode);@@ -275,18 +307,19 @@ function useLayerDetailTopology() {[selectNode],);- return useMemo(() => {- if (!graph || !activeLayerId)- return { nodes: [] as CustomFlowNode[], edges: [] as Edge[], portalNodes: [] as PortalFlowNode[], portalEdges: [] as Edge[], filteredEdges: [] as KnowledgeGraph["edges"] };+ // ── Structural build (synchronous): filtering + containers + nodes/edges+ // pre-layout. Re-runs whenever the inputs that drive container derivation+ // change. The only async piece is the ELK call below.+ const built = useMemo(() => {+ if (!graph || !activeLayerId) return null;const activeLayer = graph.layers.find((l) => l.id === activeLayerId);- if (!activeLayer) return { nodes: [] as CustomFlowNode[], edges: [] as Edge[], portalNodes: [] as PortalFlowNode[], portalEdges: [] as Edge[], filteredEdges: [] as KnowledgeGraph["edges"] };+ if (!activeLayer) return null;const layerNodeIds = new Set(activeLayer.nodeIds);- // Expand layer membership to include sub-file nodes (function/class) whose- // parent file is in this layer. These nodes aren't in layer.nodeIds directly- // but belong to the layer via their "contains" edge from a file node.+ // Expand layer membership to include sub-file nodes (function/class)+ // whose parent file is in this layer. Joined via "contains" edges.const expandedLayerNodeIds = new Set(layerNodeIds);for (const edge of graph.edges) {if (edge.type === "contains" && layerNodeIds.has(edge.source)) {@@ -294,8 +327,6 @@ function useLayerDetailTopology() {}}- // All node types visible at each persona level (single source of truth).- // Sub-file types (function, class) are only shown for junior/experienced.const subFileTypes = new Set(["function", "class"]);const allVisibleTypes = new Set(["file", "module", "concept",@@ -312,7 +343,6 @@ function useLayerDetailTopology() {return true;});- // Apply node type category filtersfilteredGraphNodes = filteredGraphNodes.filter((n) => {const category = NODE_TYPE_TO_CATEGORY[n.type as NodeType];if (!category) {@@ -346,70 +376,106 @@ function useLayerDetailTopology() {);}- const diffNodeIds = diffMode- ? new Set([...changedNodeIds, ...affectedNodeIds])- : new Set<string>();+ // Derive containers + bucket edges+ const { containers, ungrouped } = deriveContainers(+ filteredGraphNodes,+ filteredGraphEdges,+ );+ const ungroupedSet = new Set(ungrouped);+ const nodeToContainer = new Map<string, string>();+ for (const c of containers) {+ for (const id of c.nodeIds) nodeToContainer.set(id, c.id);+ }+ // Ungrouped nodes are their own atoms — register them so edge+ // aggregation treats inter-(container,ungrouped) edges as cross-atom.+ for (const id of ungroupedSet) {+ nodeToContainer.set(id, id);+ }+ const { intraContainer, interContainerAggregated } = aggregateContainerEdges(+ filteredGraphEdges,+ nodeToContainer,+ );- const flowNodes: CustomFlowNode[] = filteredGraphNodes.map((node) => ({- id: node.id,- type: "custom" as const,+ // Container size estimate (size memory takes priority)+ const sizeMemory = useDashboardStore.getState().containerSizeMemory;+ const containerWidth = (c: DerivedContainer) =>+ sizeMemory.get(c.id)?.width ??+ Math.max(NODE_WIDTH, Math.sqrt(c.nodeIds.length) * NODE_WIDTH * 1.2);+ const containerHeight = (c: DerivedContainer) =>+ sizeMemory.get(c.id)?.height ??+ Math.max(NODE_HEIGHT, Math.sqrt(c.nodeIds.length) * NODE_HEIGHT * 1.2);++ // Build container flow nodes (children NOT rendered yet — Task 12)+ const containerFlowNodes: ContainerFlowNode[] = containers.map((c, idx) => ({+ id: c.id,+ type: "container" as const,position: { x: 0, y: 0 },+ width: containerWidth(c),+ height: containerHeight(c),data: {- label: node.name ?? node.filePath?.split("/").pop() ?? node.id,- nodeType: node.type,- summary: node.summary,- complexity: node.complexity,- isHighlighted: false,- searchScore: undefined,- isSelected: false,- isTourHighlighted: false,- isDiffChanged: diffMode && changedNodeIds.has(node.id),- isDiffAffected: diffMode && affectedNodeIds.has(node.id),- isDiffFaded: diffMode && !changedNodeIds.has(node.id) && !affectedNodeIds.has(node.id),- isNeighbor: false,- isSelectionFaded: false,- onNodeClick: handleNodeSelect,+ containerId: c.id,+ name: c.name,+ childCount: c.nodeIds.length,+ strategy: c.strategy,+ colorIndex: idx % 12,+ isExpanded: false,+ hasSearchHits: false,+ isDiffAffected: false, // Task 14 will populate this+ isFocusedViaChild: false,+ onToggle: (id: string) => useDashboardStore.getState().toggleContainer(id),},}));- const flowEdges: Edge[] = filteredGraphEdges.map((edge, i) => {- const sourceInDiff = diffMode && diffNodeIds.has(edge.source);- const targetInDiff = diffMode && diffNodeIds.has(edge.target);- const isImpacted = diffMode && (sourceInDiff || targetInDiff);-- let edgeStyle: React.CSSProperties;- let edgeLabelStyle: React.CSSProperties;- let edgeAnimated: boolean;-- if (isImpacted) {- edgeStyle = {- stroke: sourceInDiff && targetInDiff ? "rgba(224, 82, 82, 0.7)" : "rgba(212, 160, 48, 0.5)",- strokeWidth: 2.5,- };- edgeLabelStyle = { fill: "#a39787", fontSize: 10 };- edgeAnimated = true;- } else if (diffMode) {- edgeStyle = { stroke: "rgba(212,165,116,0.08)", strokeWidth: 1 };- edgeLabelStyle = { fill: "rgba(163,151,135,0.3)", fontSize: 10 };- edgeAnimated = false;- } else {- edgeStyle = { stroke: "rgba(212,165,116,0.3)", strokeWidth: 1.5 };- edgeLabelStyle = { fill: "#a39787", fontSize: 10 };- edgeAnimated = edge.type === "calls";- }-+ // Build ungrouped file flow nodes (existing CustomFlowNode shape)+ const ungroupedFlowNodes: CustomFlowNode[] = filteredGraphNodes+ .filter((n) => ungroupedSet.has(n.id))+ .map((node) => ({+ id: node.id,+ type: "custom" as const,+ position: { x: 0, y: 0 },+ data: {+ label: node.name ?? node.filePath?.split("/").pop() ?? node.id,+ nodeType: node.type,+ summary: node.summary,+ complexity: node.complexity,+ isHighlighted: false,+ searchScore: undefined,+ isSelected: false,+ isTourHighlighted: false,+ isDiffChanged: diffMode && changedNodeIds.has(node.id),+ isDiffAffected: diffMode && affectedNodeIds.has(node.id),+ isDiffFaded: diffMode && !changedNodeIds.has(node.id) && !affectedNodeIds.has(node.id),+ isNeighbor: false,+ isSelectionFaded: false,+ onNodeClick: handleNodeSelect,+ },+ }));++ // Aggregated cross-atom edges (count label, log-scaled stroke).+ // diffMode dims unaffected aggregated edges (no per-edge diff data — we+ // can't tell which underlying edges are impacted without expanding a+ // container, so just fade everything in diff mode at this stage).+ const aggEdges: Edge[] = interContainerAggregated.map((agg, i) => {+ const baseStyle = diffMode+ ? { stroke: "rgba(212,165,116,0.08)", strokeWidth: 1 }+ : {+ stroke: "rgba(212,165,116,0.4)",+ strokeWidth: Math.min(1 + Math.log2(agg.count + 1), 5),+ };return {- id: `e-${i}`,- source: edge.source,- target: edge.target,- label: edge.type,- animated: edgeAnimated,- style: edgeStyle,- labelStyle: edgeLabelStyle,+ id: `agg-${i}`,+ source: agg.sourceContainerId,+ target: agg.targetContainerId,+ label: String(agg.count),+ style: baseStyle,+ labelStyle: {+ fill: diffMode ? "rgba(163,151,135,0.3)" : "#a39787",+ fontSize: 11,+ },};});- // Portal nodes for connected external layers+ // Portal nodes for connected external layers (unchanged)const portals = computePortals(graph, activeLayerId);const layerIndexMap = new Map(graph.layers.map((l, i) => [l.id, i]));@@ -427,39 +493,149 @@ function useLayerDetailTopology() {}));const portalEdges: Edge[] = [];- let portalEdgeIdx = flowEdges.length;+ let portalEdgeIdx = aggEdges.length;for (const portal of portals) {const crossFiles = findCrossLayerFileNodes(graph, activeLayerId, portal.layerId);+ // Dedupe by atom — multiple files in the same container hitting the+ // same portal collapse to one Stage 1 edge. Task 12 will re-route to+ // the actual file ids when the source container expands.+ const seenAtoms = new Set<string>();for (const fileId of crossFiles) {- if (filteredNodeIds.has(fileId)) {- portalEdges.push({- id: `e-${portalEdgeIdx++}`,- source: fileId,- target: `portal:${portal.layerId}`,- style: { stroke: "rgba(212,165,116,0.2)", strokeWidth: 1, strokeDasharray: "4 4" },- animated: false,- });- }+ if (!filteredNodeIds.has(fileId)) continue;+ const atomId = nodeToContainer.get(fileId) ?? fileId;+ if (seenAtoms.has(atomId)) continue;+ seenAtoms.add(atomId);+ portalEdges.push({+ id: `e-${portalEdgeIdx++}`,+ source: atomId,+ target: `portal:${portal.layerId}`,+ style: { stroke: "rgba(212,165,116,0.2)", strokeWidth: 1, strokeDasharray: "4 4" },+ animated: false,+ });}}- const allFlowNodes: Node[] = [- ...(flowNodes as unknown as Node[]),- ...(portalNodes as unknown as Node[]),- ];- const allFlowEdges = [...flowEdges, ...portalEdges];+ return {+ containers,+ ungrouped,+ nodeToContainer,+ intraContainer,+ filteredGraphEdges,+ containerFlowNodes,+ ungroupedFlowNodes,+ aggEdges,+ portalNodes,+ portalEdges,+ };+ }, [+ graph,+ activeLayerId,+ persona,+ diffMode,+ changedNodeIds,+ affectedNodeIds,+ focusNodeId,+ nodeTypeFilters,+ drillIntoLayer,+ handleNodeSelect,+ ]);++ // ── Async ELK Stage 1 layout ────────────────────────────────────────────+ const [topology, setTopology] = useState<LayerDetailTopology>(EMPTY_TOPOLOGY);- const dims = new Map<string, { width: number; height: number }>();- for (const n of flowNodes) {- dims.set(n.id, { width: NODE_WIDTH, height: NODE_HEIGHT });- }- for (const n of portalNodes) {- dims.set(n.id, { width: PORTAL_NODE_WIDTH, height: PORTAL_NODE_HEIGHT });+ useEffect(() => {+ if (!built) {+ setTopology(EMPTY_TOPOLOGY);+ return;}+ let cancelled = false;+ const {+ containers,+ nodeToContainer,+ intraContainer,+ filteredGraphEdges,+ containerFlowNodes,+ ungroupedFlowNodes,+ aggEdges,+ portalNodes,+ portalEdges,+ } = built;++ // Build Stage 1 ELK input: containers as opaque atoms + ungrouped files+ // + portals, all at the top level.+ const stage1Children: ElkChild[] = [+ ...containerFlowNodes.map((cn) => ({+ id: cn.id,+ width: cn.width ?? NODE_WIDTH,+ height: cn.height ?? NODE_HEIGHT,+ })),+ ...ungroupedFlowNodes.map((un) => ({+ id: un.id,+ width: NODE_WIDTH,+ height: NODE_HEIGHT,+ })),+ ...portalNodes.map((pn) => ({+ id: pn.id,+ width: PORTAL_NODE_WIDTH,+ height: PORTAL_NODE_HEIGHT,+ })),+ ];++ const stage1Edges: ElkEdge[] = [+ ...aggEdges.map((e) => ({+ id: e.id,+ sources: [String(e.source)],+ targets: [String(e.target)],+ })),+ ...portalEdges.map((e) => ({+ id: e.id,+ sources: [String(e.source)],+ targets: [String(e.target)],+ })),+ ];++ const elkInput: ElkInput = {+ id: "layer",+ layoutOptions: ELK_DEFAULT_LAYOUT_OPTIONS,+ children: stage1Children,+ edges: stage1Edges,+ };++ applyElkLayout(elkInput, { strict: import.meta.env.DEV })+ .then(({ positioned, issues }) => {+ if (cancelled) return;+ if (issues.length > 0) {+ // TODO: Task 16 wires these into the WarningBanner.+ console.warn("[layer-detail Stage 1 ELK] layout issues:", issues);+ }+ const allBaseNodes: Node[] = [+ ...(containerFlowNodes as unknown as Node[]),+ ...(ungroupedFlowNodes as unknown as Node[]),+ ...(portalNodes as unknown as Node[]),+ ];+ const positionedNodes = mergeElkPositions(allBaseNodes, positioned);+ setTopology({+ nodes: positionedNodes,+ edges: aggEdges,+ portalNodes,+ portalEdges,+ filteredEdges: filteredGraphEdges,+ containers,+ nodeToContainer,+ intraContainer,+ });+ })+ .catch((err) => {+ if (cancelled) return;+ console.error("[layer-detail Stage 1 ELK] layout failed:", err);+ });++ return () => {+ cancelled = true;+ };+ }, [built]);- const laid = applyDagreLayout(allFlowNodes, allFlowEdges, "TB", dims);- return { nodes: laid.nodes, edges: laid.edges, portalNodes, portalEdges, filteredEdges: filteredGraphEdges };- }, [graph, activeLayerId, persona, handleNodeSelect, diffMode, changedNodeIds, affectedNodeIds, focusNodeId, nodeTypeFilters, drillIntoLayer]);+ return topology;}/**@@ -488,8 +664,9 @@ function useLayerDetailGraph() {}return topo.nodes.map((node) => {- // Skip portal nodes — they have no CustomNodeData- if (node.type === "portal") return node;+ // Skip portal + container nodes — they have no CustomNodeData.+ // (Container visual overlays land in Task 14.)+ if (node.type === "portal" || node.type === "container") return node;const searchScore = searchMap.get(node.id);const isHighlighted = searchScore !== undefined;diff --git a/understand-anything-plugin/packages/dashboard/src/utils/layout.ts b/understand-anything-plugin/packages/dashboard/src/utils/layout.tsindex 6e408e5c..359a1a36 100644--- a/understand-anything-plugin/packages/dashboard/src/utils/layout.ts+++ b/understand-anything-plugin/packages/dashboard/src/utils/layout.ts@@ -187,7 +187,7 @@ export function applyForceLayout(// ELK helpers// ----------------------------------------------------------------------------const ELK_DEFAULT_LAYOUT_OPTIONS: Record<string, string> = {+export const ELK_DEFAULT_LAYOUT_OPTIONS: Record<string, string> = {algorithm: "layered","elk.direction": "DOWN","elk.layered.spacing.nodeNodeBetweenLayers": "80",