path: root/js/baba-yaga/HOST.md

# Baba Yaga Host Application

## Overview

The Baba Yaga Host Application is a mobile-first, Smalltalk-inspired interactive development environment where users can create, extend, and run applications entirely within the Baba Yaga programming language. The application provides a complete development ecosystem with an infinite canvas, persistent floating action button (FAB), and integrated development tools.

## Core Architecture

### Infinite Canvas System
- **Free-form positioning** with optional grid snapping toggle
- **Grouping and containers** for organizing related elements
- **No zoom levels** - focused on simplicity and performance
- **Scrollable viewport** with smooth panning
- **Element management** with drag-and-drop positioning

### Floating Action Button (FAB)
- **Persistent positioning** - always accessible regardless of canvas position
- **Context-aware actions** - shows relevant options based on current selection
- **Primary actions**: Add Code Editor, Interpreter, REPL, Project Explorer, Debugger
- **Secondary actions**: Create groups, add components, project operations

## Project System

### Project Format
- **Layered JSON/Binary Hybrid**: Core structure in JSON for git compatibility with custom serialization layer for performance
- **Custom Serialization**: Efficient encoding of Baba Yaga data structures with compression for large assets
- **Self-contained** - no external dependencies with embedded assets
- **Asset support**: Baba Yaga files, JSON/CSV data, optimized PNG images, audio files
- **Project metadata**: name, description, version, author, creation date, performance hints
- **Export/Import**: Local storage persistence with disk import/export and incremental saves

### Project Structure
```
project-name/
├── project.json         # Project metadata and configuration
├── src/                 # Baba Yaga source files
│   ├── main.baba        # Entry point
│   └── components/      # Custom components
├── assets/              # Data files, images, audio
├── tests/               # Test files
└── components/          # Shared component definitions
```

### Asset Management

#### Image Assets
- **Format**: PNG-only with optimization constraints for mobile performance
- **Size Limits**: Maximum 1024x1024 pixels, recommended 512x512 for optimal performance
- **Color Constraints**: Limited to 256-color palette with optional dithering
- **Storage**: Base64-encoded in project JSON with compression for large images
- **Optimization**: Automatic palette reduction and dithering on import

#### Image Integration with Baba Yaga
- **Image Type**: Native `Image` type with metadata (width, height, palette info)
- **Loading Functions**: `image.load(id)` and `image.loadAsync(id)` for asset access
- **Manipulation**: Basic operations like `image.scale`, `image.crop`, `image.flip`
- **Display**: Integration with rendering system for canvas display
- **Memory Management**: Reference counting with automatic cleanup

#### Audio Assets (nice to have, not for version 1)
- **Format**: Compressed audio formats (MP3, OGG) with size limits
- **Storage**: Base64-encoded with optional streaming for large files
- **Baba Yaga Integration**: `audio.play(id)`, `audio.stop(id)`, `audio.volume(id, level)` functions

## Component System

### Built-in Components
- **Code Editor**: Line and row numbered Baba Yaga editor with live preview (syntax highlighting is a nice to have, but not with heavy dependencies)
- **Interpreter**: Runtime execution engine with error handling
- **REPL**: Interactive read-eval-print loop with command history
- **Project Explorer**: File/directory navigation and management
- **Debugger**: Error display, stack traces, and debugging tools
- **Testing Panel**: Built-in test runner and results display

### Custom Components
- **Baba Yaga-powered widgets** - users create components using the language
- **Component sharing** via project exports
- **Event-driven communication** following functional programming principles
- **Immutable state management** consistent with Baba Yaga's functional style

### Component Communication
- **FRP/Elm Hybrid Architecture**: Event-driven communication using Functional Reactive Programming principles combined with Elm-style model-view-update pattern
- **Baba Yaga Pattern Matching**: Event handlers implemented using `when` expressions with guards for sophisticated event routing
- **Immutable Event Streams**: Events as immutable data structures with functional transformations
- **Message passing** for inter-component communication via typed message protocols
- **Shared state** through immutable data structures with atomic updates
- **Functional composition** - components as pure functions with clear input/output contracts

#### Event System Design
- **Event Bus**: Centralized pub/sub system with topic-based routing
- **Event Types**: Strongly typed events using Baba Yaga's type system
- **Event Filtering**: Pattern matching for selective event processing
- **Event Transformation**: Functional mapping and filtering of event streams
- **Error Handling**: Failed event handlers return `Err` values without crashing the system

## Development Workflow

### Live Coding
- **Immediate execution** of Baba Yaga code changes
- **Real-time preview** of component updates
- **Hot reloading** for rapid iteration
- **Error highlighting** with inline feedback

### Debugging Experience
- **Clear error messages** with actionable guidance
- **Stack trace visualization** showing execution flow
- **Variable inspection** at breakpoints
- **Step-through debugging** for complex logic
- **Error recovery suggestions** and quick fixes

### Testing Integration
- **Built-in test runner** with minimal setup
- **Test result display** in dedicated panel
- **Test-driven development** workflow support
- **Assertion library** integrated with Baba Yaga

## Mobile-First Design

### Responsive Interface
- **Adaptive layouts** for different screen sizes
- **Touch-friendly controls** with appropriate sizing
- **Orientation handling** for portrait and landscape
- **Accessibility features** for mobile users

### Input Handling
- **Native HTML5 inputs** for keyboard input
- **Touch gestures** for canvas navigation
- **FAB-centric interaction** - all major actions through the floating button
- **Contextual menus** for secondary actions

## Technical Implementation

### Core Technologies
- **Web-based architecture** for cross-platform compatibility
- **Canvas API** for infinite scroll and element positioning
- **FRP Event System** for component communication with Baba Yaga pattern matching
- **Custom Serialization Layer** for efficient project data encoding
- **Local Storage** for project persistence with incremental saves
- **File API** for import/export operations
- **Web Workers** for background processing and image optimization

### Performance Considerations
- **Virtual scrolling** for large canvases with many components
- **Lazy loading** of components and assets with demand-based initialization
- **Efficient rendering** with requestAnimationFrame and batched updates
- **Memory management** for long-running projects with garbage collection hints
- **Event Stream Optimization**: Debounced event processing and filtered subscriptions
- **Image Optimization**: Automatic compression, palette reduction, and progressive loading
- **Serialization Performance**: Efficient encoding/decoding with compression for large projects

### Data Persistence
- **Auto-save** to local storage
- **Project export** to disk
- **Version history** with Smalltalk-style image snapshots
- **Incremental saves** for large projects

## Project Templates

### Starter Kits
- **Hello World**: Basic project structure
- **Component Library**: Pre-built UI components
- **Data Processing**: CSV/JSON handling examples
- **Game Development**: Simple game framework
- **Web App**: Basic web application template

### Template System
- **Customizable templates** using Baba Yaga code
- **Template sharing** via project exports
- **Community templates** through shared projects
- **Template validation** and testing

## Future Considerations

### Potential Enhancements
- **Advanced FRP Features**: Time-travel debugging, event stream visualization, complex event processing
- **Cloud synchronization** for project backup with conflict resolution
- **Collaborative editing** for team projects with operational transformation
- **Plugin system** for extending functionality with Baba Yaga components
- **Performance profiling** tools for event streams and component rendering
- **Advanced debugging** features with FRP event tracing

### Scalability
- **Large project support** with efficient memory usage
- **Component library management** for complex applications
- **Project optimization** tools
- **Bundle size optimization** for sharing

## Development Priorities

### Phase 1: Core Infrastructure
- Infinite canvas with basic positioning
- FAB system and core components
- Project format and persistence
- Basic Baba Yaga integration

### Phase 2: Development Tools
- Code editor with syntax highlighting
- Interpreter and REPL integration
- Debugging and error handling
- Testing framework

### Phase 3: User Experience
- Component creation and sharing
- Project templates and examples
- Mobile optimization
- Performance improvements

### Phase 4: Advanced Features
- Custom component system
- Advanced debugging tools
- Project optimization
- Community features

This architecture provides a solid foundation for a Smalltalk-inspired development environment while maintaining the functional programming principles of Baba Yaga and focusing on mobile-first user experience.