hristudio/docs/core-blocks-system.md

HRIStudio Core Blocks System

Overview

The core blocks system provides essential building blocks for the visual experiment designer through a repository-based plugin architecture. This system ensures consistency, extensibility, and maintainability by treating all blocks (core functionality and robot actions) as plugins loaded from repositories.

Quick Links:

• Plugin System Implementation Guide
• Work in Progress
• Project Overview

✅ Implementation Complete

1. Core Repository Structure

Created hristudio-core/ repository with complete plugin architecture:

hristudio-core/
├── repository.json           # Repository metadata
├── plugins/
│   ├── index.json           # Plugin index (26 total blocks)
│   ├── events.json          # Event trigger blocks (4 blocks)
│   ├── wizard-actions.json  # Wizard action blocks (6 blocks)
│   ├── control-flow.json    # Control flow blocks (8 blocks)
│   └── observation.json     # Observation blocks (8 blocks)
├── assets/                  # Repository assets
└── README.md               # Complete documentation

2. Block Categories Implemented

Event Triggers (4 blocks)

• when_trial_starts - Trial initialization trigger
• when_participant_speaks - Speech detection with duration threshold
• when_timer_expires - Time-based triggers with custom delays
• when_key_pressed - Wizard keyboard shortcuts

Wizard Actions (6 blocks)

• wizard_say - Speech with tone guidance
• wizard_gesture - Physical gestures with directions
• wizard_show_object - Object presentation with action types
• wizard_record_note - Observation recording with categorization
• wizard_wait_for_response - Response waiting with timeout
• wizard_rate_interaction - Subjective rating scales

Control Flow (8 blocks)

• wait - Pause execution with optional countdown
• repeat - Loop execution with delay between iterations
• if_condition - Conditional logic with multiple condition types
• parallel - Simultaneous execution with timeout controls
• sequence - Sequential execution with error handling
• random_choice - Weighted random path selection
• try_catch - Error handling with retry mechanisms
• break - Exit controls for loops/sequences/trials

Observation & Sensing (8 blocks)

• observe_behavior - Behavioral coding with standardized scales
• measure_response_time - Stimulus-response timing measurement
• count_events - Event frequency tracking
• record_audio - Audio capture with quality settings
• capture_video - Multi-camera video recording
• log_event - Timestamped event logging
• survey_question - In-trial questionnaires
• physiological_measure - Sensor data collection

3. Technical Architecture Changes

BlockRegistry Refactoring

• Removed: All hardcoded core blocks (initializeCoreBlocks())
• Added: Async loadCoreBlocks() method with repository fetching
• Improved: Error handling, fallback system, type safety
• Enhanced: Logging and debugging capabilities

Dynamic Loading System

async loadCoreBlocks() {
  // Fetch blocks from /hristudio-core/plugins/
  // Parse and validate JSON structures
  // Convert to PluginBlockDefinition format
  // Register with BlockRegistry
  // Fallback to minimal blocks if loading fails
}

Public Serving

• Core repository copied to public/hristudio-core/
• Accessible via /hristudio-core/plugins/*.json
• Static serving ensures reliable access

4. Files Created/Modified

New Files

• hristudio-core/repository.json - Repository metadata
• hristudio-core/plugins/events.json - Event blocks (4)
• hristudio-core/plugins/wizard-actions.json - Wizard blocks (6)
• hristudio-core/plugins/control-flow.json - Control blocks (8)
• hristudio-core/plugins/observation.json - Observation blocks (8)
• hristudio-core/plugins/index.json - Plugin index
• hristudio-core/README.md - Complete documentation
• public/hristudio-core/ - Public serving copy
• scripts/test-core-blocks.ts - Validation test script

Modified Files

• src/components/experiments/designer/EnhancedBlockDesigner.tsx
  • Replaced hardcoded blocks with dynamic loading
  • Enhanced error handling and type safety
  • Improved plugin loading integration
• scripts/seed-core-blocks.ts - Fixed imports and type errors
• scripts/seed-plugins.ts - Fixed operators and imports
• scripts/seed.ts - Fixed delete operations warnings

5. Quality Assurance

Validation System

• JSON schema validation for all block definitions
• Type consistency checking (category colors, required fields)
• Parameter validation (types, constraints, options)
• Comprehensive test coverage

Test Results

✅ All tests passed! Core blocks system is working correctly.
   • 26 blocks loaded from repository
   • All required core blocks present
   • Registry loading simulation successful

TypeScript Compliance

• Fixed all unsafe any type usage
• Proper type definitions for all block structures
• Nullish coalescing operators throughout
• No compilation errors or warnings

6. Benefits Achieved

Complete Consistency

• All blocks (core + robot) now use identical plugin architecture
• Unified block management and loading patterns
• Consistent JSON schema and validation

Enhanced Extensibility

• Add new core blocks by editing JSON files (no code changes)
• Version control for core functionality
• Independent updates and rollbacks

Improved Maintainability

• Centralized block definitions
• Clear separation of concerns
• Comprehensive documentation and validation

Better Developer Experience

• Type-safe block loading
• Detailed error messages and logging
• Fallback system ensures robustness

7. Integration Points

Experiment Designer

• Automatic core blocks loading on component mount
• Seamless integration with existing plugin system
• Consistent block palette organization

Database Integration

• Core blocks can be seeded as plugins if needed
• Compatible with existing plugin management system
• Study-scoped installations possible

Future Extensibility

• Easy to create additional core repositories
• Simple to add new block categories
• Version management ready

Technical Specifications

Block Definition Schema

{
  "id": "block_identifier",
  "name": "Display Name",
  "description": "Block description",
  "category": "event|wizard|control|sensor",
  "shape": "hat|action|control|boolean|value",
  "icon": "LucideIconName",
  "color": "#hexcolor",
  "parameters": [...],
  "execution": {...}
}

Loading Process

1. Component mount triggers loadCoreBlocks()
2. Fetch each block set from /hristudio-core/plugins/
3. Validate JSON structure and block definitions
4. Convert to PluginBlockDefinition format
5. Register with BlockRegistry
6. Fallback to minimal blocks if any failures

Error Handling

• Network failures → fallback blocks
• Invalid JSON → skip block set with warning
• Invalid blocks → skip individual blocks
• Type errors → graceful degradation

Integration with HRIStudio Platform

Related Documentation

• Plugin System Implementation Guide - Robot plugin architecture
• Implementation Details - Overall platform architecture
• Database Schema - Plugin storage and management tables
• API Routes - Plugin management endpoints

Development Commands

# Test core blocks loading
bun run scripts/test-core-blocks.ts

# Validate block definitions
cd public/hristudio-core && node validate.js

# Update public repository
cp -r hristudio-core/ public/hristudio-core/

Status: Production Ready

✅ Complete: All 26 core blocks implemented and tested
✅ Validated: Comprehensive testing and type checking
✅ Documented: Integrated with existing documentation system
✅ Integrated: Seamless experiment designer integration
✅ Extensible: Ready for future enhancements

The core blocks system provides a robust, maintainable foundation for HRIStudio's experiment designer, ensuring complete architectural consistency across all platform components.