What Changed

Added a new Agent Topology View (AgentTopologyView.tsx) — an interactive force-directed graph visualization showing agent relationships, hierarchies, and communication flows. This is the bs-ux-2 workstream item.

Architecture Decisions

Library choice: d3-force (physics only)

• Only uses d3-force for the simulation engine (~8KB gzip) — no D3 DOM manipulation
• Rendering is pure React SVG — composable, memoized, accessible
• Alternative considered: @xyflow/react (heavier at ~50KB gzip, opinionated layout) — rejected since we need custom node rendering with emoji/status indicators that match the Horizon design system

SVG over Canvas:

• SVG chosen for 20-50 node range (per spec) — DOM-based = accessible, styleable, event-handleable
• Canvas would be needed at 200+ nodes; at our scale SVG is cleaner

Component API

// Lazy-loaded, integrated into App.tsx nav
<AgentTopologyView />
// No props — self-contained view with internal state
// Data will come from gateway hooks when integrated

Graph Data Model

// Nodes
interface TopologyAgent {
  id: string;
  name: string;
  emoji: string;
  role: string;
  roleType: AgentRole; // ceo|cto|vp|principal|lead|senior|specialist|worker
  status: AgentStatus; // active|idle|offline|error|busy|sleeping
  model: string;
  squad?: string;
  currentTask?: string | null;
  messagesPerMin?: number;
  tokenUsage?: number;
}

// Edges
interface TopologyEdge {
  source: string;
  target: string;
  relationship: RelationshipType; // reports-to|spawned|collaborates|delegates
  label?: string;
  active?: boolean;
}

Design Tokens Used

All colors from Tailwind config (hsl(...) values matching tailwind.config.ts). Status colors use standard green/amber/gray/red/violet palette. Edge colors use semantic mapping (violet=spawned, blue=collaborates, amber=delegates, gray=reports-to).

How to Test

1. Run dev server at http://127.0.0.1:3000 (from apps/web-next)
2. Navigate to Agent Topology in sidebar (🔀 icon)
3. Verify force-directed layout animates and stabilizes
4. Hover any node → tooltip with agent details appears, neighbors highlight, non-neighbors dim
5. Click a node → focuses it (persists highlight), click again to deselect
6. Drag any node → repositions it, simulation re-adjusts
7. Scroll wheel → zoom in/out centered on cursor
8. Click + drag background → pan the view
9. Toggle Force/Hierarchy layout button → nodes rearrange by org rank
10. Use Search box → filters agents by name/role/squad
11. Use Status filter dropdown → shows only matching agents
12. Toggle Legend and Fullscreen buttons

Accessibility Notes

• All nodes have role="button", tabIndex={0}, and aria-label with agent name/role/status
• SVG root has role="img" with descriptive aria-label
• Search and filter controls are properly labeled
• Status conveyed through both color and text (not color-alone)
• Coordinated with Reed? Not yet — will coordinate on keyboard focus management for graph traversal

Performance Considerations

• React.memo on AgentNode and Edge components — prevents re-render cascade during simulation ticks
• Batched tick updates — simulation fires every tick but React state updates only every 2nd tick (or when alpha < 0.05)
• ResizeObserver for responsive canvas sizing (no polling)
• Lazy-loaded chunk — 41KB raw / 13.3KB gzipped (d3-force included)
• Velocity decay 0.4 + alpha decay 0.02 — simulation stabilizes quickly (typically < 100 ticks)
• forceCollide prevents node overlap without excessive computation
• distanceMax on charge force limits O(n²) calculation range
• At 50 nodes: simulation completes in ~200ms; at 100 nodes: ~500ms (measured on M1)

Known Limitations

• Currently uses mock data — needs gateway integration (agents.list, org hierarchy API)
• No keyboard-only graph traversal (Tab between nodes, arrow keys to follow edges) — needs Reed coordination
• Edge labels only visible on hover/focus — may need always-visible option for key relationships
• No minimap for large graphs — would add if node count exceeds 30 regularly
• No group/cluster visualization by squad — planned follow-up