chore: commit full workspace changes (designer modularization, diagnostics fixes, docs updates, seed script cleanup)

2025-12-11 14:44:44 -05:00 · 2025-08-08 00:37:35 -04:00
parent c071d33624
commit 1ac8296ab7
37 changed files with 5378 additions and 5758 deletions
--- a/docs/experiment-designer-step-integration.md
+++ b/docs/experiment-designer-step-integration.md
@@ -0,0 +1,253 @@
+# Experiment Designer Step Integration (Modular Architecture + Drift Handling)
+
+## Overview
+
+The HRIStudio experiment designer has been redesigned with a step-based + provenance-aware architecture that provides intuitive experiment creation, transparent plugin usage, and reproducible execution through integrity hashing and a compiled execution graph.
+
+## Architecture
+
+### Core Design Philosophy
+
+The designer follows a clear hierarchy that matches database structure, runtime execution, and reproducibility tracking:
+- **Experiment** → **Steps** → **Actions** (with provenance + execution descriptors)
+- Steps are primary containers in the flow (Step 1 → Step 2 → Step 3) with sortable ordering
+- Actions are dragged from a categorized library into step containers (core vs plugin clearly labeled)
+- Direct 1:1 mapping to database `steps` and `actions` tables, persisting provenance & transport metadata
+
+### Key Components (Post-Modularization)
+
+#### ActionRegistry (`ActionRegistry.ts`)
+- Loads actions from core plugin repositories (`hristudio-core/plugins/`)
+- Integrates study-scoped robot plugins (namespaced: `pluginId.actionId`)
+- Provides fallback actions if plugin loading fails (ensures minimal operability)
+- Maps plugin parameter schemas (primitive: text/number/select/boolean) to UI fields
+- Retains provenance + execution descriptors (transport, timeout, retryable)
+
+#### Step-Based Flow (`StepFlow.tsx`)
+- Sortable step containers with drag-and-drop reordering (via `@dnd-kit`)
+- Color-coded step types (sequential, parallel, conditional, loop) with left border accent
+- Expandable/collapsible view for managing complex experiments
+- Visual connectors between steps (light vertical separators)
+- Isolated from parameter/editor logic for performance and clarity
+
+#### Action Library (`ActionLibrary.tsx`)
+- Categorized tabs: Wizard (blue), Robot (emerald), Control (amber), Observation (purple)
+- Tooltips show description, parameters, provenance badge (C core / P plugin)
+- Drag-and-drop from library directly into specific step droppable zones
+- Footer statistics (total actions / category count)
+- Empty + fallback guidance when plugin actions absent
+- Guarantees availability: once the experiment's study context and its installed plugins are loaded, all corresponding plugin actions are registered and appear (guarded against duplicate loads / stale study mismatch)
+- Plugin availability is study-scoped: only plugins installed for the experiment's parent study (via Plugin Store installation) are loaded and exposed; this ensures experiments cannot reference uninstalled or unauthorized plugin actions.
+
+#### Properties Panel (`PropertiesPanel.tsx`)
+- Context-aware: action selection → action parameters; step selection → step metadata; otherwise instructional state
+- Boolean parameters now render as accessible Switch
+- Number parameters with `min`/`max` render as Slider (shows live value + bounds)
+- Number parameters without bounds fall back to numeric input
+- Select/text unchanged; future: enum grouping + advanced editors
+- Displays provenance + transport badges (plugin id@version, transport, retryable)
+
+## User Experience
+
+### Visual Design
+- **Tightened Spacing**: Compact UI with efficient screen real estate usage
+- **Dark Mode Support**: Proper selection states and theme-aware colors
+- **Color Consistency**: Category colors used throughout for visual coherence
+- **Micro-interactions**: Hover states, drag overlays, smooth transitions
+
+### Interaction Patterns
+- **Direct Action Editing**: Click any action to immediately edit properties (no step selection required)
+- **Multi-level Sorting**: Reorder steps in flow, reorder actions within steps
+- **Visual Feedback**: Drop zones highlight, selection states clear, drag handles intuitive
+- **Touch-friendly**: Proper activation constraints for mobile/touch devices
+
+### Properties Panel (Enhanced Parameter Controls)
+- **Action-First Workflow**: Immediate property editing on action selection
+- **Rich Metadata**: Icon, category color, provenance badges (Core/Plugin, transport)
+- **Switch for Boolean**: Improves clarity vs checkbox in dense layouts
+- **Slider for Ranged Number**: Applies when `min` or `max` present (live formatted value)
+- **Graceful Fallbacks**: Plain number input if no bounds; text/select unchanged
+- **Context-Aware**: Step editing (name/type/trigger) isolated from action editing
+
+## Technical Implementation
+
+### Drag and Drop System
+Built with `@dnd-kit` for robust, accessible drag-and-drop:
+
+```typescript
+// Multi-context sorting support
+const handleDragEnd = (event: DragEndEvent) => {
+  // Action from library to step
+  if (activeId.startsWith("action-") && overId.startsWith("step-")) {
+    // Add action to step
+  }
+  
+  // Step reordering in flow
+  if (!activeId.startsWith("action-") && !overId.startsWith("step-")) {
+    // Reorder steps
+  }
+  
+  // Action reordering within step
+  if (!activeId.startsWith("action-") && !overId.startsWith("step-")) {
+    // Reorder actions in step
+  }
+};
+```
+
+### Plugin Integration (Registry-Centric)
+Actions are loaded dynamically from multiple sources with provenance & version retention:
+
+```typescript
+class ActionRegistry {
+  async loadCoreActions() {
+    // Load from hristudio-core/plugins/
+    const coreActionSets = ["wizard-actions", "control-flow", "observation"];
+    // Process and register actions
+  }
+  
+  loadPluginActions(studyId: string, studyPlugins: Array<{plugin: any}>) {
+    // Load robot-specific actions from study plugins
+    // Map parameter schemas to form controls
+  }
+}
+```
+
+### Database & Execution Conversion
+Two-layer conversion:
+1. Visual design → DB steps/actions with provenance & execution metadata
+2. Visual design → Compiled execution graph (normalized actions + transport summary + integrity hash)
+
+```typescript
+function convertStepsToDatabase(steps: ExperimentStep[]): ConvertedStep[] {
+  return steps.map((step, index) => ({
+    name: step.name,
+    type: mapStepTypeToDatabase(step.type),
+    orderIndex: index,
+    conditions: step.trigger.conditions,
+    actions: step.actions.map((action, actionIndex) => ({
+      name: action.name,
+      type: action.type,
+      orderIndex: actionIndex,
+      parameters: action.parameters,
+    })),
+  }));
+}
+```
+
+## Validation & Hash Drift Handling
+A validation workflow now surfaces structural integrity + reproducibility signals:
+
+### Validation Endpoint
+- `experiments.validateDesign` returns:
+  - `valid` + `issues[]`
+  - `integrityHash` (deterministic structural hash from compiled execution graph)
+  - `pluginDependencies` (sorted, namespaced with versions)
+  - Execution summary (steps/actions/transport mix)
+
+### Drift Detection (Client-Side)
+- Local state caches: `lastValidatedHash` + serialized design snapshot
+- Drift conditions:
+  1. Stored experiment `integrityHash` ≠ last validated hash
+  2. Design snapshot changed since last validation (structural or param changes)
+- Badge States:
+  - `Validated` (green outline): design unchanged since last validation and matches stored hash
+  - `Drift` (destructive): mismatch or post-validation edits
+  - `Unvalidated`: no validation performed yet
+
+### Rationale
+- Encourages explicit revalidation after structural edits
+- Prevents silent divergence from compiled execution artifact
+- Future: differentiate structural vs param-only drift (hash currently parameter-key-based)
+
+### Planned Enhancements
+- Hash stability tuning (exclude mutable free-text values if needed)
+- Inline warnings on mutated steps/actions
+- Optional auto-validate on save (configurable)
+
+## Plugin System Integration
+
+### Core Actions
+Loaded from `hristudio-core/plugins/` repositories:
+- **wizard-actions.json**: Wizard speech, gestures, instructions
+- **control-flow.json**: Wait, conditional logic, loops
+- **observation.json**: Behavioral coding, data collection, measurements
+
+### Robot Actions
+Dynamically loaded based on study configuration:
+- Robot-specific actions from plugin repositories
+- Parameter schemas automatically converted to form controls
+- Platform-specific validation and constraints
+
+### Fallback System
+Essential actions available even if plugin loading fails:
+- Basic wizard speech and gesture actions
+- Core control flow (wait, conditional)
+- Simple observation and data collection
+
+## Example Usage
+
+### Creating an Experiment
+1. **Add Steps**: Click "Add Step" to create containers in the experiment flow
+2. **Configure Steps**: Set name, type (sequential/parallel/conditional/loop), triggers
+3. **Drag Actions**: Drag from categorized library into step drop zones
+4. **Edit Properties**: Click actions to immediately edit parameters
+5. **Reorder**: Drag steps in flow, drag actions within steps
+6. **Save**: Direct conversion to database step/action records (provenance & execution metadata persisted)
+
+### Visual Workflow
+```
+Action Library          Experiment Flow              Properties
+┌─────────────┐        ┌──────────────────┐         ┌─────────────┐
+│ [Wizard]    │        │ Step 1: Welcome  │         │ Action:     │
+│ [Robot]     │ -----> │ ├ Wizard Says    │ ------> │ Wizard Says │
+│ [Control]   │        │ ├ Wait 2s        │         │ Text: ...   │
+│ [Observe]   │        │ └ Observe        │         │ Tone: ...   │
+└─────────────┘        └──────────────────┘         └─────────────┘
+```
+
+## Benefits
+
+### For Researchers
+- **Intuitive Design**: Natural workflow matching experimental thinking
+- **Visual Clarity**: Clear step-by-step experiment structure
+- **Plugin Integration**: Access to full ecosystem of robot platforms
+- **Direct Editing**: No complex nested selections required
+
+### For System Architecture
+- **Clean Separation**: Visual design vs execution logic clearly separated
+- **Database Integrity**: Direct 1:1 mapping maintains relationships
+- **Plugin Extensibility**: Easy integration of new robot platforms
+- **Type Safety**: Complete TypeScript integration throughout
+
+### For Development
+- **Maintainable Code**: Clean component architecture with clear responsibilities
+- **Performance**: Efficient rendering with proper React patterns
+- **Error Handling**: Graceful degradation when plugins fail
+- **Accessibility**: Built on accessible `@dnd-kit` foundation
+
+## Modular Architecture Summary
+| Module | Responsibility | Notes |
+|--------|----------------|-------|
+| `BlockDesigner.tsx` | Orchestration (state, save, validation, drift badges) | Thin controller after refactor |
+| `ActionRegistry.ts` | Core + plugin action loading, provenance, fallback | Stateless across renders (singleton) |
+| `ActionLibrary.tsx` | Categorized draggable palette | Performance-isolated |
+| `StepFlow.tsx` | Sortable steps & actions, structural UI | No parameter logic |
+| `PropertiesPanel.tsx` | Parameter + metadata editing (enhanced controls) | Switch + Slider integration |
+
+## Future Enhancements
+
+### Planned Features (Updated Roadmap)
+- **Step Templates**: Reusable step patterns for common workflows
+- **Visual Debugging**: Inline structural + provenance validation markers
+- **Collaborative Editing**: Real-time multi-user design sessions
+- **Advanced Conditionals**: Branching logic & guard editors (visual condition builder)
+- **Structural Drift Granularity**: Distinguish param-value vs structural changes
+- **Version Pin Diffing**: Detect plugin version upgrades vs design-pinned versions
+
+### Integration Opportunities
+- **Version Control**: Track experiment changes across iterations
+- **A/B Testing**: Support for experimental variations within single design
+- **Analytics Integration**: Step-level performance monitoring
+- **Export Formats**: Convert to external workflow systems
+
+This redesigned experiment designer now combines step-based structure, provenance tracking, transport-aware execution compilation, integrity hashing, and validation workflows to deliver reproducible, extensible, and transparent experimental protocols.
--- a/docs/quick-reference.md
+++ b/docs/quick-reference.md
@@ -21,9 +21,9 @@ bun run docker:up
 bun db:push
 bun db:seed

-# Sync plugin repositories (admin only)
-# This populates the plugin store with robot plugins
-# from https://repo.hristudio.com
+# Single command now syncs all repositories:
+# - Core blocks from localhost:3000/hristudio-core
+# - Robot plugins from https://repo.hristudio.com

 # Start development
 bun dev
@@ -89,7 +89,7 @@ Study → Experiment → Trial → Step → Action
 | `bun typecheck` | TypeScript validation |
 | `bun lint` | Code quality checks |
 | `bun db:push` | Push schema changes |
-| `bun db:seed` | Seed test data |
+| `bun db:seed` | Seed data & sync repositories |
 | `bun db:studio` | Open database GUI |

 ---
@@ -223,16 +223,16 @@ const hasRole = (role: string) => session?.user.role === role;

 ## 🤖 **Robot Integration**

-### Core Blocks System
+### Core Block System
 ```typescript
-// Core blocks loaded from hristudio-core repository
-await registry.loadCoreBlocks();
+// Core blocks loaded from local repository during development
+// Repository sync: localhost:3000/hristudio-core → database

-// Block categories:
+// Block categories (27 total blocks in 4 groups):
 // - Events (4): when_trial_starts, when_participant_speaks, etc.
 // - Wizard Actions (6): wizard_say, wizard_gesture, etc.  
 // - Control Flow (8): wait, repeat, if_condition, etc.
-// - Observation (8): observe_behavior, record_audio, etc.
+// - Observation (9): observe_behavior, record_audio, etc.
 ```

 ### Plugin Repository System
@@ -269,9 +269,9 @@ interface Plugin {
 ```

 ### Repository Integration
- **Live Repository**: `https://repo.hristudio.com`
- **Core Repository**: `https://core.hristudio.com` 
- **Auto-sync**: Admin dashboard → Repositories → Sync
+- **Robot Plugins**: `https://repo.hristudio.com` (live)
+- **Core Blocks**: `localhost:3000/hristudio-core` (development)
+- **Auto-sync**: Integrated into `bun db:seed` command
 - **Plugin Store**: Browse → Install → Use in experiments

 ---
@@ -408,7 +408,7 @@ bun typecheck
 3. Follow the established component patterns
 4. Add proper error boundaries for new features
 5. Test with multiple user roles
-6. Sync plugin repositories after setup for full functionality
+6. Use single `bun db:seed` for complete setup

 ### Code Standards
 - Use TypeScript strict mode
--- a/docs/work_in_progress.md
+++ b/docs/work_in_progress.md
@@ -2,6 +2,94 @@

 ## Recent Changes Summary (February 2025)

+### Experiment Designer Iteration (February 2025)
+
+#### **Current Focus: Modularized Designer (ActionLibrary / StepFlow / PropertiesPanel / Registry) & Validation Drift Handling**
+**Status**: In active iteration (not stable)
+
+The experiment designer has been refactored into modular components (registry + library + flow + properties panel). Active iteration now targets validation drift visibility, richer parameter controls, and continued provenance/compilation integrity.
+
+**Implemented (baseline):**
+- Step-first container model (steps hold ordered actions) (stable)
+- Drag-and-drop of actions into steps and reordering within steps (stable)
+- Conversion utility to DB step/action structures (provenance & execution metadata flattening) (stable)
+- Plugin action loading with namespaced IDs (pluginId.actionId) and provenance retention (stable)
+- Execution compilation pipeline (deterministic graph + integrity hash) integrated in update mutation (stable)
+
+**UI State (updated):**
+- Compact spacing (h-6/7 inputs) and category coloring
+- Dark mode variants applied (will audit accessibility)
+- Category color system (may refine semantic tokens; now reused across extracted components)
+- Step containers with colored left borders for type (moved into `StepFlow`)
+- Drag overlays + hover states (keyboard reordering & provenance badge a11y still pending)
+
+**Interaction Features (present / modularized):**
+- Multi-level drag & drop (steps + actions) via `StepFlow`
+- Direct action selection for inline parameter editing (now inside `PropertiesPanel`)
+- Action tooltip (plugin/source details; provenance badges present; enrichment still planned)
+- Drop zone highlighting
+- Pointer sensor activation threshold (mobile/touch review pending)
+
+**Plugin Integration (status):**
+- Registry loads core + study plugin actions (version stored; pin drift resolution still pending; designer now guarantees installed study plugin actions appear once experiment + study resolved)
+- Fallback actions present (unchanged)
+- Param schema → UI field mapping (primitive only; now enhanced for boolean + ranged number)
+- Provenance & execution metadata embedded in action instances (server persists) (stable)
+- Structured error surfaces for plugin load/validation failures still TODO
+
+**Technical Notes (updated):**
+- Types expanded: provenance, execution descriptors, integrity hashing structures (stable)
+- Acceptable performance; profiling after slider & drift logic integration still pending
+- Accessibility review pending (keyboard reorder, focus indicators, slider a11y labels)
+- Monolith split complete: `ActionRegistry.ts`, `ActionLibrary.tsx`, `StepFlow.tsx`, `PropertiesPanel.tsx`
+- Need unit tests for registry + conversion + compiler + drift serializer; none present
+
+**Key Files (current iteration - post modularization):**
+- `~/components/experiments/designer/BlockDesigner.tsx` - Orchestrator (state, validation, drift)
+- `~/components/experiments/designer/ActionRegistry.ts` - Registry (core + plugin + fallback)
+- `~/components/experiments/designer/ActionLibrary.tsx` - Categorized draggables
+- `~/components/experiments/designer/StepFlow.tsx` - Sortable steps & actions
+
+- `~/components/experiments/designer/PropertiesPanel.tsx` - Parameter & metadata editor
+**Current State Summary:**
+Functional baseline with modular extraction complete. Parameter UI upgraded (boolean → Switch, ranged number → Slider). Hash drift indicator implemented (Validated / Drift / Unvalidated). Still pending: enum grouping polish, keyboard DnD accessibility, version pin drift resolution, structured plugin load error surfaces.
+
+### Seed Script Simplification & Repository Integration (stable)
+
+#### **Unified Repository-Based Plugin Loading**
+Simplified and unified the seed scripts to load all plugins (core and robot) through the same repository sync mechanism.
+
+**Seed Script Consolidation:**
+- **Before**: 5 separate seed scripts (`seed.ts`, `seed-dev.ts`, `seed-simple.ts`, `seed-plugins.ts`, `seed-core-blocks.ts`)
+- **After**: Single `seed-dev.ts` script with integrated repository sync
+- **Benefits**: Consistent plugin loading, easier maintenance, real repository testing
+
+**Core Repository Integration:**
+- Core blocks now loaded from `http://localhost:3000/hristudio-core` during development
+- Same repository sync logic as robot plugins from `https://repo.hristudio.com`
+- Eliminates hardcoded core blocks - everything comes from repositories
+- Local core repository served from `public/hristudio-core/` directory
+
+**Simplified Setup Process:**
+```bash
+docker compose up -d
+bun db:push  
+bun db:seed  # Single command loads everything
+```
+
+**Repository Sync Integration:**
+- Core system blocks loaded as single plugin with 4 block groups (27 total blocks)
+- Robot plugins loaded individually (TurtleBot3 Burger/Waffle, NAO) 
+- All repositories use same sync validation and error handling
+- Proper metadata storage with repository references
+
+**Package.json Cleanup:**
+- Removed `db:seed:simple`, `db:seed:plugins`, `db:seed:core-blocks`, `db:seed:full`
+- Single `db:seed` command for all seeding needs
+- Simplified development workflow with fewer script options
+
+---
+
 ### Plugin Store Repository Integration

 #### **Complete Repository Synchronization System**
@@ -32,9 +120,7 @@ Fixed and implemented full repository synchronization for dynamic plugin loading
 - Repository names displayed for all plugins from proper metadata
 - Study-scoped plugin installation working correctly

---
-
-## Recent Changes Summary (December 2024)
+## Recent Changes Summary (December 2024) (historical reference)

 ### Plugin System Implementation

@@ -171,7 +257,7 @@ The experiment designer was completely redesigned to integrate seamlessly with t
 ```

 #### **Files Modified**
- `src/components/experiments/designer/EnhancedBlockDesigner.tsx` - Complete redesign
+- `src/components/experiments/designer/BlockDesigner.tsx` - Current iterative version
 - `src/components/ui/data-table.tsx` - Fixed control heights
 - `src/components/experiments/experiments-data-table.tsx` - Fixed select styling
 - `src/components/participants/participants-data-table.tsx` - Fixed select styling
@@ -279,24 +365,24 @@ The overall system theme was too monochromatic with insufficient color personali

 ---

-### Current Status
+### Current Status (Deprecated Section - To Be Rewritten)

 #### **Completed**
- Complete experiment designer redesign with unified components
+- (Remove) Designer not yet in a stable/complete state
 - All data table control styling standardized
 - System theme enhanced with better colors
 - Breadcrumb navigation completely fixed
 - Technical debt resolved

 #### **Production Ready**
- All TypeScript errors resolved
+- TypeScript surface improving; more types to add for provenance/execution
 - Consistent styling throughout application
 - Proper error handling and user feedback
 - Excellent dark mode support
 - Mobile/tablet friendly drag and drop

 #### **Improvements Achieved**
- **Visual Consistency**: Complete - All components now use unified design system
+- Visual consistency improved; still refactoring designer component size
 - **User Experience**: Significant improvement in navigation and usability
 - **Code Quality**: Clean, maintainable code with proper patterns
 - **Performance**: Optimized drag and drop with better collision detection
@@ -304,7 +390,7 @@ The overall system theme was too monochromatic with insufficient color personali

 ---

-### Core Block System Implementation (February 2024)
+### Core Block System Implementation (February 2024) (archived)

 **Complete documentation available in [`docs/core-blocks-system.md`](core-blocks-system.md)**

@@ -388,26 +474,37 @@ hristudio-core/

 ---

-### Documentation Status
+### Documentation Status (Updated With Provenance, Compilation, Pending Modularization)

 All changes have been documented and the codebase is ready for production deployment. The system now features:

-1. **Complete Plugin Architecture**: Both core blocks and robot actions loaded from repositories
-2. **Working Repository Sync**: Live synchronization from `https://repo.hristudio.com`
-3. **Proper Installation States**: Plugin store correctly shows installed vs available plugins
-4. **TypeScript Compliance**: All unsafe `any` types replaced with proper typing
-5. **Admin Access**: Full administrator role and permission system operational
+1. Unified repository loading in place (integrity hash now captured; version drift alerts pending)
+2. **Simplified Seed Scripts**: Single command setup with automatic repository synchronization  
+3. **Local Core Repository**: Core blocks served from `public/hristudio-core/` during development
+4. **Working Repository Sync**: Live synchronization from `https://repo.hristudio.com` for robot plugins
+5. **Proper Installation States**: Plugin store correctly shows installed vs available plugins
+6. **TypeScript Compliance**: All unsafe `any` types replaced with proper typing
+7. **Admin Access**: Full administrator role and permission system operational

-**Core Documentation Files:**
+**Core Documentation Files (Pending Updates):**
 - [`docs/core-blocks-system.md`](core-blocks-system.md) - Complete core blocks implementation guide
 - [`docs/plugin-system-implementation-guide.md`](plugin-system-implementation-guide.md) - Robot plugin system guide
- [`docs/work_in_progress.md`](work_in_progress.md) - Current development status
+- [`docs/work_in_progress.md`](work_in_progress.md) - Current development status (now includes provenance & compiler updates)

-**Production Readiness:**
- ✅ All TypeScript errors resolved (except documentation LaTeX)
- ✅ Repository synchronization fully functional
+**Readiness Caveats:**
+- Pending UI: provenance badges (partially done), re-validation triggers (implemented), drift indicator (TODO), modular split (TODO), parameter control upgrades (TODO), version drift resolution (TODO)
+- ✅ Simplified seed scripts with unified repository loading
+- ✅ Core repository integration via localhost during development
+- ✅ Repository synchronization fully functional for both core and robot plugins
 - ✅ Plugin store with proper installation state detection
 - ✅ Admin dashboard with repository management
 - ✅ Complete user authentication and authorization
 - ✅ Study-scoped plugin installation working
- ✅ 98% feature completion maintained
+- ✅ 98% feature completion maintained
+
+**Development Workflow (Stable Pieces):**
+- ✅ Single `bun db:seed` command for complete setup
+- ✅ Core blocks loaded from local repository structure  
+- ✅ Robot plugins synchronized from live repository
+- ✅ Consistent plugin architecture across all block types
+- ✅ Real repository testing during development