🚀 HandIt Interactive Tour System

An advanced interactive tour system inspired by Layup Labs for HandIt.ai - A comprehensive onboarding and user guidance platform for AI agent improvement.

📋 What is this?

This project is a complete implementation of an interactive tour system similar to Layup Labs, specifically designed for HandIt.ai (an automatic AI agent improvement platform). It includes:

• ✅ Welcome tours with fullscreen modals
• ✅ Setup wizards with interactive forms
• ✅ Contextual tooltips for user guidance
• ✅ Mock components (trace viewers, evaluators, sidebar details)
• ✅ Fully dynamic JSON configuration
• ✅ Analytics and event tracking
• ✅ Responsive design with dark theme
• ✅ Cursor animations and guided interactions
• ✅ Persistent sidebar with execution details
• ✅ 5-step numbered tour flow

🚀 How to run the project

Prerequisites

Make sure you have installed:

• Node.js (version 16 or higher)
• npm (included with Node.js)

Step 1: Install dependencies

npm install

Step 2: Run in development mode

npm start

The project will automatically open in your browser at: http://localhost:3000

Step 3: Explore the tours!

Once the application is running:

1. Welcome Tour: Automatically activated when simulating a new user
2. Setup Wizard: Available after the walkthrough
3. Evaluator Tour: Activated when simulating SDK integration
4. Optimizations: Appear when sufficient evaluations exist

🎮 Demo Features

The application includes a complete dashboard with buttons to simulate different states:

Available Simulations:

• 🔄 Simulate first login → Activates welcome tour
• ⚙️ Simulate integrated SDK → Activates evaluator wizard
• 📊 Generate evaluation data → Creates simulated metrics
• 🚀 Simulate optimization → Shows improvement notifications

Interactive Dashboard:

• 📈 Real-time metrics (simulated)
• 🔍 Traces section with mock data
• 🧠 Evaluators panel
• ⚡ Optimizations center
• 📋 Execution details sidebar with expandable sections

📁 Project Structure

quickstart/
├── public/
│   ├── index.html              # Main HTML
│   └── manifest.json           # PWA configuration
├── src/
│   ├── index.js                # React entry point
│   ├── index.css               # Global styles
│   ├── HandItApp.jsx           # Main application
│   ├── HandItApp.css           # Dashboard styles
│   └── components/
│       └── HandItTour/
│           ├── HandItTourProvider.jsx  # Context provider for tours
│           ├── TourComponents.jsx      # Tour UI components
│           ├── TourComponents.css      # Component styles
│           ├── CursorGuide.jsx         # Cursor animation system
│           ├── CursorGuide.css         # Cursor styles
│           └── handit-tour-config.json # Complete tour configuration
├── package.json                # Dependencies and scripts
└── README.md                   # This file

🎨 Implemented Tours

1. Welcome & Concept Walkthrough (5 Steps)

• Step 1: Welcome screen with tour introduction
• Step 2: Tracing exploration with table interaction
• Step 3: Sidebar execution details (System Prompt, User Prompt, Output)
• Step 4: Evaluation Suite navigation
• Step 5: Release Hub exploration

2. Wizard-Guided Setup

• Agent type selection forms
• SDK integration code with tabs
• Wait states for external events

3. Evaluator Setup Wizard

• Agent type-based recommendations
• Customizable criteria configuration
• Auto-attachment to relevant nodes

4. First Optimization Experience

• Contextual notifications
• Before/after comparisons
• Improvement metrics

🖱️ Advanced Cursor Guidance

The tour system features sophisticated cursor animations:

• Curved path animations between elements
• Click animations with visual feedback
• Glow highlights on target elements
• Smart positioning of instruction bubbles
• Auto-advance functionality with user interaction

📋 Sidebar Component

Interactive execution details sidebar featuring:

• Expandable sections for System Prompt, User Prompt, and Output
• JSON syntax highlighting for structured data
• Dark theme styling matching the interface
• Persistent functionality (works outside tour mode)
• Multiple selector strategies for robust element detection

⚙️ JSON Configuration

The entire system is controlled from src/components/HandItTour/handit-tour-config.json:

{
  "tourConfig": {
    "tours": [...],           // Tour definitions with step numbers
    "triggers": {...},        // Activation conditions  
    "dynamicContent": {...},  // Personalizable content
    "analytics": {...}        // Event tracking
  }
}

Key Configuration Features:

• Step numbering (1-5) for easy identification
• Cursor guidance with animation paths and delays
• Instruction positioning relative to targets
• Interactive elements with click/hover actions
• Multi-language support (currently English)

🔧 Customization

Change Themes:

Edit colors in handit-tour-config.json:

"theme": {
  "primaryColor": "#6366f1",
  "backgroundColor": "rgba(0, 0, 0, 0.7)"
}

Add New Tours:

1. Define the tour in tours array
2. Add trigger in triggers
3. Create steps with actions and step numbers
4. Customize dynamic content

Modify Mock Components:

Edit TourComponents.jsx to change:

• MockTraceViewer - Trace visualization
• MockEvaluationPanel - Evaluation panels
• MockSidebar - Execution details sidebar

📱 Responsive Design

• ✅ Desktop - Complete experience
• ✅ Tablet - Modal adaptations
• ✅ Mobile - Mobile-optimized tours

🎯 Integrated Analytics

The system automatically tracks:

• ▶️ Tour starts
• ✅ Step completions
• ⏭️ Tours skipped
• 🔄 Time spent on each step
• 🖱️ Action clicks
• 📊 User interaction patterns

🔗 Available Scripts

npm start          # Development (port 3000)
npm run build      # Production build  
npm test           # Run tests
npm run eject      # Expose configuration (not recommended)

🌟 Key Features

• Completely configurable via JSON
• Templating system for dynamic content
• Realistic mock components for demos
• State management with React Context
• Smart triggers based on conditions
• Smooth animations and transitions
• Accessibility (keyboard, screen readers)
• Integrated analytics for optimization
• Cursor guidance system with path animations
• Persistent sidebar with execution details
• Step-by-step numbered flow

🚀 Getting Started

npm install && npm start

The tour will automatically begin when you open the application! 🎉

🔄 Tour Flow

1. Welcome Screen → Start tour
2. Tracing Section → Click to explore traces
3. Table Interaction → Click on execution to open sidebar
4. Sidebar Exploration → Expand System/User Prompts and Output
5. Evaluation Suite → Navigate to quality checks
6. Release Hub → Explore AI optimization system

📚 Inspiration

This project is inspired by Layup Labs and specifically designed for the onboarding needs of AI platforms like HandIt.ai.

🎯 Development Notes

• Cursor animations use curved paths with configurable durations
• Instruction bubbles position dynamically near target elements
• Event listeners include cleanup to prevent memory leaks
• State management uses functional updates to avoid closure issues
• Debug functions available in browser console (window.showMockSidebar())

---

Built with React, Context API, and advanced CSS animations for HandIt.ai