ratatui_ruby-tea 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d10ee51cb79e58e9b24dbf78e696dcbc901ddedac44dce824c4cf8817e8b07a3
-  data.tar.gz: 1043f33f9e3804748ea3fdd5eef4783b7af3a81ed51b10ce88f3447953e1874e
+  metadata.gz: c83e509aceb1826713abd9e4835055c1d28397627438d3041783564195b1821b
+  data.tar.gz: d452ab612362d0d3216101ab9d454c950a8af07afcd913c3fa8627e69eb09887
 SHA512:
-  metadata.gz: e25205b29e1654964c88455f9a9fed89ee3464aacbecc458e128baae8bf0a788196e9c1fbdee9cea3549b0e9f60cf1bef5c48c870baa57af453759ad4625453b
-  data.tar.gz: 121c207a7c82109eafbcdbe7ebae838cccb33f54a0f6ff96c75832294e07496284c26c89fdf7bf0f871883959951414ab52582d209c52b1fb00249a0b009ab9f
+  metadata.gz: 6c211329907d95912192da187769d97ef56142cb4b1abe87ed2ed38c61b519d31f6823ab7f1154bc930e430b5fb19f1301c9497a9c68856c3c136c1ec0f6b962
+  data.tar.gz: 12b22830443dcc0783323bcccb8f2c1337a416cfe0cebaf89b0988d949f68e3ab73c4fbc37a6c140bc8b103465c8e467dad443654259961987dd91de7fa95767

data/AGENTS.md

@@ -55,10 +55,14 @@ Description: Part of the RatatuiRuby ecosystem.
 
 ## 3. Definition of Done (DoD)
 
-Before considering a task complete:
+Before considering a task complete and returning control to the user, you **MUST** ensure:
 
 0. **Production Ready:** RBS types are complete and accurate (no `untyped`), errors are handled with good DX, documentation follows guidelines, high code quality (no "pre-existing debt" excuses).
-1. **Default Rake Task Passes:** Run `bundle exec agent_rake` (no args). Confirm it passes with ZERO errors.
-2. **Documentation Updated:** If public APIs changed, update relevant docs.
-3. **Changelog Updated:** If public APIs changed, update CHANGELOG.md's **Unreleased** section.
-4. **Commit Message Suggested:** Include a suggested commit message block.
+1.  **Default Rake Task Passes:** Run `bundle exec agent_rake` (no args). Confirm it passes with ZERO errors **or warnings**.
+  - You will save time if you run `bundle exec agent_rake rubocop:autocorrect` first.
+  - If you think the rake is looking for deleted files, STOP EVERYTHING and tell the user.
+2.  **Documentation Updated:** If public APIs or observable behavior changed, update relevant RDoc, rustdoc, `doc/` files, `README.md`, and/or `ratatui_ruby-wiki` files.
+3.  **Changelog Updated:** If public APIs, observable behavior, or gemspec dependencies have changed, update [CHANGELOG.md](CHANGELOG.md)'s **Unreleased** section.
+4.  **Commit Message Suggested:** You **MUST** ensure the final message to the user includes a suggested commit message block. This is NOT optional.
+  - You MUST also check `git log -n1` to see the current standard AI footer ("Generated  with" and "Co-Authored-By") and include it in your suggested message.
+

data/CHANGELOG.md

@@ -21,6 +21,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.3.1] - 2026-01-11
+
+### Added
+
+- **CancellationToken**: Cooperative cancellation mechanism for long-running custom commands. Commands check `cancelled?` periodically and stop gracefully when `cancel!` is called. Includes `CancellationToken::NONE` null object for commands that ignore cancellation.
+
+- **Command::Custom Mixin**: Include in your class to mark it as a custom command. Provides `tea_command?` brand predicate and `tea_cancellation_grace_period` (default 2.0 seconds) for configuring cleanup time after cancellation.
+
+- **Command::Outlet**: Messaging gateway for custom commands. Use `put(tag, *payload)` to send results back to the update function. Validates Ractor-shareability in debug mode.
+
+- **Custom Command Dispatch**: Runtime now dispatches custom commands (objects with `tea_command?` returning true) in background threads. Commands receive an `Outlet` for messaging and a `CancellationToken` for cooperative shutdown.
+
+- **Command.custom Factory**: Wraps lambdas/procs to give them unique identity for dispatch tracking. Each `Command.custom(callable)` call produces a distinct wrapper, enabling targeted cancellation. Accepts optional `grace_period:` to override the default 2.0 second cleanup window.
+
+- **Command.cancel Factory**: Request cancellation of a running command. Returns a `Command::Cancel` sentinel that the runtime routes to the appropriate command's CancellationToken.
+
+- **Runtime Cancellation Dispatch**: The runtime now handles `Command::Cancel` by signaling the target command's `CancellationToken`, enabling cooperative cancellation of long-running commands. Respects `tea_cancellation_grace_period`: waits for the grace period, then force-kills unresponsive threads. Use `Float::INFINITY` to never force-kill.
+
+- **Graceful Shutdown**: On exit, runtime signals all active commands then respects each command's grace period. Commands with `Float::INFINITY` grace are waited on indefinitely (user has SIGKILL). Final queue messages are processed before returning.
+
+- **Automatic Error Propagation**: Custom commands that raise unhandled exceptions now produce a `Command::Error` message instead of corrupting the TUI display. The runtime catches exceptions and pushes `Command::Error.new(command:, exception:)` to the queue. Pattern match on `Command::Error` in your update function to handle failures uniformly. Factory method `Command.error(command, exception)` is available for testing.
+
+- **Command::System Cancellation**: Streaming shell commands now respect cooperative cancellation. When cancelled, sends `SIGTERM` for graceful shutdown, then `SIGKILL` if the child process doesn't exit. Prevents orphaned child processes from lingering after app exit.
+
+### Changed
+
+### Fixed
+
+- **Ractor Enforcement is Debug-Only**: The Ractor-shareability check now only runs in debug mode (and automated tests). Production skips this check for performance, matching the original specification. Previously, the check ran unconditionally.
+
+### Removed
+
 ## [0.3.0] - 2026-01-08
 
 ### Added
@@ -83,6 +115,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **First Release**: Empty release of `ratatui_ruby-tea`, a Ruby implementation of The Elm Architecture (TEA) for `ratatui_ruby`. Scaffolding generated by `ratatui_ruby-devtools`.
 
 [Unreleased]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/HEAD
+[0.3.1]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.3.1
 [0.3.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.3.0
 [0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.2.0
 [0.2.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.2.0

data/README.md

@@ -26,6 +26,23 @@ Mailing List: Announcements](https://img.shields.io/badge/mailing_list-announcem
 
 Please join the **announce** mailing list at https://lists.sr.ht/~kerrick/ratatui_ruby-announce to stay up-to-date on new releases and announcements. See the [`trunk` branch](https://git.sr.ht/~kerrick/ratatui_ruby-tea/tree/trunk) for pre-release updates.
 
+---
+
+## Quick Links
+
+### The Ecosystem
+
+**RatatuiRuby:** [Core engine](https://git.sr.ht/~kerrick/ratatui_ruby) • **Tea:** [MVU architecture](https://git.sr.ht/~kerrick/ratatui_ruby-tea) • **Kit:** [Component architecture](https://git.sr.ht/~kerrick/ratatui_ruby-kit) (Planned) • **DSL:** [Glimmer syntax](https://sr.ht/~kerrick/ratatui_ruby/#chapter-4-the-syntax) (Planned) • **Framework:** [Omakase framework](https://git.sr.ht/~kerrick/ratatui_ruby-framework) (Planned) • **UI:** [Polished widgets](https://git.sr.ht/~kerrick/ratatui_ruby-ui) (Planned) • **UI Pro:** [More polished widgets](https://sr.ht/~kerrick/ratatui_ruby#chapter-6-licensing) (Planned)
+
+### For App Developers
+
+**Get Started:** [Quickstart](https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/doc/getting_started/quickstart.md) • [Examples](https://git.sr.ht/~kerrick/ratatui_ruby/tree/stable/item/examples) ⸺ **Stay Informed:** [Announce List](https://lists.sr.ht/~kerrick/ratatui_ruby-announce) • [FAQ](https://man.sr.ht/~kerrick/ratatui_ruby/troubleshooting.md) ⸺ **Reach Out:** [Discuss List](https://lists.sr.ht/~kerrick/ratatui_ruby-discuss) • [Bug Tracker](https://todo.sr.ht/~kerrick/ratatui_ruby)
+
+### For Contributors
+
+**Get Started:** [Contributing Guide](https://man.sr.ht/~kerrick/ratatui_ruby/contributing.md) • [Code of Conduct](https://man.sr.ht/~kerrick/ratatui_ruby/code_of_conduct.md) ⸺ **Stay Informed:** [Announce List](https://lists.sr.ht/~kerrick/ratatui_ruby-announce) • [Project History](https://man.sr.ht/~kerrick/ratatui_ruby/history/index.md) ⸺ **Reach Out:** [Development List](https://lists.sr.ht/~kerrick/ratatui_ruby-devel) • [Bug Tracker](https://todo.sr.ht/~kerrick/ratatui_ruby)
+
+---
 
 ## Compatibility
 

data/Rakefile

@@ -13,4 +13,4 @@ RatatuiRuby::Devtools.install!
 # Import project-specific tasks
 Dir.glob("tasks/*.rake").each { |r| import r }
 
-task default: %w[lint:fix test lint reuse]
+task default: %w[lint:fix test lint reuse steep]

data/Steepfile

@@ -7,7 +7,7 @@ target :lib do
   signature "sig"
   check "lib"
 
-  library "pathname"
-  library "fileutils"
-  library "minitest"
+  library "open3"
+
+  collection_config "rbs_collection.yaml"
 end

data/doc/contributors/design/commands_and_outlets.md

@@ -0,0 +1,204 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Custom Commands Design (`ratatui_ruby-tea`)
+
+This document describes the architectural design and guiding principles of custom commands in `ratatui_ruby-tea`. It is intended for contributors, architects, and AI agents working on the codebase.
+
+## Core Abstractions
+
+Custom commands extend Tea with user-defined side effects: WebSockets, gRPC, database polling, background workers. The architecture provides four key components:
+
+| Component | Purpose |
+|-----------|---------|
+| `Command::Custom` | Mixin for command identification |
+| `Command::Outlet` | Messaging gateway for result delivery |
+| `Command::CancellationToken` | Cooperative cancellation mechanism |
+| `Command.custom { ... }` | Wrapper giving callables unique identity |
+
+---
+
+## Guiding Design Principles
+
+### 1. Messaging Gateway over Raw Queue
+
+Commands produce messages. Those messages cross threads. Without abstraction, queue manipulation scatters across the codebase.
+
+The Outlet wraps the internal queue with a domain-specific API. Commands call `out.put(:tag, data)` instead of managing queue details. Debug mode validates Ractor-shareability automatically—commands cannot accidentally push unshareable data.
+
+| Aspect | Raw Queue | Outlet |
+|--------|-----------|--------|
+| Ractor safety | Manual | Automatic |
+| Error messages | Generic | Contextual |
+| API | `queue << Ractor.make_shareable([...])` | `out.put(:tag, data)` |
+| Pattern | Implementation detail | **Messaging Gateway** |
+
+This implements the **Messaging Gateway** pattern from Enterprise Integration Patterns. The Outlet is a **Facade** (Gang of Four) over the queue, and acts as a **Channel Adapter** translating command results into update function messages.
+
+### 2. Cooperative Cancellation over Thread Termination
+
+Long-running commands block the event loop. WebSocket listeners, database pollers, and streaming connections run indefinitely until stopped. Stopping them abruptly corrupts state.
+
+`Thread#kill` terminates immediately. Mutexes may deadlock. Resources may leak. Database transactions may abort mid-write.
+
+The `CancellationToken` signals cancellation requests. Commands check `token.cancelled?` periodically and stop at safe points. Cleanup code runs. Resources release. Transactions commit.
+
+| Aspect | `Thread#kill` | CancellationToken |
+|--------|---------------|------------------|
+| Cleanup | None (immediate termination) | Command controls cleanup |
+| Resource safety | May corrupt state | Clean shutdown |
+| Mutexes | May deadlock | Released properly |
+| Pattern | Forceful | **Cooperative** |
+
+**Configurable grace periods** accommodate different cleanup needs:
+
+- `0.5` seconds — Quick HTTP abort, minimal cleanup
+- `2.0` seconds — Default, suitable for most commands
+- `5.0` seconds — WebSocket close handshake with remote server
+- `Float::INFINITY` — Never force-kill (database transactions)
+
+### 3. Command Identity via Object Reference
+
+The runtime tracks active commands by their object identity. When the update function returns `Command.cancel(handle)`, the runtime looks up that exact object in its registry and signals its token.
+
+Class-based commands get unique identity automatically—each `MyCommand.new` produces a distinct object. Reusable lambdas and procs share identity. Dispatch them twice, and cancellation would affect both.
+
+`Command.custom(callable)` wraps a callable in a unique container. Each call produces a distinct handle. Store it in your model. Cancel it later by returning `Command.cancel(handle)`.
+
+### 4. Automatic Error Propagation
+
+Commands run in threads. Exceptions bubble up silently. The update function never sees them. Backtraces written to STDERR corrupt the TUI display.
+
+The runtime catches unhandled exceptions and pushes `Command::Error` to the queue. This is automatic—commands do not rescue exceptions unless they want custom handling. The update function pattern-matches on `Command::Error` and reacts appropriately.
+
+This mirrors the sentinel pattern used for `Command::Exit` and `Command::Cancel`.
+
+### 5. Ractor Readiness
+
+This design is forward-compatible with Ruby's Ractor-based parallelism.
+
+**What's already shareable:**
+
+| Pattern | Shareable? | Why |
+|---------|------------|-----|
+| Module-constant lambda | ✅ Yes | `self` is the frozen module |
+| Closure-free block | ✅ Yes | No captured variables |
+| `Data.define` command | ✅ Yes | Immutable by definition |
+| Frozen class instance | ✅ Yes | Deeply frozen |
+
+**Debug mode validation:**
+
+In debug mode, Tea validates Ractor shareability at dispatch time. `Ractor.shareable?(command)` catches most issues. The Outlet's `put` method validates messages before pushing them to the queue.
+
+**Why Thread dispatch is Ractor-safe:**
+
+Commands execute in Threads within the **main Ractor**. Only messages (via Outlet) cross the shareability boundary. The `CancellationToken` stays within its Thread—never shared across Ractors. The `@active_commands` hash is local to the Runtime (main Ractor).
+
+When Ruby evolves to true Ractor parallelism, this design upgrades transparently: commands are already validated as shareable, so they could be sent to worker Ractors without code changes.
+
+---
+
+## Pattern Lineage
+
+This design implements several established patterns from the software architecture literature.
+
+### Design Patterns (Gang of Four)
+
+| Component | Pattern |
+|-----------|---------|
+| Custom Mixin | **Command** — Encapsulates a request as an object |
+| Outlet | **Facade** — Simplified interface to a complex subsystem |
+| Runtime | **Mediator** — Coordinates command dispatch and message routing |
+| Update Function | **State** — Behavior changes based on internal state |
+
+### Enterprise Integration Patterns (Hohpe & Woolf)
+
+| Component | Pattern |
+|-----------|---------|
+| Outlet | **Messaging Gateway** — Wraps message channel access |
+| Outlet | **Channel Adapter** — Connects applications to messaging systems |
+| Queue | **Point-to-Point Channel** — Single consumer receives each message |
+
+### Cancellation Patterns
+
+| Platform | Mechanism | Relationship |
+|----------|-----------|--------------|
+| **.NET** | `CancellationToken` | Direct inspiration for API design |
+| **Go** | `context.Context` | Cooperative cancellation via `ctx.Done()` |
+| **JavaScript** | `AbortController` | Web Fetch API cancellation |
+| **Java** | `Thread.interrupt()` | Flag-based cooperative cancellation |
+| **Kotlin** | `Job.cancel()` | Coroutine cancellation |
+
+---
+
+## Prior Art
+
+### The Elm Architecture (TEA)
+
+| Framework | Language | Notes |
+|-----------|----------|-------|
+| **Elm** | Elm | Original TEA; `Cmd` + `Sub` primitives |
+| **BubbleTea** | Go | TUI implementation; "Subscriptions are Loops" philosophy |
+| **Iced** | Rust | GUI TEA with Command + Subscription |
+| **Miso** | Haskell | Web TEA with Effect + Sub |
+| **Bolero** | F# | Web TEA with Cmd + Sub |
+
+### Redux Ecosystem
+
+| Library | Pattern | Mapping |
+|---------|---------|---------|
+| **Redux Thunk** | Raw dispatch access | Direct queue access (rejected) |
+| **Redux Saga** | `put()` effect dispatches actions | **Outlet.put** ← adopted |
+| **Redux Observable** | RxJS Observables | RxRuby (rejected for complexity) |
+| **redux-loop** | Elm-style Cmd | Recursive commands |
+
+Redux Saga's `put()` is the direct inspiration for `out.put()`. The Saga pattern—long-running processes that listen for actions and dispatch new ones—maps directly to Tea's custom commands.
+
+### Ruby Ecosystem
+
+| Library | Pattern | Relationship |
+|---------|---------|--------------|
+| **Observable** (stdlib) | Observer pattern | Similar push semantics, lacks thread-safety |
+| **Concurrent Ruby** | Actor, Promises | More complex than needed |
+| **Celluloid** | Actor mailboxes | Inspiration for internal terminology |
+| **Sidekiq** | Background jobs | Similar "fire command, receive result" model |
+
+---
+
+## Key Influences Summary
+
+| Influence | What We Adopted |
+|-----------|-----------------|
+| **Elm** | MVU architecture, Cmd/Msg pattern |
+| **BubbleTea** | "Subscriptions are Loops" philosophy |
+| **Redux Saga** | `put()` for message dispatch |
+| **.NET CancellationToken** | Cooperative cancellation with grace periods |
+| **EIP Messaging Gateway** | Outlet as infrastructure abstraction |
+| **Go context.Context** | Cancellation propagation pattern |
+
+---
+
+## Further Reading
+
+### External Resources
+
+- [Elm Guide](https://guide.elm-lang.org/) — Official Elm documentation covering commands and effects
+- [BubbleTea](https://github.com/charmbracelet/bubbletea) — Go TUI framework based on The Elm Architecture
+- [Redux Saga](https://redux-saga.js.org/) — Saga pattern and `put()` effect documentation
+- [Enterprise Integration Patterns](https://www.enterpriseintegrationpatterns.com/) — Messaging patterns reference by Hohpe & Woolf
+
+### Academic References
+
+1. **Gamma, Helm, Johnson, Vlissides** (1994). *Design Patterns: Elements of Reusable Object-Oriented Software*. Addison-Wesley.
+   - Command, Facade, Mediator, State patterns
+
+2. **Fowler, M.** (2002). *Patterns of Enterprise Application Architecture*. Addison-Wesley.
+   - Gateway pattern
+
+3. **Hohpe, G. & Woolf, B.** (2003). *Enterprise Integration Patterns*. Addison-Wesley.
+   - Messaging Gateway, Message Channel, Point-to-Point Channel, Channel Adapter
+
+4. **Joshi, U.** (2023). *Patterns of Distributed Systems*. Addison-Wesley.
+   - Write-Ahead Log, Thread Pool

data/doc/contributors/kit-no-outlet.md

@@ -0,0 +1,237 @@
+<!--
+SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Why Kit Doesn't Need Outlet
+
+> **Context**: The `unified-draft.md` specifies `Tea::Command::Outlet` for message passing from custom commands to the Tea runtime. This document explains why Kit (the component-based runtime) does not need this abstraction.
+
+---
+
+## The Core Insight: Immediate-Mode Rendering
+
+RatatuiRuby's Engine is **immediate-mode**:
+
+> "Each frame, your code describes the entire UI from scratch. The Engine draws it and immediately forgets it, holding no application state between renders."
+
+This means Kit walks the entire component tree and calls `render` **every frame**. Components don't need to notify anyone of state changes—the next frame automatically sees updated state.
+
+---
+
+## Tea vs Kit: Different Problems
+
+| Concern | Tea | Kit |
+|---------|-----|-----|
+| **State model** | Immutable (Ractor-safe) | Mutable (encapsulated) |
+| **State location** | Single Model in runtime | Distributed in components |
+| **Async results** | Message → Queue → Update | Callback → mutate state |
+| **Render trigger** | After update function | **Every frame** |
+| **Re-render notification** | Implicit (update always renders) | **Not needed** (always renders) |
+
+---
+
+## WebSocket Example: Tea vs Kit
+
+### Tea: Outlet Required
+
+```ruby
+class WebSocketCommand
+  include Tea::Command::Custom
+
+  def call(out, token)
+    ws = WebSocket::Client.new(@url)
+    ws.on_message { |msg| out.put(:ws, :message, data: msg) }
+    ws.connect
+
+    until token.cancelled?
+      sleep 1
+    end
+
+    ws.close
+  end
+end
+
+def update(msg, model)
+  case msg
+  in [:ws, :message, data:]
+    model.with(messages: model.messages + [data])
+  end
+end
+```
+
+Tea needs Outlet because:
+1. Command runs in a separate thread
+2. Model is immutable—can't mutate from callback
+3. Runtime must receive messages to call `update`
+
+### Kit: Direct Mutation
+
+```ruby
+class WebSocketTab
+  include Kit::Component
+
+  def initialize(url:)
+    @url = url
+    @messages = []
+  end
+
+  def mount
+    @ws = WebSocket::Client.new(@url)
+    @ws.on_message { |msg| @messages << msg }
+    @ws.connect_async
+  end
+
+  def unmount
+    @ws&.close
+  end
+
+  def render(frame, area)
+    frame.render_widget(tui.list(items: @messages.last(10)), area)
+  end
+end
+```
+
+Kit doesn't need Outlet because:
+1. Component owns the WebSocket directly
+2. State is mutable—callbacks mutate `@messages`
+3. Next frame's `render` sees updated state automatically
+
+---
+
+## Why Each Tea Concept Is Unnecessary in Kit
+
+### Outlet (Message Gateway)
+
+**Tea**: Routes messages from command thread → runtime queue → update function.
+
+**Kit**: Not needed. Callbacks mutate component state directly. Immediate-mode rendering sees changes next frame.
+
+### CancellationToken
+
+**Tea**: Runtime signals command to stop cooperatively, since commands run in spawned threads tracked by the runtime.
+
+**Kit**: Not needed. Components have `unmount` lifecycle hook. Component stops its own resources:
+
+```ruby
+def unmount
+  @ws&.close
+  @polling_thread&.kill
+end
+```
+
+### Ractor Safety
+
+**Tea**: Messages cross thread boundaries and must be Ractor-shareable for future Ruby 4.0 compatibility.
+
+**Kit**: Not needed. Components are mutable by design. State stays within the component. No Ractor isolation required.
+
+### Thread Tracking
+
+**Tea**: Runtime tracks spawned command threads to ensure clean shutdown.
+
+**Kit**: Not needed. Each component tracks its own resources. Tree traversal during shutdown calls `unmount` on each component.
+
+---
+
+## What Kit DOES Need
+
+### 1. Lifecycle Hooks
+
+```ruby
+module Kit::Component
+  def mount
+    # Called when component enters tree
+  end
+
+  def unmount
+    # Called when component leaves tree
+  end
+end
+```
+
+These replace Tea's command spawning and cancellation.
+
+### 2. Thread Safety for Complex Mutations
+
+For simple mutations (array append, boolean toggle), Ruby's GIL is sufficient.
+
+For complex mutations:
+
+```ruby
+def mount
+  @mutex = Mutex.new
+  @ws = WebSocket::Client.new(@url)
+  @ws.on_message do |msg|
+    @mutex.synchronize { @messages << msg }
+  end
+end
+
+def render(frame, area)
+  messages = @mutex.synchronize { @messages.dup }
+  # render with messages
+end
+```
+
+### 3. Error Handling
+
+Components should rescue and surface errors:
+
+```ruby
+def mount
+  @ws = WebSocket::Client.new(@url)
+  @ws.on_error { |e| @error = e.message }
+rescue => e
+  @error = e.message
+end
+```
+
+---
+
+## Comparison Table
+
+| Abstraction | Tea | Kit | Why Different |
+|-------------|-----|-----|---------------|
+| **Outlet** | ✓ Required | ✗ Not needed | Kit mutates directly |
+| **CancellationToken** | ✓ Required | ✗ Not needed | Kit has `unmount` |
+| **Ractor safety** | ✓ Required | ✗ Not needed | Kit is mutable |
+| **Thread tracking** | ✓ Runtime tracks | ✗ Not needed | Components self-manage |
+| **Lifecycle hooks** | ✗ Not applicable | ✓ Required | Kit needs mount/unmount |
+| **Mutex** | ✗ Uses Outlet | ⚠ If complex | Kit needs manual locking |
+
+---
+
+## Architectural Summary
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                          ENGINE                                  │
+│               (Immediate-mode, renders every frame)              │
+├─────────────────────────────┬───────────────────────────────────┤
+│            TEA              │              KIT                   │
+│                             │                                    │
+│  Immutable Model            │  Mutable Components                │
+│  Commands spawn threads     │  Components own resources          │
+│  Outlet sends messages      │  Callbacks mutate state            │
+│  Runtime tracks threads     │  unmount cleans up                 │
+│  Ractor-safe required       │  GIL + Mutex sufficient            │
+│                             │                                    │
+│  NEEDS OUTLET               │  DOESN'T NEED OUTLET               │
+└─────────────────────────────┴───────────────────────────────────┘
+```
+
+---
+
+## Conclusion
+
+**Outlet is Tea-specific.** It solves the problem of getting async results into an immutable, unidirectional data flow.
+
+Kit's paradigm—mutable components with immediate-mode rendering—makes Outlet unnecessary:
+
+1. **Callbacks mutate state** → No message routing needed
+2. **Render every frame** → No change notification needed
+3. **`unmount` hook** → No external cancellation needed
+4. **Components own resources** → No runtime tracking needed
+
+The Outlet stays in `Tea::Command::Outlet`. Kit needs no equivalent.