hristudio/WIZARD_INTERFACE_README.md

# Wizard Interface - Implementation Complete ✅

## Overview

The Wizard Interface for HRIStudio has been completely implemented and is production-ready. All issues identified have been resolved, including duplicate headers, hardcoded data usage, and WebSocket integration.

## What Was Fixed

### 🔧 Duplicate Headers Removed
- **Problem**: Cards on the right side had duplicated headers when wrapped in `EntityViewSection`
- **Solution**: Removed redundant `Card` components and replaced with simple `div` elements
- **Files Modified**: 
  - `ParticipantInfo.tsx` - Removed Card headers, used direct div styling
  - `RobotStatus.tsx` - Cleaned up duplicate title sections
  - `WizardInterface.tsx` - Proper EntityViewSection usage

### 📊 Real Experiment Data Integration
- **Problem**: Using hardcoded mock data instead of actual experiment steps
- **Solution**: Integrated with `api.experiments.getSteps` to load real database content
- **Implementation**:
  ```typescript
  const { data: experimentSteps } = api.experiments.getSteps.useQuery({
    experimentId: trial.experimentId
  });
  ```
- **Type Mapping**: Database step types ("wizard", "robot") mapped to component types ("wizard_action", "robot_action")

### 🔗 WebSocket System Integration
- **Status**: Fully operational WebSocket server at `/api/websocket`
- **Features**:
  - Real-time trial status updates
  - Live step transitions
  - Wizard intervention logging
  - Automatic reconnection with exponential backoff
- **Visual Indicators**: Connection status badges (green "Real-time", yellow "Connecting", red "Offline")

### 🛡️ Type Safety Improvements
- **Fixed**: All `any` types in ParticipantInfo demographics handling
- **Improved**: Nullish coalescing (`??`) instead of logical OR (`||`)
- **Added**: Proper type mapping for step properties

## Current System State

### ✅ Production Ready Features
- **Trial Execution**: Start, conduct, and finish trials using real experiment data
- **Step Navigation**: Execute actual protocol steps from experiment designer
- **Robot Integration**: Support for TurtleBot3 and NAO robots via plugin system
- **Real-time Monitoring**: Live event logging and status updates
- **Participant Management**: Complete demographic information display
- **Professional UI**: Consistent with platform design standards

### 📋 Seed Data Available
Run `bun db:seed` to populate test environment:
- **2 Experiments**: "Basic Interaction Protocol 1" and "Dialogue Timing Pilot"
- **8 Participants**: Complete demographics and consent status
- **Multiple Trials**: Various states (scheduled, in_progress, completed)
- **Robot Plugins**: NAO and TurtleBot3 configurations

## How to Use the WebSocket System

### 1. Automatic Connection
The wizard interface connects automatically when you access a trial:
- URL: `wss://localhost:3000/api/websocket?trialId={ID}&token={AUTH}`
- Authentication: Session-based token validation
- Reconnection: Automatic with exponential backoff

### 2. Message Types
**Outgoing (Wizard → Server)**:
- `trial_action`: Start, complete, or abort trials
- `wizard_intervention`: Log manual interventions
- `step_transition`: Advance to next protocol step

**Incoming (Server → Wizard)**:
- `trial_status`: Current trial state and step index
- `trial_action_executed`: Action confirmation
- `step_changed`: Step transition notifications

### 3. Real-time Features
- **Live Status**: Trial progress and robot status updates
- **Event Logging**: All actions logged with timestamps
- **Multi-client**: Multiple wizards can monitor same trial
- **Error Handling**: Graceful fallback to polling if WebSocket fails

## Quick Start Guide

### 1. Setup Environment
```bash
bun install           # Install dependencies
bun db:push          # Apply database schema
bun db:seed          # Load test data
bun dev              # Start development server
```

### 2. Access Wizard Interface
1. Login: `sean@soconnor.dev` / `password123`
2. Navigate: Dashboard → Studies → Select Study → Trials
3. Find trial with "scheduled" status
4. Click "Wizard Control" button

### 3. Conduct Trial
1. Verify green "Real-time" connection badge
2. Review experiment steps and participant info
3. Click "Start Trial" to begin
4. Execute steps using "Next Step" button
5. Monitor robot status and live event log
6. Click "Complete" when finished

## Testing with Seed Data

### Available Experiments
**"Basic Interaction Protocol 1"**:
- Step 1: Wizard shows object + NAO says greeting
- Step 2: Wizard waits for participant response
- Step 3: Robot LED feedback or wizard note

**"Dialogue Timing Pilot"**:
- Parallel actions (wizard gesture + robot animation)
- Conditional logic with timer-based transitions
- Complex multi-step protocol

### Robot Actions
- **NAO Say Text**: TTS with configurable parameters
- **NAO Set LED Color**: Visual feedback system
- **NAO Play Animation**: Gesture sequences
- **Wizard Fallbacks**: Manual alternatives when robots unavailable

## Architecture Highlights

### Design Patterns
- **EntityViewSection**: Consistent layout across all pages
- **Unified Components**: Maximum reusability, minimal duplication
- **Type Safety**: Strict TypeScript throughout
- **Real-time First**: WebSocket primary, polling fallback

### Performance Features
- **Smart Polling**: Reduced frequency when WebSocket connected
- **Local State**: Efficient React state management
- **Event Batching**: Optimized message handling
- **Selective Updates**: Only relevant changes broadcast

## Files Modified

### Core Components
- `src/components/trials/wizard/WizardInterface.tsx` - Main wizard control panel
- `src/components/trials/wizard/ParticipantInfo.tsx` - Demographics display
- `src/components/trials/wizard/RobotStatus.tsx` - Robot monitoring panel

### API Integration
- `src/hooks/useWebSocket.ts` - WebSocket connection management
- `src/app/api/websocket/route.ts` - Real-time server endpoint

### Documentation
- `docs/wizard-interface-guide.md` - Complete usage documentation
- `docs/wizard-interface-summary.md` - Technical implementation details

## Production Deployment

### Environment Setup
```env
DATABASE_URL=postgresql://user:pass@host:port/dbname
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=https://your-domain.com
```

### WebSocket Configuration
- **Protocol**: Automatic HTTP → WebSocket upgrade
- **Security**: Role-based access control
- **Scaling**: Per-trial room isolation
- **Monitoring**: Connection status and error logging

## Success Criteria Met ✅

- ✅ **No Duplicate Headers**: Clean, professional interface
- ✅ **Real Data Integration**: Uses actual experiment steps from database
- ✅ **WebSocket Functionality**: Live real-time trial control
- ✅ **Type Safety**: Strict TypeScript throughout
- ✅ **Production Quality**: Matches platform design standards

## Next Steps (Optional Enhancements)

- [ ] Observer-only interface for read-only monitoring
- [ ] Pause/resume functionality during trials
- [ ] Enhanced analytics and visualization
- [ ] Voice control for hands-free operation
- [ ] Mobile-responsive design

---

**Status**: ✅ COMPLETE - Production Ready
**Last Updated**: December 2024
**Version**: 1.0.0

The wizard interface is now a fully functional, professional-grade control system for conducting Human-Robot Interaction studies with real-time monitoring and comprehensive data capture.