ratatui_ruby-tea 0.3.1 → 0.4.0

data/doc/contributors/WIP/decomposition_strategies_analysis.md

@@ -0,0 +1,258 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# MVU/TEA Decomposition Strategies Analysis
+
+## Decomposition Style Categories
+
+### FRACTAL Style (Recursive MVU Triads)
+Each component/module is a complete MVU unit with its own Model, Update, and View. Components nest recursively, parent delegates to children. Child components are self-contained and can be composed.
+
+### SLICE Style (Domain-Segregated State)
+State is partitioned by domain/feature, but update/view logic may be centralized or cross-cutting. Each slice typically has Model + Update, with views potentially pulling from multiple slices.
+
+### HYBRID
+Combines both patterns - some aspects use fractal composition, others use slice partitioning.
+
+### NO DECOMPOSITION
+Framework does not provide explicit support for breaking down complex applications.
+
+---
+
+## Framework Categorization
+
+### 🟢 FRACTAL Decomposition
+
+#### **1. Elm (Original TEA)**
+- **Style**: Fractal (historically, with evolution)
+- **Terminology**: "Nested TEA", "Modules", "Translator Pattern" / "OutMsg Pattern"
+- **Details**:
+  - Originally promoted recursive MVU triads (child modules with own Model/Msg/update/view)
+  - Parent uses `Html.map` and `Cmd.map` to transform child messages
+  - **Evolution**: Elm 0.19 de-emphasized deep nesting due to boilerplate
+  - Current recommendation: Shallow nesting, reusable view functions over deep component trees
+  - "Translator Pattern" for child-to-parent communication (child returns OutMsg for parent)
+- **Composition**: Yes, via `Html.map` / `Cmd.map` and OutMsg pattern
+
+#### **2. Bubble Tea (Go)**
+- **Style**: Fractal
+- **Terminology**: "Tree of Models", "Nested Models", "Child Components"
+- **Details**:
+  - Each component has its own `Model` struct with `Init()`, `Update()`, `View()` methods
+  - Parent embeds child models as fields
+  - Parent routes messages to children based on state (often using session/state enum)
+  - View composition combines child view strings
+  - Uses "Bubbles" library for pre-built components
+- **Composition**: Yes, explicit message routing in parent's Update
+
+#### **3. Iced (Rust)**
+- **Style**: Fractal
+- **Terminology**: "Nested components", "Message routing", "`.map()` transformation"
+- **Details**:
+  - Each component can have State + Message enum + update + view
+  - Parent's Message enum wraps child Message types
+  - Uses `.map()` to transform child messages/commands/elements to parent context
+  - `Subscription::batch()` for combining child subscriptions
+  - Note: `Component` trait deprecated in 0.13+ (violated single source of truth)
+- **Composition**: Yes, via `.map()` transformation
+
+#### **4. Elmish (F#/Fable)**
+- **Style**: Fractal
+- **Terminology**: "Nested TEA", "Child modules"
+- **Details**:
+  - Direct port of Elm Architecture to F#
+  - Each module has `Model * Cmd<Msg>` init, `update`, `view`
+  - Parent maps child messages and commands
+  - Used with React for rendering
+- **Composition**: Yes, same as Elm
+
+#### **5. Hyperapp (JavaScript)**
+- **Style**: Fractal-lite
+- **Terminology**: No specific term (minimal framework)
+- **Details**:
+  - Unified global state, but can be structured recursively
+  - Effects can be nested in init array `[state, effect1, effect2]`
+  - Very lightweight (1KB), minimal opinions
+- **Composition**: Limited, more state-tree focused than component-focused
+
+---
+
+### 🔵 SLICE Decomposition
+
+#### **6. Redux (JavaScript/React)**
+- **Style**: PURE SLICE
+- **Terminology**: "Slices", "Reducers", "State combination"
+- **Details**:
+  - `createSlice` creates domain-specific state + reducers
+  - Each slice has `name`, `initialState`, `reducers`
+  - Slices combined via `configureStore({ reducer: { user: userSlice, posts: postsSlice } })`
+  - Views (React components) can access any slice via selectors
+  - **NOT strictly MVU** (no built-in effects), but pattern is similar
+- **Composition**: Yes, via `combineReducers` / `configureStore`
+- **Notable**: Slices have reducers, but no dedicated views - views are separate React components
+
+---
+
+### 🟡 HYBRID Decomposition
+
+#### **7. TCA (Swift - The Composable Architecture)**
+- **Style**: HYBRID (Fractal-ish with powerful scoping)
+- **Terminology**: "Reducers", "Scoping", "Pullback", "Child features", "Composition"
+- **Details**:
+  - Each "feature" is a `Reducer` with nested `State` and `Action` types
+  - Uses `.scope()` to focus parent state/actions on child domain
+  - Can compose reducers horizontally (siblings) or vertically (parent-child)
+  - **More sophisticated than pure fractal**: dependency injection, effects management, testing tools
+  - Parent doesn't just delegate - uses lenses/scoping to project state
+- **Composition**: Yes, via `Reducer` composition operators and scoping
+
+#### **8. Flutter Bloc**
+- **Style**: HYBRID
+- **Terminology**: "BloC per feature/screen", "Nested BloCs", "BlocProvider", "MultiBlocProvider"
+- **Details**:
+  - Recommended pattern: one Bloc/Cubit per screen or feature
+  - BloCs can be nested via `BlocProvider` (dependency injection)
+  - `MultiBlocProvider` for multiple BloCs in widget tree
+  - **Not pure fractal**: BloCs don't nest MVU triads, they're separate event-driven state machines
+  - **Not pure slice**: Each BloC is feature-specific, views are Flutter widgets
+- **Composition**: Yes, via provider pattern (DI), not via direct delegation
+
+#### **9. Android MVI (Kotlin)**
+- **Style**: HYBRID
+- **Terminology**: "ViewModel per feature", "StateFlow", "Intent channels"
+- **Details**:
+  - Each ViewModel manages feature state via `StateFlow`
+  - Intents sent to ViewModel via `SharedFlow` or `Channel`
+  - ViewModels can be scoped to fragments/activities
+  - **Not pure fractal**: ViewModels are independent state machines, not nested MVU
+  - **Not pure slice**: Each ViewModel is feature-bound
+- **Composition**: Limited, mostly via ViewModel scoping and shared state
+
+#### **10. Meiosis (JavaScript)**
+- **Style**: HYBRID
+- **Terminology**: "Services", "Nested components" (optional), "Initial model composition"
+- **Details**:
+  - Flexible pattern, not opinionated
+  - Can compose via `initialModel` merging
+  - "meiosis-setup" library helps with nested components and services
+  - View-library agnostic
+- **Composition**: Yes, but flexible/manual
+
+---
+
+### ⚫ NO EXPLICIT DECOMPOSITION
+
+#### **11. SAM Pattern (JavaScript)**
+- **Style**: No explicit decomposition support
+- **Terminology**: N/A
+- **Details**:
+  - Single Model (state tree)
+  - Single State Representation function
+  - Actions propose mutations
+  - Based on TLA+ formalism
+  - **Philosophical**: Focused on temporal logic and correctness, less on composition
+- **Composition**: Not a focus
+
+---
+
+### 🟣 OTHER / MINIMAL DOCUMENTATION
+
+#### **12-16. .NET Implementations**
+- **Fabulous (F#/MAUI)**: Likely **FRACTAL** (F# MVU port, similar to Elmish)
+- **BlazorMVU (C#/Blazor)**: Likely **FRACTAL** (Elm-inspired)
+- **MauiReactor (C#/MAUI)**: Likely **FRACTAL** (MVU for .NET MAUI)
+- **MVUX (.NET/Uno)**: **HYBRID** (Model-View-Update eXtended, data binding focus)
+- **ngx-mvu (Angular)**: Likely **HYBRID** (Angular + MVU concepts)
+
+---
+
+## Summary Table
+
+| Framework | Style | Terminology |
+|-----------|-------|-------------|
+| **Elm** | Fractal (evolved) | Nested TEA, Modules, Translator/OutMsg Pattern |
+| **Bubble Tea** | Fractal | Tree of Models, Nested Models, Child Components |
+| **Iced** | Fractal | Nested components, Message routing, `.map()` |
+| **Elmish** | Fractal | Nested TEA, Child modules |
+| **Hyperapp** | Fractal-lite | (minimal framework, no specific term) |
+| **Redux** | **SLICE** | **Slices**, Reducers, State combination |
+| **TCA** | **HYBRID** | Reducers, Scoping, Pullback, Child features |
+| **Flutter Bloc** | **HYBRID** | BloC per feature, Nested BloCs, Providers |
+| **Android MVI** | **HYBRID** | ViewModel per feature, StateFlow, Intents |
+| **Meiosis** | **HYBRID** | Services, Nested components (optional) |
+| **SAM** | None | N/A (TLA+ formalism focus) |
+| Fabulous | Fractal (likely) | (F# MVU) |
+| BlazorMVU | Fractal (likely) | (Elm-inspired) |
+| MauiReactor | Fractal (likely) | (MVU for MAUI) |
+| MVUX | Hybrid (likely) | (Extended MVU, data binding) |
+| ngx-mvu | Hybrid (likely) | (Angular + MVU) |
+
+---
+
+## Key Insights
+
+### Fractal Pattern Characteristics:
+1. ✅ **Complete MVU triads** for each component
+2. ✅ **Recursive composition** (components contain components)
+3. ✅ **Message delegation** (parent forwards to child)
+4. ✅ **View composition** (parent combines child views)
+5. ❌ **High boilerplate** (Elm community moved away from deep nesting)
+
+**Examples**: Elm (original), Bubble Tea, Iced, Elmish
+
+### Slice Pattern Characteristics:
+1. ✅ **Domain-partitioned state** (slices by feature)
+2. ✅ **Flat composition** (slices are siblings, not nested)
+3. ✅ **Centralized view** (views pull from multiple slices)
+4. ✅ **Low boilerplate** (slices are simple)
+5. ❌ **No per-slice views** (views are separate layer)
+
+**Example**: Redux (pure slice pattern)
+
+### Hybrid Pattern Characteristics:
+1. ✅ **Feature-scoped state** (like slices)
+2. ✅ **Independent update logic** (like fractal)
+3. ✅ **Flexible composition** (dependency injection, scoping)
+4. ✅ **Reduced boilerplate** (compared to pure fractal)
+5. ⚠️ **Framework-specific** (each does it differently)
+
+**Examples**: TCA (scoping/pullback), Flutter Bloc (providers), Android MVI (ViewModels)
+
+---
+
+## Where Does RatatuiRuby-TEA Fit?
+
+### Current State: **FRACTAL**
+- Fragments have `Model`, `INITIAL`, `UPDATE`, `VIEW`
+- Parents delegate to children via `Tea.delegate`
+- Message routing via `Tea.route`
+- Router DSL for declarative composition
+
+### With Init Callable: **ENHANCED FRACTAL**
+Your `Init` proposal strengthens the fractal pattern by:
+1. ✅ Enabling **parameterized initialization** (like Iced's `flags`)
+2. ✅ Supporting **initial commands** (like Elm's `(Model, Cmd)`)
+3. ✅ Allowing **parent-to-child props** (React-style, but fractal)
+4. ✅ Maintaining **complete MVU triads** (Model, Init, Update, View)
+
+This is **closer to Iced** (Rust) than Elm, as Iced explicitly supports flags for initialization and has evolved beyond Elm's original design.
+
+---
+
+## Recommendation
+
+RatatuiRuby-TEA should **embrace the modern fractal pattern** with:
+- **Complete MVU triads per fragment**: `Model`, `Init`, `Update`, `View`
+- **Parameterized initialization**: `Init` accepts flags/props
+- **Explicit composition**: Parent calls child `Init`, routes messages, composes views
+
+This positions RatatuiRuby-TEA as:
+- **Functional** (like Elm/Elmish/Iced)
+- **Composable** (fractal pattern)
+- **Modern** (Init callable, not static constants)
+- **Parameterizable** (flags/props support)
+
+**NOT** like Redux (slice pattern) or TCA/Bloc (OOP/hybrid patterns).

data/doc/contributors/WIP/implementation_plan.md

@@ -0,0 +1,405 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Init Callable Implementation Plan
+
+## Problem Statement
+
+The current codebase uses **three different names** for initial state:
+- `MODEL` (simple examples: README, verify_readme_usage)
+- `INITIAL` (fractal fragments: dashboard examples)  
+- `init:` (runtime parameter with different semantics)
+
+The planned v0.4.0 transition (`INITIAL` → `Initial` PascalCase) would create visual collision with `Model`, where both look like type names despite different purposes (type vs instance).
+
+**Critical Finding**: Research of 15+ MVU/TEA frameworks shows **zero** use static constants for initialization. All use callables/functions.
+
+## Solution: Init Callable
+
+Replace static `INITIAL`/`MODEL` constants with `Init` callable that:
+1. Returns `[model, command]` tuple (or DWIM variants)
+2. Accepts flags/props for parameterization
+3. Enables parent-to-child initialization data flow
+4. Supports initial command dispatch alongside state
+
+## Proposed Changes
+
+### Core API
+
+#### Fragment Structure (v0.4.0)
+```ruby
+module MyFragment
+  Model = Data.define(:field1, :field2)
+  
+  # NEW: Init callable (optional, defaults to Model.new)
+  Init = ->(flags_hash = {}) do
+    model = Model.new(...)
+    command = some_initial_command  # or nil
+    [model, command]
+  end
+  
+  Update = ->(message, model) { ... }
+  View = ->(model, tui) { ... }
+end
+```
+
+#### DWIM Return Values
+```ruby
+# All valid return formats:
+Init = -> { Model.new(...) }                    # Just model
+Init = -> { [Model.new(...), nil] }             # Explicit tuple, no command
+Init = -> { [Model.new(...), some_cmd] }        # With command
+Init = -> { Command.exit }                      # Just command (edge case)
+```
+
+#### Normalization Helper
+```ruby
+module Tea
+  # Normalize Init return to [model, command] tuple
+  # Uses DWIM logic like Update (tea_command? detection)
+  def self.normalize_init(result)
+    case result
+    when Command then [nil, result]           # Just command
+    in [model, command] then [model, command] # Already tuple
+    else
+      if result.respond_to?(:tea_command?) && result.tea_command?
+        [nil, result]                         # Command without array wrapper
+      else
+        [result, nil]                         # Just model
+      end
+    end
+  end
+end
+```
+
+---
+
+### Fractal Composition
+
+#### Parent Init Calls Child Init
+```ruby
+module Dashboard
+  Model = Data.define(:stats, :network, :theme)
+  
+  Init = ->(theme: :dark, env: {}) do
+    # Call child Inits with props
+    stats_model, stats_cmd = StatsPanel::Init.(theme: theme)
+    network_model, network_cmd = NetworkPanel::Init.(theme: theme)
+    
+    model = Model.new(
+      stats: stats_model,
+      network: network_model,
+      theme: theme
+    )
+    
+    command = Command.batch(
+      Tea.route(stats_cmd, :stats),
+      Tea.route(network_cmd, :network)
+    )
+    
+    [model, command]
+  end
+  
+  # View composition - UNCHANGED (still manual)
+  View = ->(model, tui) do
+    tui.vertical_layout(
+      children: [
+        StatsPanel::View.call(model.stats, tui),
+        NetworkPanel::View.call(model.network, tui)
+      ]
+    )
+  end
+  
+  # Update routing - UNCHANGED (Router DSL)
+  include Tea::Router
+  route :stats, to: StatsPanel
+  route :network, to: NetworkPanel
+  Update = from_router
+end
+```
+
+**Key Point**: Only `Update` uses Router DSL. `Init` and `View` remain explicit/manual composition.
+
+---
+
+### Runtime Integration
+
+#### Current API (Backward Compatible)
+```ruby
+# Still works (old style)
+Tea.run(
+  model: MyApp::INITIAL,
+  view: MyApp::VIEW,
+  update: MyApp::UPDATE
+)
+```
+
+#### New API (Fragment-First)
+```ruby
+# New style (preferred)
+Tea.run(
+  fragment: MyApp,
+  argv: ARGV,
+  env: ENV
+)
+
+# Equivalent to:
+# model, init_cmd = MyApp::Init.(argv: ARGV, env: ENV)
+# Tea.run(model: model, view: MyApp::View, update: MyApp::Update, init: init_cmd)
+```
+
+#### Runtime Implementation
+```ruby
+module RatatuiRuby::Tea
+  def self.run(fragment: nil, model: nil, view: nil, update: nil, argv: [], env: {}, init: nil)
+    if fragment
+      # New style: fragment-first
+      init_callable = fragment.const_defined?(:Init) ? fragment::Init : -> { fragment::Model.new }
+      init_result = init_callable.call(argv: argv, env: env)
+      model, init_cmd = normalize_init(init_result)
+      view = fragment::View
+      update = fragment::Update
+      init = init_cmd  # Override init param with Init-generated command
+    else
+      # Old style: explicit parameters (backward compatible)
+      # model, view, update, init already provided
+    end
+    
+    Runtime.run(model: model, view: view, update: update, init: init)
+  end
+end
+```
+
+---
+
+## Migration Strategy
+
+### v0.4.0: Breaking Change (Zero Users, Zero Cruft)
+
+Since the project has **zero external users**, we will make this a **breaking change in v0.4.0**:
+
+- ✅ `Init` callable is the **only** way to define initial state
+- ❌ `INITIAL` and `MODEL` constants are **removed** (no backward compatibility)
+- ✅ `Init` is **optional** (defaults to `-> { Model.new }` if not defined)
+- ✅ All examples and documentation use `Init` pattern
+- ✅ Clean slate, no migration debt
+
+**Rationale**: Adding backward compatibility for a non-existent user base creates unnecessary code complexity and testing burden. Break now while we can.
+
+---
+
+## Implementation Checklist
+
+### Core Implementation
+- [ ] **`Tea.normalize_init` helper**
+  - [ ] Implement DWIM logic with `tea_command?` detection
+  - [ ] Handle all return formats: model, command, `[model, cmd]`
+  - [ ] Tests for all DWIM variants
+  
+- [ ] **Runtime changes**
+  - [ ] Add `fragment:`, `argv:`, `env:` parameters to `Tea.run`
+  - [ ] Auto-call `fragment::Init` when `fragment:` provided
+  - [ ] Default `Init` to `-> { Model.new }` if not defined
+  - [ ] Maintain backward compatibility with `model:`/`view:`/`update:` params
+  - [ ] Tests for both old and new API styles
+
+### Example Migrations
+- [ ] **Simple example** (verify_readme_usage)
+  - [ ] Replace `MODEL` constant with `Init` callable
+  - [ ] Update README code samples
+  - [ ] Verify tests still pass
+  
+- [ ] **Fractal example** (app_fractal_dashboard)
+  - [ ] Convert all fragment `INITIAL` to `Init`
+  - [ ] Update parent Init to call child Inits with props
+  - [ ] Compose initial commands with `Command.batch`
+  - [ ] Verify all dashboard variants (base, router, manual, helpers) work
+
+### Documentation
+- [ ] **Update AGENTS.md**
+  - [ ] Change Fragment definition to use `Init` instead of `INITIAL`
+  - [ ] Update terminology section
+  
+- [ ] **Create concept documentation files**
+  - [ ] `doc/init.md` (full documentation)
+    - [ ] Follow documentation style guide (Alexandrian Context-Problem-Solution)
+    - [ ] Explain what Init is and why it exists (vs static constants)
+    - [ ] Document Init at root level (runtime integration)
+    - [ ] Document Init at non-root level (fractal composition)
+    - [ ] Show parameterization with flags/props
+    - [ ] Document DWIM return values
+    - [ ] Show Tea.normalize_init usage
+    - [ ] Multiple complete examples (simple, fractal, with commands)
+    - [ ] Link to related concepts (Fragment, Model, Update, Command)
+  - [ ] Create stubs for concept doc series (H1 + "TODO" only):
+    - [ ] `doc/fragment.md`
+    - [ ] `doc/model.md`
+    - [ ] `doc/view.md`
+    - [ ] `doc/update.md`
+    - [ ] `doc/command.md`
+    - [ ] `doc/message.md`
+    - [ ] `doc/output.md`
+  
+- [ ] **Update design_for_v0.4.0.md**
+  - [ ] Add Init Callable section
+  - [ ] Document DWIM behavior
+  - [ ] Document `Tea.normalize_init` helper
+  - [ ] Add footnote on Iced pattern inspiration
+  - [ ] Add footnote on OutMsg pattern (future consideration)
+  
+- [ ] **Create migration guide**
+  - [ ] Before/after examples
+  - [ ] Deprecation timeline
+  - [ ] Common patterns
+  
+- [ ] **Update RDoc**
+  - [ ] Document `Tea.normalize_init`
+  - [ ] Document new `Tea.run` signature
+  - [ ] Update Fragment examples throughout
+
+### RBS Type Signatures
+- [ ] **Update Tea module RBS**
+  ```ruby
+  module RatatuiRuby::Tea
+    def self.run: (
+      ?fragment: Module,
+      ?model: untyped,
+      ?view: ^(untyped, untyped) -> Widget,
+      ?update: ^(untyped, untyped) -> untyped,
+      ?init: ^() -> untyped,
+      ?argv: Array[String],
+      ?env: Hash[String, String]
+    ) -> void
+    
+    def self.normalize_init: (untyped result) -> [untyped, Command?]
+  end
+  ```
+
+### Testing
+- [ ] **Unit tests for `Tea.normalize_init`**
+  - [ ] Returns `[model, nil]` for model-only
+  - [ ] Returns `[nil, cmd]` for command-only
+  - [ ] Returns `[model, cmd]` for tuple
+  - [ ] Handles `tea_command?` detection
+  
+- [ ] **Integration tests for `Tea.run`**
+  - [ ] Fragment-first API works
+  - [ ] Old API still works (backward compat)
+  - [ ] Init commands are dispatched
+  - [ ] ARGV/ENV passed to Init
+  - [ ] Default Init works when not defined
+  
+- [ ] **Fractal composition tests**
+  - [ ] Parent Init calls child Inits
+  - [ ] Props passed to children
+  - [ ] Commands batched correctly
+  - [ ] Router still routes messages correctly
+
+### CHANGELOG
+- [ ] Add to `[UNRELEASED]` section:
+  ```markdown
+  ### Breaking Changes
+  - **REMOVED**: `INITIAL` and `MODEL` constants
+    - Use `Init` callable instead: `Init = -> { [Model.new(...), nil] }`
+    - `Init` is optional (defaults to `-> { Model.new }`)
+  
+  ### Added
+  - **Init Callable Pattern**: Fragments support `Init` callable for parameterized initialization
+    - Returns `[model, command]` tuple (DWIM supported)
+    - Accepts flags/props for parent-to-child data flow
+    - `Tea.normalize_init` helper for composing child Inits
+  - **Fragment-First Runtime API**: `Tea.run(fragment: MyApp, argv: ARGV, env: ENV)`
+  - **Concept Documentation**: Created `doc/init.md` and series stubs
+  ```
+
+---
+
+## Breaking Changes
+
+**v0.4.0 is a BREAKING RELEASE**:
+
+- ❌ **REMOVED**: `INITIAL` and `MODEL` constants (use `Init` callable instead)
+- ✅ **NEW**: `Init` callable is the only supported initialization pattern
+- ✅ **NEW**: Runtime `fragment:` parameter for fragment-first API
+
+**Rationale**: Zero external users means zero migration burden. Ship clean architecture without legacy cruft.
+
+---
+
+## Open Questions
+
+None - all design decisions finalized with user.
+
+---
+
+## Design Notes (Contributor Reference)
+
+### Concept Documentation Series
+
+`doc/init.md` is the **first** in a series of concept documentation pages, one for each core TEA concept:
+- `doc/init.md` (this implementation)
+- `doc/fragment.md` (future)
+- `doc/model.md` (future)
+- `doc/view.md` (future)
+- `doc/update.md` (future)
+- `doc/command.md` (future)
+- `doc/message.md` (future)
+- `doc/output.md` (future)
+
+Each follows the Alexandrian Context-Problem-Solution pattern per `doc/contributors/documentation_style.md`.
+
+### Why Not Auto-Init in Router DSL?
+
+The Router DSL is **message-only** by design. It handles `Update` function routing, not initialization or view composition:
+
+```ruby
+route :stats, to: StatsPanel  # Only routes messages to StatsPanel::Update
+```
+
+Both `Init` and `View` remain **explicit composition** (manual), which provides:
+- ✅ Full control over initialization order and props
+- ✅ Clear, explicit data flow
+- ✅ Flexibility for conditional initialization
+- ✅ Consistency with View composition pattern
+
+### Terminology Inspirations
+
+This pattern draws from multiple proven MVU implementations:
+- **Elm**: `init : () -> (Model, Cmd Msg)` tuple return
+- **Iced (Rust)**: `fn new(flags: Flags) -> (State, Command)` parameterized init
+- **Bubble Tea (Go)**: `func (m Model) Init() tea.Cmd` method-based init
+- **Hyperapp (JS)**: `init: [state, ...effects]` array-based DWIM
+
+See `doc/contributors/mvu_research_notes.md` for detailed analysis.
+
+### Future: OutMsg Pattern
+
+Elm's "Translator Pattern" / "OutMsg Pattern" allows children to emit events to parents beyond state updates. Not needed for v0.4.0, but may be considered for future:
+
+```ruby
+# Potential future enhancement
+Update = ->(msg, model) do
+  case msg
+  in [:data_loaded, data]
+    [[model.with(data: data), nil], [:parent_event_here]]
+    #                                 ^^^^^^^^^^^^^^^^^^^^ OutMsg for parent
+  end
+end
+```
+
+See `doc/contributors/outmsg_pattern_notes.md` for details.
+
+---
+
+## Success Criteria
+
+- [ ] All existing tests pass
+- [ ] `bundle exec agent_rake` passes (0 warnings)
+- [ ] Both old and new API styles work
+- [ ] Fractal dashboard example uses Init pattern
+- [ ] Simple example uses Init pattern
+- [ ] Documentation is comprehensive and clear
+- [ ] Migration path is documented