milktea 0.1.0

data/docs/devlog/20250704.md

@@ -0,0 +1,90 @@
+# Development Log - 2025-07-04
+
+## What's New
+
+#### Optional Loader System for Flexible Development Patterns
+The framework now provides an optional Loader system that enables developers to choose when autoloading and hot reloading capabilities are needed. This addresses the fundamental difference between standalone examples and full application development workflows.
+
+Key capabilities include:
+- **Selective activation**: Examples can run without unnecessary autoloading overhead
+- **Explicit configuration**: Applications can enable loading with `config.loader = Milktea::Loader.new(app_dir, runtime)`
+- **Graceful degradation**: Hot reloading works when Listen gem is available, falls back to basic autoloading when not
+- **Development-focused**: Optimized for the common pattern where examples are lightweight and apps need full development features
+
+#### Enhanced Hot Reloading Architecture
+The hot reloading system now provides more granular control over development workflows:
+
+- **Dual-mode operation**: Basic autoloading (always available) and file watching (conditionally enabled)
+- **Optional Listen integration**: Detects Listen gem availability at runtime using `gem "listen"` with proper error handling
+- **Message-driven reload**: Uses `Message::Reload` for clean communication between Loader and Runtime
+- **Zeitwerk integration**: Leverages Zeitwerk's robust autoloading capabilities as the foundation
+
+## What's Fixed
+
+#### Method Naming Consistency
+Renamed `hot_reload!` to `hot_reload` to better reflect the method's non-throwing behavior. The method gracefully handles cases where the Listen gem is unavailable, making the exclamation mark suffix misleading. This change improves API consistency and developer expectations.
+
+#### Configuration System Clarity
+Resolved the automatic initialization of the loader in the Config class, which was creating unnecessary overhead for simple use cases. The loader is now explicitly `nil` by default, requiring conscious activation for development scenarios that need it.
+
+#### Test Suite Alignment
+Updated all test files to follow the project's strict RSpec guidelines from CLAUDE.md:
+- Transformed multi-line tests into context + one-liner patterns
+- Applied spy pattern instead of `expect().to receive()` for better test isolation
+- Maintained comprehensive coverage while improving readability and maintainability
+
+## Design Decisions
+
+#### Reloader → Loader Rename and Optional Architecture
+**Context**: The original Reloader was automatically initialized for all applications, creating overhead for simple examples and unclear boundaries between autoloading and hot reloading.
+
+**Decision**: Renamed to Loader and made it optional by default, requiring explicit configuration.
+
+**Rationale**: This design better aligns with the framework's dual usage patterns:
+- Examples focus on demonstrating TUI concepts without development overhead
+- Applications explicitly enable development features when needed
+- Clear separation of concerns between framework core and development tooling
+
+This decision supports the Clean Architecture principle of dependency inversion, where the framework core doesn't depend on development-specific features.
+
+#### Runtime Detection of Optional Dependencies
+**Context**: The Listen gem provides file watching capabilities but shouldn't be a hard dependency for the framework.
+
+**Decision**: Use `gem "listen"` with `Gem::LoadError` rescue for runtime detection rather than gemspec dependencies.
+
+**Rationale**: This approach provides:
+- Zero additional dependencies for basic usage
+- Graceful enhancement when Listen is available
+- Clear error boundaries that don't affect core functionality
+- Better compatibility with different deployment environments
+
+#### Dependency Injection for Loader
+**Context**: The Loader needs access to Runtime for message communication and app_dir for file watching.
+
+**Decision**: Use constructor injection rather than setter injection or service location.
+
+**Rationale**: Constructor injection makes dependencies explicit and ensures the Loader is properly configured at creation time. This aligns with the framework's overall dependency injection pattern and makes testing more straightforward.
+
+## Impact
+
+The optional Loader system significantly improves the developer experience by:
+
+**For Example Development**: Examples now run with minimal overhead, focusing attention on TUI concepts rather than development tooling. This makes the framework more accessible to newcomers and reduces cognitive load when exploring features.
+
+**For Application Development**: Developers get explicit control over when and how autoloading capabilities are enabled, leading to more predictable development workflows and better understanding of their application's loading behavior.
+
+**For Framework Architecture**: The changes reinforce the Clean Architecture patterns by separating core framework functionality from development-specific features. This makes the codebase more maintainable and easier to extend.
+
+**For Testing Strategy**: The refactoring demonstrates and reinforces the project's commitment to RSpec best practices, creating a stronger foundation for future test development and maintaining high code quality standards.
+
+## Files Modified
+
+- `lib/milktea/loader.rb` - Renamed from reloader.rb, implements optional loading system
+- `lib/milktea/config.rb` - Made loader optional with attr_accessor instead of automatic initialization
+- `lib/milktea/program.rb` - Updated to handle optional loader with early return pattern
+- `lib/milktea/message.rb` - Added Message::Reload for hot reload communication
+- `lib/milktea/runtime.rb` - Added Message::Reload handling in execute_side_effect
+- `spec/milktea/loader_spec.rb` - Renamed from reloader_spec.rb, updated all tests to follow RSpec guidelines
+- `spec/milktea/config_spec.rb` - Updated to expect nil loader by default and test optional behavior
+- `spec/milktea/program_spec.rb` - Updated delegation tests to reflect removed loader delegation
+- `CLAUDE.md` - Updated with comprehensive RSpec style guidelines and development commands

data/docs/devlog/20250705.md

@@ -0,0 +1,81 @@
+# Development Log - 2025-07-05
+
+## What's New
+
+#### Dynamic Child Resolution Framework-Wide
+The dynamic child resolution mechanism has been elevated from a Container-specific feature to a core Model capability. This fundamental enhancement allows any Model subclass to use Symbol-based child definitions that resolve to methods returning Class objects. Developers can now implement dynamic behavior patterns across the entire framework, not just in layout containers.
+
+The implementation provides robust error handling with clear distinction between missing methods (NoMethodError) and invalid return types (ArgumentError). This enables sophisticated patterns like state-driven component switching while maintaining type safety and developer experience.
+
+#### Container Default View Implementation
+Container classes now automatically display their children without requiring boilerplate view methods. Since containers are fundamentally layout mechanisms designed to organize and present child components, the default behavior of `view = children_views` eliminates repetitive code while maintaining the ability to override for custom implementations.
+
+#### Enhanced Flexbox Layout System
+The Container layout system has been significantly expanded with bidirectional flexbox support. Developers can now create both column and row layouts with proportional sizing, providing CSS-like flexbox behavior in terminal interfaces. The system includes comprehensive bounds calculation that correctly propagates dimensions and positions to child components.
+
+#### Interactive Layout Examples
+Two new comprehensive examples demonstrate the framework's layout capabilities:
+- `container_layout.rb`: An interactive demo showcasing dynamic switching between column and row layouts with real-time bounds visualization
+- `container_simple.rb`: A basic demonstration of row layout with visual box rendering
+
+These examples integrate with tty-box for professional terminal UI presentation and serve as practical references for developers building TUI applications.
+
+## What's Fixed
+
+#### Hot Reloading and Dynamic Layout Integration
+Resolved a critical issue where dynamically created layout components (Row/Column) weren't receiving proper bounds information from their parent containers. Previously, dynamic layouts would use full screen dimensions instead of allocated flex space, breaking layout calculations during hot reload scenarios. The solution involved implementing Symbol-based child resolution that preserves bounds propagation throughout the component hierarchy.
+
+#### View Rendering Consistency
+Fixed children_views joining behavior to eliminate unnecessary newlines between child views. This prevents layout breaking in Container scenarios where child components should be positioned adjacently without automatic line separation. The change maintains flexibility for components that specifically need newline separation while providing sensible defaults for layout containers.
+
+#### Test Organization and Coverage
+Reorganized test suites to properly reflect the architectural changes. Dynamic child resolution tests were moved from container_spec to model_spec, aligning test coverage with the new framework-wide availability of the feature. This ensures maintainability and prevents confusion about where functionality is implemented.
+
+## Design Decisions
+
+#### Symbol-Based Dynamic Resolution Architecture
+**Context**: The original dynamic child resolution was implemented only in Container, limiting its use to layout scenarios. However, the pattern of dynamically selecting child components based on state is valuable across all Model types.
+
+**Decision**: Move the resolution mechanism to the base Model class with a clean API: `resolve_child(klass_or_symbol, state)`.
+
+**Rationale**: This promotes consistency across the framework and enables sophisticated component composition patterns. The Symbol-to-method resolution pattern provides a clean DSL while maintaining Ruby's dynamic capabilities. Error handling distinguishes between missing methods and type validation, providing clear debugging guidance.
+
+#### Container as Pure Layout Component
+**Context**: Container subclasses consistently implemented identical `view` methods that simply called `children_views`, representing boilerplate code with no variation.
+
+**Decision**: Implement `def view = children_views` as the default Container behavior.
+
+**Rationale**: Containers exist to organize and present child components, so displaying children is their natural purpose. This reduces cognitive overhead for developers while maintaining override capability for specialized containers. The decision aligns with the principle that containers should be transparent layout mechanisms.
+
+#### Framework-Wide Symbol Resolution
+**Context**: Initially, Symbol-based child definitions were Container-specific, creating inconsistency in the framework's component definition patterns.
+
+**Decision**: Standardize Symbol resolution across all Model classes through the base class implementation.
+
+**Rationale**: Consistency improves developer experience and enables advanced patterns like state-driven component composition throughout the framework. The unified approach reduces learning curve and provides predictable behavior regardless of component type.
+
+#### Bounds-Aware Dynamic Components
+**Context**: Dynamic layout switching required maintaining proper parent-child bounds relationships while enabling runtime component type changes.
+
+**Decision**: Ensure all dynamic resolution paths preserve bounds information propagation through the unified `resolve_child` method.
+
+**Rationale**: Terminal UI layout requires precise coordinate and dimension management. Breaking bounds propagation creates visual artifacts and layout inconsistencies. The solution maintains flexbox semantics while enabling dynamic behavior.
+
+## Impact
+
+These changes significantly enhance the framework's flexibility and developer experience. The dynamic child resolution system enables sophisticated component composition patterns previously impossible, while the enhanced Container system provides CSS-like layout capabilities for terminal interfaces.
+
+Developers can now build more maintainable TUI applications with less boilerplate code and greater architectural flexibility. The unified Symbol resolution pattern creates consistency across the framework, reducing learning curve and improving code predictability.
+
+The improvements particularly benefit complex applications requiring dynamic layouts, state-driven component switching, and sophisticated terminal interface designs. Hot reloading reliability ensures smooth development experience even with complex dynamic component hierarchies.
+
+## Files Modified
+
+- `lib/milktea/model.rb` - Added dynamic child resolution framework-wide
+- `lib/milktea/container.rb` - Added default view implementation, removed Container-specific resolution
+- `spec/milktea/model_spec.rb` - Added comprehensive dynamic resolution tests
+- `spec/milktea/container_spec.rb` - Reorganized tests, removed duplicated dynamic tests
+- `examples/container_layout.rb` - Interactive layout demo with dynamic switching
+- `examples/container_simple.rb` - Basic layout demonstration
+- `Gemfile` - Added tty-box dependency for enhanced examples
+- `lib/milktea/renderer.rb` - Enhanced cursor management for cleaner terminal experience

data/examples/container_layout.rb

@@ -0,0 +1,288 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "milktea"
+require "tty-box"
+
+# Container Layout Demo with Terminal Resize Support
+#
+# This example demonstrates:
+# - Flexbox-style container layouts (column and row)
+# - Dynamic layout switching
+# - Terminal resize handling at the root level
+#
+# When the terminal is resized, only the root model (LayoutDemoModel) needs
+# to handle Message::Resize by calling `with` to rebuild itself. All child
+# containers and components will automatically recalculate their bounds and
+# adapt to the new screen dimensions.
+
+# Box model that renders a tty-box with content
+class BoxModel < Milktea::Container
+  def view
+    TTY::Box.frame(
+      top: bounds.y,
+      left: bounds.x,
+      width: bounds.width,
+      height: bounds.height,
+      title: { top_left: " #{state[:title]} " },
+      border: :light,
+      padding: 1,
+      align: :center
+    ) do
+      content_lines.join("\n")
+    end
+  end
+
+  def update(message)
+    case message
+    when Milktea::Message::KeyPress
+      handle_keypress(message)
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  private
+
+  def default_state
+    { title: "Box", content: "Content", value: 0 }
+  end
+
+  def content_lines
+    lines = []
+    lines << state[:content] if state[:content]
+    lines << "Value: #{state[:value]}" if state.key?(:value)
+    lines << ""
+    lines << bounds_info
+    lines
+  end
+
+  def bounds_info
+    "#{bounds.width}×#{bounds.height} @(#{bounds.x},#{bounds.y})"
+  end
+
+  def handle_keypress(message)
+    case message.value
+    when "+"
+      [with(value: state[:value] + 1), Milktea::Message::None.new]
+    when "-"
+      [with(value: state[:value] - 1), Milktea::Message::None.new]
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+end
+
+# Column layout container
+class ColumnLayoutModel < Milktea::Container
+  direction :column
+  child BoxModel, ->(state) { { title: "Header", content: "Top Section", value: state[:header_value] } }, flex: 1
+  child BoxModel, ->(state) { { title: "Content", content: "Main Area", value: state[:content_value] } }, flex: 3
+  child BoxModel, ->(state) { { title: "Footer", content: "Bottom Status", value: state[:footer_value] } }, flex: 1
+
+  def update(message)
+    case message
+    when Milktea::Message::KeyPress
+      handle_keypress(message)
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  private
+
+  def default_state
+    { header_value: 1, content_value: 10, footer_value: 5 }
+  end
+
+  def handle_keypress(message)
+    case message.value
+    when "+"
+      [with(
+        header_value: state[:header_value] + 1,
+        content_value: state[:content_value] + 1,
+        footer_value: state[:footer_value] + 1
+      ), Milktea::Message::None.new]
+    when "-"
+      [with(
+        header_value: [state[:header_value] - 1, 0].max,
+        content_value: [state[:content_value] - 1, 0].max,
+        footer_value: [state[:footer_value] - 1, 0].max
+      ), Milktea::Message::None.new]
+    when "q"
+      [self, Milktea::Message::Exit.new]
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+end
+
+# Row layout container
+class RowLayoutModel < Milktea::Container
+  direction :row
+  child BoxModel, ->(state) { { title: "Left", content: "Sidebar", value: state[:left_value] } }, flex: 1
+  child BoxModel, ->(state) { { title: "Center", content: "Main Content", value: state[:center_value] } }, flex: 2
+  child BoxModel, ->(state) { { title: "Right", content: "Info Panel", value: state[:right_value] } }, flex: 1
+
+  def update(message)
+    case message
+    when Milktea::Message::KeyPress
+      handle_keypress(message)
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  private
+
+  def default_state
+    { left_value: 3, center_value: 7, right_value: 2 }
+  end
+
+  def handle_keypress(message)
+    case message.value
+    when "+"
+      [with(
+        left_value: state[:left_value] + 1,
+        center_value: state[:center_value] + 1,
+        right_value: state[:right_value] + 1
+      ), Milktea::Message::None.new]
+    when "-"
+      [with(
+        left_value: [state[:left_value] - 1, 0].max,
+        center_value: [state[:center_value] - 1, 0].max,
+        right_value: [state[:right_value] - 1, 0].max
+      ), Milktea::Message::None.new]
+    when "q"
+      [self, Milktea::Message::Exit.new]
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+end
+
+# Status bar model
+class StatusBar < Milktea::Model
+  def view
+    layout_type = state[:show_column] ? "Column" : "Row"
+    TTY::Box.frame(
+      top: bounds.y,
+      left: bounds.x,
+      width: bounds.width,
+      height: bounds.height,
+      title: { top_left: " Layout Demo " },
+      border: :light,
+      align: :center
+    ) do
+      "Current: #{layout_type} Layout | 't' toggle | '+/-' change values | 'q' quit"
+    end
+  end
+
+  def update(_message)
+    [self, Milktea::Message::None.new]
+  end
+
+  private
+
+  def bounds
+    @bounds ||= Milktea::Bounds.new(
+      width: state[:width] || screen_width,
+      height: state[:height] || screen_height,
+      x: state[:x] || 0,
+      y: state[:y] || 0
+    )
+  end
+end
+
+# Main application that toggles between layouts
+class LayoutDemoModel < Milktea::Container
+  direction :column
+  child :status_bar, flex: 1
+  child :dynamic_layout, lambda { |state|
+    state.slice(:header_value, :content_value, :footer_value, :left_value, :center_value, :right_value)
+  }, flex: 5
+
+  def update(message)
+    case message
+    when Milktea::Message::KeyPress
+      handle_keypress(message)
+    when Milktea::Message::Resize
+      # Rebuild model with fresh class to pick up new screen dimensions
+      [with, Milktea::Message::None.new]
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  private
+
+  def default_state
+    {
+      show_column: true,
+      header_value: 1,
+      content_value: 10,
+      footer_value: 5,
+      left_value: 3,
+      center_value: 7,
+      right_value: 2
+    }
+  end
+
+  def status_bar
+    StatusBar
+  end
+
+  def dynamic_layout
+    state[:show_column] ? ColumnLayoutModel : RowLayoutModel
+  end
+
+  def handle_keypress(message)
+    case message.value
+    when "t"
+      [with(show_column: !state[:show_column]), Milktea::Message::None.new]
+    when "+"
+      increment_values
+    when "-"
+      decrement_values
+    when "q"
+      [self, Milktea::Message::Exit.new]
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  def increment_values
+    [with(
+      header_value: state[:header_value] + 1,
+      content_value: state[:content_value] + 1,
+      footer_value: state[:footer_value] + 1,
+      left_value: state[:left_value] + 1,
+      center_value: state[:center_value] + 1,
+      right_value: state[:right_value] + 1
+    ), Milktea::Message::None.new]
+  end
+
+  def decrement_values
+    [with(
+      header_value: [state[:header_value] - 1, 0].max,
+      content_value: [state[:content_value] - 1, 0].max,
+      footer_value: [state[:footer_value] - 1, 0].max,
+      left_value: [state[:left_value] - 1, 0].max,
+      center_value: [state[:center_value] - 1, 0].max,
+      right_value: [state[:right_value] - 1, 0].max
+    ), Milktea::Message::None.new]
+  end
+end
+
+# Create and run the layout demo
+puts "Container Layout Demo with Terminal Resize Support"
+puts "Press 't' to toggle between column and row layouts"
+puts "Use +/- to change values, 'q' to quit"
+puts "Try resizing your terminal window to see automatic layout adaptation"
+puts "Press any key to start..."
+$stdin.gets
+
+model = LayoutDemoModel.new
+program = Milktea::Program.new(model)
+program.run

data/examples/container_simple.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "milktea"
+require "tty-box"
+
+# Simple box component
+class SimpleBox < Milktea::Container
+  def view
+    TTY::Box.frame(
+      top: bounds.y,
+      left: bounds.x,
+      width: bounds.width,
+      height: bounds.height,
+      title: { top_left: " #{state[:title]} " },
+      border: :light,
+      padding: 1
+    ) do
+      "#{state[:content]}\n#{bounds.width}×#{bounds.height}"
+    end
+  end
+
+  def update(_message)
+    [self, Milktea::Message::None.new]
+  end
+
+  private
+
+  def default_state
+    { title: "Box", content: "Hello" }
+  end
+end
+
+# Row layout example
+class RowDemo < Milktea::Container
+  direction :row
+  child SimpleBox, ->(_state) { { title: "Left", content: "Panel 1" } }, flex: 1
+  child SimpleBox, ->(_state) { { title: "Center", content: "Main Area" } }, flex: 2
+  child SimpleBox, ->(_state) { { title: "Right", content: "Panel 3" } }, flex: 1
+
+  def view
+    children_views
+  end
+
+  def update(message)
+    case message
+    when Milktea::Message::KeyPress
+      if message.value == "q"
+        [self, Milktea::Message::Exit.new]
+      else
+        [self, Milktea::Message::None.new]
+      end
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+end
+
+# Test the layout
+puts "Simple Container Row Layout Test"
+puts "Press 'q' to quit, any other key to continue..."
+
+model = RowDemo.new(width: 60, height: 15)
+program = Milktea::Program.new(model)
+program.run

data/examples/counter.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "milktea"
+
+# Counter model demonstrating state management
+class CounterModel < Milktea::Model
+  def initialize(state = {})
+    default_state = { count: 0 }
+    super(default_state.merge(state))
+  end
+
+  def view
+    <<~VIEW
+      Counter: #{state[:count]}
+
+      Press:
+      - '+' or 'k' to increment
+      - '-' or 'j' to decrement
+      - 'r' to reset
+      - 'q' to quit
+
+      Ctrl+C to exit
+    VIEW
+  end
+
+  def update(message)
+    case message
+    when Milktea::Message::Exit
+      [self, message]
+    when Milktea::Message::KeyPress
+      handle_keypress(message)
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  private
+
+  def handle_keypress(message)
+    case message.value
+    when "+", "k"
+      [with(count: state[:count] + 1), Milktea::Message::None.new]
+    when "-", "j"
+      [with(count: state[:count] - 1), Milktea::Message::None.new]
+    when "r"
+      [with(count: 0), Milktea::Message::None.new]
+    when "q"
+      [self, Milktea::Message::Exit.new]
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+end
+
+# Create and run the counter program
+model = CounterModel.new
+program = Milktea::Program.new(model)
+program.run