OpenNoodl/dev-docs/tasks/phase-4-canvas-visualisation-views/VIEW-003-trigger-chain-debugger/ENHANCEMENT-connection-highlighting.md

ENHANCEMENT: Connection Highlighting for Signal Flow Visualization

Status: 💡 Proposed Enhancement
Priority: MEDIUM
Effort: 2-3 days
Depends on: VIEW-003 core functionality + KNOWN-ISSUES fixes

---

Overview

Visual highlighting of connections when clicking events in the timeline to show signal flow through the node graph. This creates a "visual debugger" experience where you can see exactly which connections triggered which nodes.

User Value

Current Experience:

• Click event → Navigate to component → Node is highlighted
• User must mentally trace connections to understand flow

Enhanced Experience:

• Click event → Navigate + highlight node + highlight incoming connection + highlight outgoing connections
• Visual "breadcrumb trail" showing signal path through graph
• Immediately understand cause and effect

Visual Design

Highlighting Layers

When clicking an event in timeline:

1. Source Node (already implemented)

   • Node border highlighted
   • Node selected in canvas

2. Incoming Connection (NEW)

   • Connection line highlighted with pulse animation
   • Shows "where the signal came from"
   • Color: theme accent (e.g., blue)

3. Outgoing Connections (NEW)

   • All connections triggered by this event highlighted
   • Shows "what happened next"
   • Color: theme success (e.g., green)
   • Optional: Show in sequence if multiple

UI States

Single Step Mode (default):

• Shows one event's flow at a time
• Clear highlighting persists until next event clicked

Chain Mode (future):

• Shows entire recorded chain overlaid
• Each step in sequence with different colors
• Creates "flow animation" through graph

Technical Design

Data Requirements

Current TriggerEvent:

interface TriggerEvent {
  nodeId?: string; // ✅ Have this
  componentName: string; // ✅ Have this
  // MISSING:
  connectionId?: string; // Need for incoming connection
  triggeredConnections?: string[]; // Need for outgoing
}

Required Changes:

1. Capture connectionId in TriggerChainRecorder
2. Capture triggered connections (next events in chain)
3. Store in TriggerEvent interface

Implementation Plan

Phase 1: Data Capture (1 day)

Update TriggerEvent interface:

interface TriggerEvent {
  // ... existing fields
  connectionId?: string; // ID of connection that triggered this
  sourcePort?: string; // Output port name
  targetPort?: string; // Input port name
  nextEvents?: string[]; // IDs of events this triggered
}

Update TriggerChainRecorder:

• Capture connectionId from ViewerConnection data
• Parse source/target ports from connectionId
• Build forward links (nextEvents) during chain building

Phase 2: Connection Lookup (0.5 days)

Add connection lookup to EventStep click handler:

// Find the connection from connectionId
const connection = component.graph.connections.find(/* match */);
if (connection) {
  // Highlight it
}

Challenge: Connection ID format may not match graph model format Solution: Use port + node matching as fallback

Phase 3: Highlighting System (1 day)

Use existing HighlightManager:

// In EventStep.tsx click handler
HighlightManager.instance.highlightConnections(
  [event.connectionId], // Incoming
  {
    channel: 'trigger-chain-incoming',
    color: 'accent',
    animated: true
  }
);

HighlightManager.instance.highlightConnections(
  event.nextConnectionIds, // Outgoing
  {
    channel: 'trigger-chain-outgoing',
    color: 'success',
    animated: false
  }
);

Fallback: If HighlightManager doesn't support connections, extend it or use ViewerConnection highlighting

Phase 4: UI Controls (0.5 days)

Add toggle in panel:

• "Show connection flow" checkbox
• Enabled by default
• Persisted in user preferences

Benefits for Step-by-Step Debugger

This enhancement directly enables step-by-step debugging by:

1. Visual confirmation: User sees exactly what will execute next
2. Flow prediction: Outgoing connections show multiple paths
3. Debugging aid: Easily spot unexpected connections
4. Learning tool: New users understand signal flow visually

Edge Cases

1. Cross-component signals: Connection spans components

   • Solution: Highlight in both components, navigate as needed

2. Fan-out: One signal triggers multiple nodes

   • Solution: Highlight all outgoing connections

3. Missing data: ConnectionId not captured

   • Solution: Graceful degradation (node-only highlighting)

4. Performance: Many connections highlighted

   • Solution: Limit to 10 connections max, show "and X more"

Success Criteria

• Clicking event highlights incoming connection
• Clicking event highlights all outgoing connections
• Highlighting persists until another event clicked
• Works across simple and complex signal chains
• Performance acceptable with 50+ nodes
• Graceful fallback if connection data missing

Related Enhancements

• ENHANCEMENT-step-by-step-debugger.md: Uses this for visual feedback
• KNOWN-ISSUES.md: Connection data capture depends on event filtering fixes

Files to Modify

• packages/noodl-editor/src/editor/src/utils/triggerChain/types.ts
• packages/noodl-editor/src/editor/src/utils/triggerChain/TriggerChainRecorder.ts
• packages/noodl-editor/src/editor/src/views/panels/TriggerChainDebuggerPanel/components/EventStep.tsx
• Potentially: packages/noodl-editor/src/editor/src/services/HighlightManager.ts (if connection support needed)