milktea 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ed418298f9856106a16ea4b8547cddbdde2841e270faa7e7c5750e45498055c
-  data.tar.gz: ebbc971d234ee535db7d4cda1d57a94c57fbe6a6cade430d3a715a13340fae24
+  metadata.gz: b8fc1c4405e6f8b4d6969285482fc16ec7d103ff9399f89a2606532e3545b9a6
+  data.tar.gz: 38638d551a1c7ffd34c0b2d32ff75824db9daff1371cb3ecf30ab7604f714f14
 SHA512:
-  metadata.gz: 4733b94d3d650b662671a3d14fee70d7a4aec3b8dd7bbb64f69f4f5e4bd8744a2993791bcc02690b349fa95b4dfdf0d4f01eb26261a733ce800ad0fa8823137a
-  data.tar.gz: 0f871c49c46ec816401b93cf7f16e856ccb2103e8bc256665d2a3fffcb0a8f669ba241f0d6279d37a0716acbe6e6ca1152d3f2a4283fdbedf925011a0f910eea
+  metadata.gz: 0f2e50699ec28cddbeaabfa11ceeda12bf544d4572d38d78fd8edbcaa2efe0ad7d4b7e0f47af1b7945ec29fb74614ae2661da2ede93e40daa2952bab82d7426f
+  data.tar.gz: 5b4397dfb287ace7627b374a005f62b93fd76ac578aff0c9067df52175eb2a4345ff9548998dd63b8cf8ba27b6ac0387b1c0e57fdd76afb19034922ece5c2bf5

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.0"
+}

data/.rubocop.yml

@@ -1,8 +1,9 @@
 AllCops:
   NewCops: enable
   SuggestExtensions: false
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
   Exclude:
+    - 'vendor/**/*'
     - 'examples/**/*'
 
 Style/StringLiterals:

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.2.0](https://github.com/elct9620/milktea/compare/v0.1.0...v0.2.0) (2025-07-06)
+
+
+### Features
+
+* add truncation mode to Milktea::Text component ([031f87a](https://github.com/elct9620/milktea/commit/031f87a6f55476098ac7247b8041e32e38e67961))
+* bump minimum Ruby version to 3.2+ for Zeitwerk compatibility ([18cc801](https://github.com/elct9620/milktea/commit/18cc8011c2ac4586ad849bf4670750ecbc011294))
+* implement Message::Tick with timestamp for timing-based updates ([982baec](https://github.com/elct9620/milktea/commit/982baeca567eed949ec82187fefb1f45078e97f5))
+* implement Milktea::Text component with overflow handling ([5a0ef38](https://github.com/elct9620/milktea/commit/5a0ef38708e74f4eef6905c2f72813c4259fdfa0))
+* refactor examples to use bundler/inline for self-contained dependencies ([2192a6b](https://github.com/elct9620/milktea/commit/2192a6b185e04d26fa258231c88f412f39254b1a))
+
+
+### Bug Fixes
+
+* add rubocop-rubycw gem to resolve CI failure ([82b0dd7](https://github.com/elct9620/milktea/commit/82b0dd71bd535e8b2169401ca5e1f78e9f5dea79))
+* properly configure RuboCop plugins to resolve CI failures ([d82e2c8](https://github.com/elct9620/milktea/commit/d82e2c83338eaca3841bfbb3cceec401bbdc6787))
+* use clear_screen_down instead of clear_screen in renderer ([d41d431](https://github.com/elct9620/milktea/commit/d41d43115ca36b801fe5289d38996d4a38997e22))

data/CLAUDE.md

@@ -202,7 +202,63 @@ This project follows Clean Architecture and Domain-Driven Design (DDD) principle
 
 Follow these conventions when writing RSpec tests:
 
-1. **ALWAYS prefer one-line `it { ... }` syntax**:
+### Critical Anti-Patterns to Avoid
+
+**NEVER use introspection methods to test private implementation details:**
+
+```ruby
+# BAD - Never use these anti-patterns
+it { expect(program.send(:check_resize)).to be_nil }
+it { expect(subject.instance_variable_get(:@output)).to eq($stdout) }
+it { expect(object.send(:private_method)).to eq(value) }
+
+# GOOD - Test through public API and observable behavior
+it { expect(runtime).to have_received(:enqueue) }
+it { expect(output.string).to include("expected content") }
+it { expect(program).to respond_to(:stop) }
+```
+
+**Why these are anti-patterns:**
+- Tests implementation details instead of behavior
+- Makes tests brittle and coupled to internal structure  
+- Violates encapsulation principles
+- Makes refactoring difficult
+
+**Always test through public interfaces and observable outcomes.**
+
+### Core Testing Conventions
+
+1. **Use `describe` blocks to reference actual methods**:
+   ```ruby
+   # GOOD - Reference actual methods
+   describe "#initialize" do
+   describe "#update" do  
+   describe "#with" do
+   describe ".configure" do  # Class method
+   describe ".new" do       # Class method
+   
+   # BAD - Generic descriptions that don't map to methods
+   describe "initialization" do
+   describe "test creation" do
+   describe "updating behavior" do
+   describe "configuration setup" do
+   ```
+
+2. **Use `context` blocks with "when" for conditional scenarios**:
+   ```ruby
+   # GOOD - Always start context with "when" for conditions
+   context "when merging provided state with default state" do
+   context "when no config is provided" do
+   context "when runtime is running" do
+   context "when renderer detects resize" do
+   
+   # BAD - Don't use context for non-conditional descriptions
+   context "merging state" do
+   context "configuration testing" do  
+   context "with custom values" do
+   ```
+
+3. **ALWAYS prefer one-line `it { ... }` syntax**:
    ```ruby
    # Preferred - Always use this when possible
    it { expect(model.state[:count]).to eq(0) }
@@ -215,7 +271,7 @@ Follow these conventions when writing RSpec tests:
    end
    ```
 
-2. **Use `subject` to define test targets**:
+4. **Use `subject` to define test targets**:
    ```ruby
    subject(:program) { described_class.new }
    subject(:new_model) { model.with(count: 5) }
@@ -226,7 +282,7 @@ Follow these conventions when writing RSpec tests:
    subject { described_class.env }
    ```
 
-3. **Use `let` for test dependencies and lazy evaluation**:
+5. **Use `let` for test dependencies and lazy evaluation**:
    ```ruby
    let(:output) { StringIO.new }
    let(:new_model) { result.first }
@@ -234,7 +290,7 @@ Follow these conventions when writing RSpec tests:
    let(:original_children) { parent_model.children }
    ```
 
-4. **Use `context` to group related scenarios and enable one-liners**:
+6. **Use `context` to group related scenarios and enable one-liners**:
    ```ruby
    # Good - Use context to set up scenarios for one-line tests
    context "when merging provided state with default state" do
@@ -251,7 +307,7 @@ Follow these conventions when writing RSpec tests:
    end
    ```
 
-5. **Use `is_expected` when testing the subject directly**:
+7. **Use `is_expected` when testing the subject directly**:
    ```ruby
    it { is_expected.to be_running }  # Preferred
    it { is_expected.not_to be(model) }
@@ -263,7 +319,7 @@ Follow these conventions when writing RSpec tests:
    it { expect(described_class.root).to be_a(Pathname) }
    ```
 
-6. **Use `before` blocks for setup actions, not variable assignments**:
+8. **Use `before` blocks for setup actions, not variable assignments**:
    ```ruby
    # Good - Setup actions in before blocks
    context "when configuring with block" do
@@ -284,13 +340,13 @@ Follow these conventions when writing RSpec tests:
    end
    ```
 
-7. **Use `.to change()` for testing immutability**:
+9. **Use `.to change()` for testing immutability**:
    ```ruby
    it { expect { model.update(:increment) }.not_to change(model, :state) }
    it { expect { model.with(count: 5) }.not_to change(model, :state) }
    ```
 
-7. **Each `it` block should have only one expectation**:
+10. **Each `it` block should have only one expectation**:
    ```ruby
    # Good - Separate one-line tests
    it { expect(new_model).not_to be(model) }
@@ -304,7 +360,7 @@ Follow these conventions when writing RSpec tests:
    end
    ```
 
-8. **Transform multi-line tests into context + one-liners**:
+11. **Transform multi-line tests into context + one-liners**:
    ```ruby
    # Good - Use context to enable one-liner
    context "when called on base class" do
@@ -328,7 +384,7 @@ Follow these conventions when writing RSpec tests:
    end
    ```
 
-10. **PRIORITY: Transform ANY multi-line test into context + one-liner**:
+12. **PRIORITY: Transform ANY multi-line test into context + one-liner**:
     ```ruby
     # If you find yourself writing this:
     it "merges provided state with default state" do
@@ -344,24 +400,6 @@ Follow these conventions when writing RSpec tests:
     end
     ```
 
-11. **Never test private instance variables directly**:
-    ```ruby
-    # Bad - Testing implementation details
-    it { expect(subject.instance_variable_get(:@output)).to eq($stdout) }
-    
-    # Good - Testing public behavior with one-liner
-    it { expect(output.string).to include("expected content") }
-    ```
-
-12. **Focus on observable behavior, not implementation**:
-    ```ruby
-    # Bad - Checking internal state
-    it { expect(program.instance_variable_get(:@renderer)).to be_a(Milktea::Renderer) }
-    
-    # Good - Testing actual public behavior with one-liner
-    it { expect(runtime).to have_received(:stop) }
-    ```
-
 13. **Prefer `instance_double` over extensive `allow` calls**:
     ```ruby
     # Bad - Multiple allow calls
@@ -384,7 +422,7 @@ Follow these conventions when writing RSpec tests:
     end
     ```
 
-13. **Use spies for testing delegation instead of expect().to receive()**:
+14. **Use spies for testing delegation instead of expect().to receive()**:
     ```ruby
     # Bad - Pre-setting expectations
     it "delegates to runtime stop" do
@@ -401,7 +439,7 @@ Follow these conventions when writing RSpec tests:
     end
     ```
 
-14. **Use RSpec's `output` matcher for testing stdout/stderr**:
+15. **Use RSpec's `output` matcher for testing stdout/stderr**:
     ```ruby
     # Good - Using output matcher
     it "prints to stdout" do
@@ -422,7 +460,7 @@ Follow these conventions when writing RSpec tests:
     end
     ```
 
-15. **Use `allow(ENV).to receive(:fetch)` for environment variable mocking**:
+16. **Use `allow(ENV).to receive(:fetch)` for environment variable mocking**:
     ```ruby
     # Good - Mock ENV.fetch calls
     before { allow(ENV).to receive(:fetch).with("MILKTEA_ENV", nil).and_return("test") }
@@ -432,7 +470,7 @@ Follow these conventions when writing RSpec tests:
     after { ENV.delete("MILKTEA_ENV") }
     ```
 
-16. **Structure module/class method tests with clear subject definitions**:
+17. **Structure module/class method tests with clear subject definitions**:
     ```ruby
     describe ".root" do
       subject { described_class.root }
@@ -453,7 +491,7 @@ Follow these conventions when writing RSpec tests:
     end
     ```
 
-17. **Use named subjects for configuration testing**:
+18. **Use named subjects for configuration testing**:
     ```ruby
     describe ".configure" do
       subject(:config) { described_class.config }  # Named subject for clarity
@@ -474,7 +512,15 @@ Follow these conventions when writing RSpec tests:
 
 ### RSpec Style Summary
 
-**CRITICAL RULE**: Always prefer `it { ... }` one-line syntax. If you find yourself writing a multi-line `it` block, immediately refactor it into a `context` with a `subject` to enable one-line tests.
+**CRITICAL ANTI-PATTERNS - NEVER DO THESE:**
+- Never use `send(:private_method)` to test private methods
+- Never use `instance_variable_get(:@var)` to test private variables
+- Always test through public interfaces and observable behavior
+
+**CRITICAL CONVENTIONS:**
+- `describe` blocks must reference actual methods (`#initialize`, `.configure`)
+- `context` blocks must start with "when" for conditional scenarios
+- Always prefer `it { ... }` one-line syntax over multi-line blocks
 
 **The Golden Pattern**:
 ```ruby
@@ -517,7 +563,7 @@ end
 
 ## Important Notes
 
-- Ruby version requirement: >= 3.1.0
+- Ruby version requirement: >= 3.2.0
 - Uses conventional commits format in English
 - The gemspec uses git to determine which files to include in the gem
 - Currently in early development (v0.1.0) with core architecture implemented

data/README.md

@@ -12,6 +12,8 @@ A Terminal User Interface (TUI) framework for Ruby, inspired by [Bubble Tea](htt
 - 🔄 **Hot Reloading**: Instant feedback during development (similar to web frameworks)
 - 📱 **Responsive Design**: Automatic adaptation to terminal resize events
 - 🧩 **Composable Components**: Build complex UIs from simple, reusable models
+- 📝 **Text Components**: Unicode-aware text rendering with wrapping and truncation
+- ⏱️ **Timing System**: Built-in support for animations and time-based updates
 - 🎨 **Rich Terminal Support**: Leverage TTY gems for advanced terminal features
 
 ## Installation
@@ -224,14 +226,20 @@ end
 
 Explore the `examples/` directory for comprehensive demonstrations:
 
-- **[Container Layout](examples/container_layout.rb)**: Flexbox-style layouts with resize support
+- **[Simple Counter](examples/simple.rb)**: Basic Elm Architecture patterns
+- **[Container Layout](examples/container_layout.rb)**: Flexbox-style layouts with resize support  
+- **[Text Components](examples/text_demo.rb)**: Unicode text rendering with dual modes
+- **[Animations](examples/tick_example.rb)**: Timing-based animations and dynamic content
 - **[Hot Reload Demo](examples/hot_reload_demo.rb)**: Development workflow with instant updates
+- **[Dashboard](examples/dashboard.rb)**: Complex multi-component layout
 
 Run examples:
 
 ```bash
+ruby examples/simple.rb
+ruby examples/text_demo.rb
+ruby examples/tick_example.rb
 ruby examples/container_layout.rb
-ruby examples/hot_reload_demo.rb
 ```
 
 ## Advanced Features
@@ -318,17 +326,19 @@ program.run
 
 - **`Milktea::Model`**: Base class for all UI components
 - **`Milktea::Container`**: Layout container with flexbox-style properties
+- **`Milktea::Text`**: Unicode-aware text component with dual rendering modes
 - **`Milktea::Application`**: High-level application wrapper
 - **`Milktea::Program`**: Main application runtime
-- **`Milktea::Message`**: Standard message types (KeyPress, Exit, Resize, Reload)
+- **`Milktea::Message`**: Standard message types for application events
 
 ### Message System
 
-- **`Message::KeyPress`**: Keyboard input events
+- **`Message::KeyPress`**: Keyboard input events with key details
+- **`Message::Tick`**: Timing events with timestamps for animations
 - **`Message::Exit`**: Application termination
-- **`Message::Resize`**: Terminal size changes
-- **`Message::Reload`**: Hot reload events
-- **`Message::None`**: No-operation message
+- **`Message::Resize`**: Terminal size changes  
+- **`Message::Reload`**: Hot reload events (development)
+- **`Message::None`**: No-operation message (no render)
 
 For detailed API documentation, see the [documentation website](https://rubydoc.info/gems/milktea).
 

data/docs/devlog/20250705.md

@@ -20,6 +20,12 @@ Two new comprehensive examples demonstrate the framework's layout capabilities:
 
 These examples integrate with tty-box for professional terminal UI presentation and serve as practical references for developers building TUI applications.
 
+#### Self-Contained Example Architecture
+Examples have been completely refactored to use `bundler/inline` with inline gemfiles, making them truly self-contained. Each example now manages its own specific dependencies without affecting the main project's Gemfile. This architectural change eliminates the need for developers to modify project dependencies just to run examples and ensures examples remain functional regardless of the main project's development dependencies.
+
+#### Enhanced Ruby Compatibility and CI Infrastructure
+The project now enforces a minimum Ruby version of 3.2+ to ensure Zeitwerk compatibility and modern Ruby feature availability. The CI matrix has been expanded to test against Ruby 3.2, 3.3, and 3.4, providing comprehensive compatibility assurance across current Ruby versions while maintaining focus on supported versions.
+
 ## What's Fixed
 
 #### Hot Reloading and Dynamic Layout Integration
@@ -31,6 +37,12 @@ Fixed children_views joining behavior to eliminate unnecessary newlines between
 #### 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.
 
+#### Dependency Management and Development Environment
+Resolved dependency bloat by removing unnecessary development dependencies (ruby-lsp, logger, rbs, sorbet-runtime) from the main Gemfile. The ruby-lsp dependency was causing maintenance overhead without providing essential functionality for the framework itself. This cleanup reduces installation size and eliminates potential dependency conflicts for users integrating Milktea into their applications.
+
+#### CI Configuration and RuboCop Integration
+Fixed CI failures caused by RuboCop plugin configuration issues. Removed unnecessary RuboCop plugins (rubocop-rubycw, rubocop-on-rbs) that were added to resolve CI failures but weren't actually required for this project. The GitHub Actions now correctly use the project's .rubocop.yml configuration without additional plugin dependencies.
+
 ## Design Decisions
 
 #### Symbol-Based Dynamic Resolution Architecture
@@ -61,21 +73,59 @@ Reorganized test suites to properly reflect the architectural changes. Dynamic c
 
 **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.
 
+#### Ruby Version Requirements and Zeitwerk Compatibility
+**Context**: The framework uses Zeitwerk for autoloading, which has specific Ruby version requirements for optimal functionality and stability.
+
+**Decision**: Bump minimum Ruby version requirement from 3.1.0 to 3.2.0 across all project configurations.
+
+**Rationale**: Ruby 3.2+ provides better Zeitwerk integration, improved performance, and access to modern Ruby features that enhance framework capabilities. This decision ensures developers have access to the most stable and feature-complete Ruby environment while maintaining reasonable compatibility with current Ruby versions.
+
+#### Self-Contained Example Dependencies
+**Context**: Examples previously relied on development dependencies in the main Gemfile, creating coupling between framework dependencies and example requirements.
+
+**Decision**: Implement `bundler/inline` with inline gemfiles for all examples, making each example completely self-contained.
+
+**Rationale**: This architectural pattern eliminates dependency pollution in the main project while ensuring examples remain functional and runnable without project setup. It demonstrates best practices for Ruby gem development and provides better developer experience for users exploring framework capabilities.
+
+#### Development Dependency Minimization
+**Context**: The main Gemfile contained development tools (ruby-lsp, tty-box, listen) that aren't essential for framework functionality but were needed for specific development workflows.
+
+**Decision**: Remove non-essential development dependencies from the main Gemfile and move them to example-specific inline gemfiles where needed.
+
+**Rationale**: This reduces the installation footprint for users integrating Milktea into their applications and eliminates potential dependency conflicts. Essential testing and code quality tools remain in the main Gemfile, while convenience tools are available where specifically needed.
+
 ## 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.
+These changes significantly enhance the framework's flexibility and developer experience while establishing a more robust foundation for long-term development. 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.
+
+The self-contained example architecture dramatically improves developer onboarding by eliminating setup friction and dependency conflicts. New users can now explore framework capabilities without modifying their development environment or dealing with complex dependency resolution.
 
-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 Ruby 3.2+ requirement ensures developers have access to modern language features and optimal Zeitwerk performance, while the streamlined CI pipeline provides faster feedback and more reliable testing across supported Ruby versions.
+
+Developers can now build more maintainable TUI applications with less boilerplate code, greater architectural flexibility, and confidence in cross-version compatibility. 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
 
+### Core Framework
 - `lib/milktea/model.rb` - Added dynamic child resolution framework-wide
 - `lib/milktea/container.rb` - Added default view implementation, removed Container-specific resolution
+- `lib/milktea/renderer.rb` - Enhanced cursor management for cleaner terminal experience
+
+### Testing and Quality
 - `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
+- `.rubocop.yml` - Updated target Ruby version to 3.2, cleaned up plugin configuration
+
+### Examples and Documentation
+- `examples/container_layout.rb` - Interactive layout demo with inline dependencies
+- `examples/container_simple.rb` - Basic layout demonstration with inline dependencies
+- `examples/hot_reload_demo.rb` - Updated to use inline gemfile with listen dependency
+- `CLAUDE.md` - Updated Ruby version requirement documentation
+
+### Project Configuration
+- `Gemfile` - Removed development dependencies (ruby-lsp, tty-box, listen)
+- `Gemfile.lock` - Updated dependency tree reflecting removed packages
+- `milktea.gemspec` - Updated minimum Ruby version to 3.2.0
+- `.github/workflows/main.yml` - Updated CI matrix for Ruby 3.2, 3.3, 3.4 testing

data/docs/devlog/20250706.md

@@ -0,0 +1,118 @@
+# Development Log - 2025-07-06
+
+## What's New
+
+#### Message::Tick for Timing-Based UI Updates
+Introduced a new message type `Message::Tick` that provides timestamp information for time-dependent UI components. This enables developers to build animations, clocks, loading indicators, and other dynamic interfaces that update based on elapsed time. The Tick message includes a timestamp parameter (defaulting to `Time.now`) and integrates seamlessly into the Elm Architecture message flow.
+
+The implementation automatically generates tick messages in the main event loop at 60 FPS, providing consistent timing information to all components. Unlike `Message::None`, tick messages trigger rendering to ensure time-based components update their display properly. This design enables smooth animations and responsive time-dependent interfaces while maintaining the framework's predictable message handling.
+
+#### Enhanced Testing Convention Framework
+Established comprehensive testing guidelines that eliminate anti-patterns and enforce consistent test structure across the codebase. The new conventions prioritize testing public behavior over implementation details, making tests more maintainable and robust against refactoring.
+
+Key improvements include mandatory use of one-liner `it { ... }` syntax, proper `describe` blocks that reference actual methods, and `context` blocks that always start with "when" for conditional scenarios. These patterns create more readable and maintainable test suites while reducing cognitive overhead for developers working across different components.
+
+#### Milktea::Text Component with Dual Mode Architecture
+A comprehensive text display component has been introduced to the Milktea framework, providing developers with sophisticated text rendering capabilities for terminal interfaces. The Text component inherits from Container, enabling it to participate in the flexbox layout system while offering specialized text handling functionality.
+
+The component supports two distinct operational modes: wrap mode for traditional line-based text display and truncation mode for space-constrained scenarios. This dual approach addresses the fundamental challenge of text display in terminal interfaces where developers need both readable text flow and precise space management.
+
+#### Intelligent Text Wrapping and Overflow Management
+The wrap mode leverages the `strings` gem to provide Unicode-aware text wrapping that respects word boundaries and handles complex character sets including emojis and multi-byte characters. When text exceeds the available height, the component intelligently truncates at line boundaries while preserving content readability.
+
+The implementation handles edge cases in text measurement and display, including proper positioning with terminal cursor controls and accurate bounds calculation for nested layout scenarios. This ensures text components integrate seamlessly with the broader Container layout system.
+
+## What's Fixed
+
+#### Testing Anti-Pattern Elimination
+Systematically removed testing anti-patterns across all spec files, transforming 18+ multi-line tests into the preferred context + one-liner format. Fixed inappropriate use of `send(:private_method)` and `instance_variable_get(:@var)` that tested implementation details rather than public behavior.
+
+The refactoring maintained 100% test coverage while improving readability and maintainability. Tests now focus on observable outcomes through public APIs, making them more resilient to internal refactoring and clearer about component expectations. This establishes a sustainable pattern for future test development.
+
+#### Message::Tick Rendering Behavior
+Corrected the initial design where Tick messages were excluded from triggering renders. The fix ensures that time-dependent components can update their display when tick events occur, enabling proper animation and dynamic UI behavior. This change resolved the fundamental issue that would have prevented time-based interfaces from working correctly.
+
+The solution involved updating the runtime message handling to treat Tick messages like other render-triggering events while maintaining the optimization that `Message::None` doesn't cause unnecessary redraws. This balanced approach provides the timing functionality developers need while preserving performance for static content.
+
+#### Text Positioning and Bounds Integration
+Resolved initial implementation issues where text positioning used hardcoded coordinates instead of respecting the Container bounds system. The fix ensures text components correctly integrate with flexbox layouts and maintain proper positioning when used within complex Container hierarchies.
+
+The solution involved implementing proper cursor positioning that respects both absolute coordinates (x, y) and relative positioning within allocated Container space. This enables text components to work correctly in nested layout scenarios and dynamic resizing situations.
+
+#### Terminal Screen Clearing Behavior
+Fixed the renderer's screen clearing behavior to use `clear_screen_down` instead of `clear_screen`, preventing the terminal from clearing the entire scrollback history. This change improves user experience by preserving terminal history while still properly clearing the application's display area.
+
+The fix addresses the common terminal application issue where applications aggressively clear the entire screen, causing users to lose their command history and previous terminal output. The new approach only clears from the cursor position downward, maintaining the user's terminal session context while ensuring clean application rendering.
+
+## Design Decisions
+
+#### Testing Architecture: Public API Focus
+**Context**: The codebase had accumulated testing patterns that relied on accessing private methods and instance variables, creating brittle tests coupled to implementation details.
+
+**Decision**: Mandate testing only through public interfaces and observable behavior, with strict prohibition of `send(:private_method)` and `instance_variable_get(:@var)` patterns.
+
+**Rationale**: Tests should verify what components do, not how they do it internally. This approach makes tests more maintainable during refactoring, clearer about component contracts, and focused on user-observable behavior. The stricter guidelines prevent future accumulation of implementation-dependent tests while establishing sustainable patterns for the growing codebase.
+
+#### Message::Tick Rendering Strategy
+**Context**: Time-based UI components need regular updates to display current state, but the framework optimizes performance by avoiding unnecessary renders.
+
+**Decision**: Enable Tick messages to trigger rendering while maintaining the optimization that `Message::None` events don't cause redraws.
+
+**Rationale**: Animations, clocks, and loading indicators require visual updates when time progresses, even if no user interaction occurs. Excluding Tick from rendering would break time-dependent interfaces. The selective approach preserves performance optimizations for static content while enabling dynamic time-based behavior where needed. This balances responsiveness with resource efficiency.
+
+#### Testing Convention Enforcement
+**Context**: As the codebase grows, inconsistent testing patterns create maintenance overhead and cognitive load for developers working across different components.
+
+**Decision**: Enforce standardized test structure with one-liner syntax, method-referencing describe blocks, and "when"-prefixed context blocks.
+
+**Rationale**: Consistent patterns reduce the mental overhead of understanding tests and make it easier to identify what functionality is being verified. The one-liner preference encourages clear, focused test cases that verify single behaviors. Standardization enables developers to quickly navigate and understand test intent across the entire framework, improving development velocity and reducing onboarding time.
+
+#### Dual Mode Architecture for Text Display
+**Context**: Terminal interfaces require different text handling strategies depending on use case - some scenarios need readable text flow while others prioritize space efficiency and content density.
+
+**Decision**: Implement a mode-based architecture with `wrap: false` (truncation) as default and `wrap: true` for traditional wrapping behavior.
+
+**Rationale**: The truncation mode addresses the common terminal interface challenge of displaying maximum information in limited space, making it the more universally applicable default. The wrap mode preserves traditional text display expectations for content-focused scenarios. This approach provides developers with explicit control over text behavior while establishing sensible defaults for most TUI applications.
+
+#### Documentation Integration Strategy
+**Context**: Testing conventions needed to be preserved and communicated to prevent regression to anti-pattern usage.
+
+**Decision**: Update CLAUDE.md with comprehensive anti-pattern prevention guidelines and reorganize existing rules for clarity.
+
+**Rationale**: Embedding conventions in the project documentation ensures they persist beyond the current development session and guide future contributors. The prominent placement of anti-pattern warnings helps developers avoid common mistakes while the reorganized structure makes the guidelines more discoverable and actionable.
+
+## Impact
+
+The Message::Tick implementation opens up entirely new categories of TUI applications that Milktea can support, including games, monitoring dashboards, and interactive animations. Time-based interfaces are now first-class citizens in the framework, with built-in support for smooth updates and consistent timing.
+
+The testing convention improvements establish a sustainable foundation for the project's growth. With clear guidelines preventing anti-patterns and encouraging consistent structure, the codebase can scale without accumulating technical debt in the test suite. Future contributors have clear guidance for writing maintainable tests that focus on behavior rather than implementation.
+
+The Text component introduction significantly expands Milktea's capabilities for building sophisticated terminal interfaces. Developers can now create information-dense applications with professional text rendering while maintaining the framework's layout system integration and hot reloading capabilities.
+
+The combined effect of these improvements positions Milktea as a more mature and capable TUI framework. The timing system enables dynamic interfaces, the testing framework ensures long-term maintainability, and the text component provides essential UI building blocks. These foundational improvements support more ambitious application development while maintaining the framework's core strengths.
+
+## Files Modified
+
+### Core Framework
+- `lib/milktea/message.rb` - Added timestamp parameter to Message::Tick for timing information
+- `lib/milktea/program.rb` - Integrated tick message generation into main event loop
+- `lib/milktea/runtime.rb` - Simplified side effect handling and enabled Tick rendering
+- `lib/milktea/text.rb` - Complete Text component implementation with dual-mode architecture
+- `lib/milktea/renderer.rb` - Fixed screen clearing behavior to preserve terminal history
+- `milktea.gemspec` - Added strings gem dependency for text manipulation capabilities
+
+### Testing Framework
+- `spec/milktea_spec.rb` - Converted multi-line tests to one-liner format
+- `spec/milktea/application_spec.rb` - Transformed 8 multi-line tests to context + one-liner pattern
+- `spec/milktea/program_spec.rb` - Fixed 4 multi-line tests and removed anti-patterns
+- `spec/milktea/renderer_spec.rb` - Converted multi-line test to one-liner
+- `spec/milktea/runtime_spec.rb` - Fixed instance variable usage and multi-line tests
+- `spec/milktea/message_spec.rb` - Added comprehensive Message::Tick test coverage
+
+### Documentation and Examples
+- `CLAUDE.md` - Enhanced RSpec testing guidelines with anti-pattern prevention
+- `examples/tick_example.rb` - Demonstration of timing-based animation usage
+- `examples/text_demo.rb` - Interactive demonstration of text component modes
+
+### Dependencies
+- `Gemfile.lock` - Updated with strings gem and its dependencies for Unicode text handling

data/examples/container_layout.rb

@@ -1,7 +1,14 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "milktea", path: "../"
+  gem "tty-box", "~> 0.7.0"
+end
+
 require "milktea"
 require "tty-box"
 

data/examples/container_simple.rb

@@ -1,7 +1,14 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "milktea", path: "../"
+  gem "tty-box", "~> 0.7.0"
+end
+
 require "milktea"
 require "tty-box"
 

data/examples/hot_reload_demo.rb

@@ -1,7 +1,14 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require "bundler/setup"
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "milktea", path: "../"
+  gem "listen"
+end
+
 require "milktea"
 
 # Hot Reload Demo using Milktea::Application - Simplified setup

data/examples/text_demo.rb

@@ -0,0 +1,136 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "milktea"
+
+# TextDemo model demonstrating Text component usage
+class TextDemo < Milktea::Container
+  direction :column
+  child :header, flex: 1
+  child :short_text, flex: 2
+  child :long_text, flex: 3
+  child :truncated_text, flex: 2
+  child :unicode_text, flex: 2
+  child :footer, flex: 1
+
+  def header
+    HeaderText
+  end
+
+  def short_text
+    ShortText
+  end
+
+  def long_text
+    LongText
+  end
+
+  def truncated_text
+    TruncatedText
+  end
+
+  def unicode_text
+    UnicodeText
+  end
+
+  def footer
+    FooterText
+  end
+
+  def update(message)
+    case message
+    when Milktea::Message::KeyPress
+      return [self, Milktea::Message::Exit.new] if ["q", "ctrl+c"].include?(message.key)
+    When Milktea::Message::Resize
+      return [with, Milktea::Message::None.new]
+    end
+
+    [self, Milktea::Message::None.new]
+  end
+end
+
+# Header text component
+class HeaderText < Milktea::Text
+  private
+
+  def default_state
+    {
+      content: "Milktea Text Component Demo\nPress 'q' to quit",
+      wrap: true
+    }
+  end
+end
+
+# Short text that fits within bounds
+class ShortText < Milktea::Text
+  private
+
+  def default_state
+    {
+      content: "This is a short text that fits comfortably within the bounds. " \
+               "It demonstrates basic text rendering."
+    }
+  end
+end
+
+# Long text that requires wrapping and truncation
+class LongText < Milktea::Text
+  private
+
+  def default_state
+    {
+      content: "This is a much longer text that will demonstrate the wrapping " \
+               "and truncation capabilities of the Text component. When text " \
+               "is too long to fit within the specified width, it will " \
+               "automatically wrap to the next line. If there are too many " \
+               "lines to fit within the height bounds, the last visible line " \
+               "will be truncated with an ellipsis. This ensures that text " \
+               "always stays within its designated area and doesn't overflow " \
+               "into other components. The wrapping is word-aware, so it won't " \
+               "break words in the middle unless absolutely necessary.",
+      wrap: true
+    }
+  end
+end
+
+# Truncated text demonstrating the new truncation mode
+class TruncatedText < Milktea::Text
+  private
+
+  def default_state
+    {
+      content: "This demonstrates the new truncation mode (wrap: false). " \
+               "Newlines are removed and text is truncated to fit within " \
+               "width * height characters. Custom trailing can be set.",
+      trailing: "..."
+    }
+  end
+end
+
+# Unicode and emoji text
+class UnicodeText < Milktea::Text
+  private
+
+  def default_state
+    {
+      content: "Unicode support: 你好世界 🌍🌎🌏\n" \
+               "Japanese: ラドクリフ、マラソン五輪代表\n" \
+               "Emoji: 🚀 🎉 🔥 ✨ 💻 📱"
+    }
+  end
+end
+
+# Footer text
+class FooterText < Milktea::Text
+  private
+
+  def default_state
+    { content: "Text components handle wrapping, truncation, and Unicode!" }
+  end
+end
+
+# Create and run the program
+model = TextDemo.new
+program = Milktea::Program.new(model)
+program.run

data/examples/tick_example.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/milktea"
+
+# Example model that uses Tick messages for animations
+class TickModel < Milktea::Model
+  def view
+    elapsed = last_tick ? Time.now - last_tick : 0
+    dots = "." * ((elapsed * 2).to_i % 4)
+
+    <<~VIEW
+      ╭─────────────────────────────────────────────────────────╮
+      │                    Tick Example                         │
+      ├─────────────────────────────────────────────────────────┤
+      │                                                         │
+      │  Loading#{dots.ljust(3)}                                  │
+      │                                                         │
+      │  Last tick: #{last_tick&.strftime("%H:%M:%S.%L") || "none"}         │
+      │  Elapsed: #{elapsed.round(3)}s                            │
+      │                                                         │
+      │  Press 'q' to quit                                      │
+      │                                                         │
+      ╰─────────────────────────────────────────────────────────╯
+    VIEW
+  end
+
+  def update(message)
+    case message
+    when Milktea::Message::Tick
+      # Track the tick timestamp - this demonstrates that tick messages
+      # provide timing information that models can use for animations
+      [with(last_tick: message.timestamp), Milktea::Message::None.new]
+    when Milktea::Message::KeyPress
+      if message.key == "q"
+        [self, Milktea::Message::Exit.new]
+      else
+        [self, Milktea::Message::None.new]
+      end
+    else
+      [self, Milktea::Message::None.new]
+    end
+  end
+
+  private
+
+  def default_state
+    { last_tick: nil }
+  end
+
+  def last_tick
+    state[:last_tick]
+  end
+end
+
+# Configure Milktea
+Milktea.configure do |config|
+  config.hot_reloading = false
+end
+
+# Create and run the tick demonstration
+program = Milktea::Program.new(TickModel.new)
+program.run

data/lib/milktea/message.rb

@@ -9,8 +9,12 @@ module Milktea
     # Message to exit the program
     Exit = Data.define
 
-    # Timer tick message
-    Tick = Data.define
+    # Timer tick message with timestamp
+    Tick = Data.define(:timestamp) do
+      def initialize(timestamp: Time.now)
+        super
+      end
+    end
 
     # Keyboard event message
     KeyPress = Data.define(:key, :value, :ctrl, :alt, :shift) do

data/lib/milktea/program.rb

@@ -39,6 +39,7 @@ module Milktea
 
     def process_messages
       check_resize
+      enqueue(Message::Tick.new)
       @model = tick(@model)
       render(@model) if render?
     end

data/lib/milktea/renderer.rb

@@ -22,13 +22,13 @@ module Milktea
 
     def setup_screen
       @output.print @cursor.hide
-      @output.print @cursor.clear_screen
+      @output.print @cursor.clear_screen_down
       @output.print @cursor.move_to(0, 0)
       @output.flush
     end
 
     def restore_screen
-      @output.print @cursor.clear_screen
+      @output.print @cursor.clear_screen_down
       @output.print @cursor.show
       @output.flush
     end

data/lib/milktea/runtime.rb

@@ -53,18 +53,10 @@ module Milktea
 
     def execute_side_effect(side_effect)
       case side_effect
-      when Message::None
-        # Do nothing
       when Message::Exit
         stop
       when Message::Batch
         side_effect.messages.each { |msg| enqueue(msg) }
-      when Message::Reload
-        # Hot reload handled automatically by Zeitwerk
-        # No additional action needed
-      when Message::Resize
-        # Terminal resize detected
-        # No additional action needed at this level
       end
     end
   end

data/lib/milktea/text.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "strings"
+require "tty-cursor"
+
+module Milktea
+  # Text component for displaying text content with wrapping and truncation
+  class Text < Container
+    def view
+      return "" if content.empty?
+      return render(truncated_lines) if state[:wrap]
+
+      render_truncated
+    end
+
+    private
+
+    def render(lines)
+      lines.map.with_index do |line, index|
+        TTY::Cursor.move_to(bounds.x, bounds.y + index) + line
+      end.join
+    end
+
+    def render_truncated
+      cleaned_content = content.gsub("\n", "")
+      max_length = bounds.width * bounds.height
+      truncated_content = Strings.truncate(cleaned_content, max_length, trailing: state[:trailing])
+
+      TTY::Cursor.move_to(bounds.x, bounds.y) + truncated_content
+    end
+
+    def truncated_lines
+      lines = wrap_content
+      return lines unless lines.length > bounds.height
+
+      lines.take(bounds.height)
+    end
+
+    def wrap_content
+      Strings.wrap(content, bounds.width).split("\n")
+    end
+
+    def content
+      state[:content] || ""
+    end
+
+    def default_state
+      { content: "", wrap: false, trailing: "…" }.freeze
+    end
+  end
+end

data/lib/milktea/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Milktea
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/release-please-config.json

@@ -0,0 +1,10 @@
+{
+  "release-type": "ruby",
+  "packages": {
+    ".": {
+      "package-name": "milktea",
+      "include-component-in-tag": false,
+      "release-type": "ruby"
+    }
+  }
+}

metadata

@@ -1,15 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: milktea
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Aotokitsuruya
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-05 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: strings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: timers
   requirement: !ruby/object:Gem::Requirement
@@ -89,9 +102,11 @@ extra_rdoc_files: []
 files:
 - ".claude/commands/devlog.md"
 - ".claude/settings.json"
+- ".release-please-manifest.json"
 - ".rspec"
 - ".rubocop.yml"
 - ARCHITECTURE.md
+- CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
 - README.md
@@ -100,6 +115,7 @@ files:
 - docs/devlog/20250704-2.md
 - docs/devlog/20250704.md
 - docs/devlog/20250705.md
+- docs/devlog/20250706.md
 - examples/container_layout.rb
 - examples/container_simple.rb
 - examples/counter.rb
@@ -108,6 +124,8 @@ files:
 - examples/hot_reload_demo/models/demo_model.rb
 - examples/hot_reload_demo/models/status_model.rb
 - examples/simple.rb
+- examples/text_demo.rb
+- examples/tick_example.rb
 - lib/milktea.rb
 - lib/milktea/application.rb
 - lib/milktea/bounds.rb
@@ -119,7 +137,9 @@ files:
 - lib/milktea/program.rb
 - lib/milktea/renderer.rb
 - lib/milktea/runtime.rb
+- lib/milktea/text.rb
 - lib/milktea/version.rb
+- release-please-config.json
 - sig/milktea.rbs
 homepage: https://github.com/elct9620/milktea
 licenses:
@@ -129,7 +149,6 @@ metadata:
   source_code_uri: https://github.com/elct9620/milktea
   changelog_uri: https://github.com/elct9620/milktea/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -137,15 +156,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: The TUI framework for Ruby, inspired by the bubbletea framework for Go.
 test_files: []