diff options
Diffstat (limited to 'js/baba-yaga/HOST.md')
| -rw-r--r-- | js/baba-yaga/HOST.md | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/js/baba-yaga/HOST.md b/js/baba-yaga/HOST.md new file mode 100644 index 0000000..504ed96 --- /dev/null +++ b/js/baba-yaga/HOST.md @@ -0,0 +1,214 @@ +# 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. |