ratatui_ruby-tea 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1bf31fb6ff8bacdcd6f9c54e794e0c769f5c52afde2c5e4d78cbee48be36b12
-  data.tar.gz: 1bd65539c4eace89fc1d58d857d81fb9cc03187ea7ae770d4b5c4a051ae407a0
+  metadata.gz: d10ee51cb79e58e9b24dbf78e696dcbc901ddedac44dce824c4cf8817e8b07a3
+  data.tar.gz: 1043f33f9e3804748ea3fdd5eef4783b7af3a81ed51b10ce88f3447953e1874e
 SHA512:
-  metadata.gz: 413f42942963ef06433b683b2cf3820db1a8cd679fcf263aaccc4cbd3780fa01b7bcc66842aeaad7606377380530215a9b6a07a145d6df56ecf34a5053c998cb
-  data.tar.gz: 8edaf06fbf149723ca70b2f27157c8c2d22536f060c94facfb6d904223b48dc21613daa0a130237548a40d705074ec22f90403e27855b1b578bad0e770f27040
+  metadata.gz: e25205b29e1654964c88455f9a9fed89ee3464aacbecc458e128baae8bf0a788196e9c1fbdee9cea3549b0e9f60cf1bef5c48c870baa57af453759ad4625453b
+  data.tar.gz: 121c207a7c82109eafbcdbe7ebae838cccb33f54a0f6ff96c75832294e07496284c26c89fdf7bf0f871883959951414ab52582d209c52b1fb00249a0b009ab9f

data/AGENTS.md

@@ -31,6 +31,13 @@ Description: Part of the RatatuiRuby ecosystem.
 - **Setup:** `bin/setup` must handle Bundler dependencies.
 - **Git:** ALWAYS set `PAGER=cat` with `git`. **THIS IS CRITICAL!**
 
+### Tea-Specific Vocabulary
+
+- **BANNED WORD: "component"** — Reserved for Kit.
+- **Avoid "widget" for Tea units** — "Widget" refers to Engine/Ratatui render primitives. In Tea, call them **bags**.
+- **Bag:** A module containing `Model`, `INITIAL`, `UPDATE`, and `VIEW` constants. Bags compose: parent bags delegate to child bags.
+- Use "model", "update", "view" for the MVU pattern. Use "message" (not "msg") and "command" (not "cmd").
+
 ### Ruby Standards
 
 - Use `Data.define` for all value objects (Ruby 3.2+).
@@ -50,6 +57,7 @@ Description: Part of the RatatuiRuby ecosystem.
 
 Before considering a task complete:
 
+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.

data/CHANGELOG.md

@@ -21,6 +21,46 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.3.0] - 2026-01-08
+
+### Added
+
+- **Router DSL**: New `Tea::Router` module provides declarative routing for Fractal Architecture:
+  - `route :prefix, to: ChildBag` — declares a child bag route
+  - `keymap { key "q", -> { Command.exit } }` — declares keyboard handlers
+  - `keymap { key "x", handler, when: -> (m) { m.ready? } }` — guards (also: `if:`, `only:`, `guard:`, `unless:`, `except:`, `skip:`)
+  - `keymap { only when: guard do ... end }` — nested guard blocks apply to all keys within (also: `skip when: ...`)
+  - `mousemap { click -> (x, y) { ... } }` — declares mouse handlers
+  - `action :name, handler` — declares reusable actions for key/mouse handlers
+  - `from_router` — generates an UPDATE lambda from routes and handlers
+
+- **Composition Helpers**: New helper methods for Fractal Architecture reduce boilerplate:
+  - `Tea.route(command, :prefix)` — wraps a command to route results to a child bag
+  - `Tea.delegate(message, :prefix, child_update, child_model)` — dispatches prefixed messages to child bags
+
+- **Command Mapping**: `Command.map(inner_command, &mapper)` wraps a child command and transforms its result message. Essential for parent bags routing child command results.
+
+- **Shortcuts Module**: `require "ratatui_ruby/tea/shortcuts"` and `include Tea::Shortcuts` for short aliases:
+  - `Cmd.exit` — alias for `Command.exit`
+  - `Cmd.sh(command, tag)` — alias for `Command.system`
+  - `Cmd.map(command, &block)` — alias for `Command.map`
+
+- **Sync Event Integration**: Runtime now handles `Event::Sync` from `RatatuiRuby::SyntheticEvents`. When a Sync event is received, the runtime waits for all pending async threads and processes their results before continuing. Use `inject_sync` in tests for deterministic async verification.
+
+- **Streaming Command Output**: `Command.system` now accepts a `stream:` keyword argument. When `stream: true`, the runtime sends incremental messages (`[:tag, :stdout, line]`, `[:tag, :stderr, line]`) as output arrives, followed by `[:tag, :complete, {status:}]` when the command finishes. Invalid commands send `[:tag, :error, {message:}]`. Default behavior (`stream: false`) remains unchanged.
+
+- **Custom Shell Modal Example**: Added `examples/app_fractal_dashboard/bags/custom_shell_modal.rb` demonstrating a 3-bag fractal architecture for a modal that runs arbitrary shell commands with streaming output. Features interleaved stdout/stderr, exit status indication, and Ractor-safe implementation using `tui.overlay` for opaque rendering.
+
+### Changed
+
+- **Command Module Rename (Breaking)**: The `Cmd` module is now `Command` with Rubyish naming:
+  - `Cmd::Quit` → `Command::Exit` (use `Command.exit` factory)
+  - `Cmd::Exec` → `Command::System` (use `Command.system(cmd, tag)` factory)
+
+### Fixed
+
+### Removed
+
 ## [0.2.0] - 2026-01-08
 
 ### Added
@@ -43,6 +83,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.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
 [0.1.0]: https://git.sr.ht/~kerrick/ratatui_ruby-tea/refs/v0.1.0

data/README.md

@@ -106,7 +106,7 @@ end
 
 UPDATE = -> (msg, model) do
   if msg.q? || msg.ctrl_c?
-    RatatuiRuby::Tea::Cmd.quit
+    RatatuiRuby::Tea::Command.exit
   else
     model
   end

data/doc/concepts/application_architecture.md

@@ -5,12 +5,191 @@
 
 # Application Architecture
 
-Architect robust TUI applications using core library patterns and API best practices.
+Build robust TUI applications with Tea patterns.
 
 ## Core Concepts
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+_This section is incomplete. Check the source files._
 
 ## Thread and Ractor Safety
 
-_Because this gem is in pre-release, it lacks documentation. Please check the source files._
+### The Strategic Context
+
+Ruby 4.0 introduces [Ractors](https://docs.ruby-lang.org/en/4.0/Ractor.html)—
+true parallel actors that forbid shared mutable state. Code that passes
+mutable objects between threads crashes in a Ractor world.
+
+Tea prepares you today. The runtime enforces Ractor-shareability on every
+Model and Message *now*, using standard threads. Pass a mutable object,
+and it raises an error immediately. Write Ractor-safe code today; upgrade
+to Ruby 4.0 without changes tomorrow.
+
+Enforce immutability rules before you strictly need them, and the migration
+is invisible.
+
+### The Problem
+
+Ruby's Ractor model prevents data races by forbidding shared mutable state.
+Mutable objects cause runtime errors:
+
+```
+RatatuiRuby::Error::Invariant: Model is not Ractor-shareable.
+```
+
+### The Solution
+
+Use `Ractor.make_shareable`. It recursively freezes everything:
+
+```ruby
+Ractor.make_shareable(model.with(text: "#{model.text}#{char}"))
+```
+
+For constants, wrap INITIAL:
+
+```ruby
+INITIAL = Ractor.make_shareable(
+  Model.new(text: "", running: false, chunks: [])
+)
+```
+
+For collection updates:
+
+```ruby
+new_chunks = Ractor.make_shareable([*model.chunks, new_item])
+```
+
+### The Lightweight Alternative
+
+When you know exactly what's mutable, `.freeze` is shorter:
+
+```ruby
+[model.with(text: "#{model.text}#{char}".freeze), nil]
+```
+
+### Foot-Guns
+
+#### frozen_string_literal Only Affects Literals
+
+The magic comment freezes strings that appear directly in source code.
+Computed strings are mutable.
+
+```ruby
+# frozen_string_literal: true
+
+"literal"        # frozen ✓
+"#{var}"         # mutable ✗
+str.chop         # mutable ✗
+str + other      # mutable ✗
+```
+
+#### Data.define Needs Shareable Values
+
+`Data.define` creates frozen instances. The instance is Ractor-shareable
+only when all its values are shareable.
+
+### Quick Reference
+
+| Pattern | Code |
+|---------|------|
+| Make anything shareable | `Ractor.make_shareable(obj)` |
+| Freeze a string | `str.freeze` |
+| INITIAL constant | `Ractor.make_shareable(Model.new(...))` |
+| Array update | `Ractor.make_shareable([*old, new])` |
+
+### Debugging
+
+See this error?
+
+```
+RatatuiRuby::Error::Invariant: Model is not Ractor-shareable.
+```
+
+Wrap the returned model with `Ractor.make_shareable`.
+
+## Modals and Command Result Routing
+
+Modals capture keyboard input. They overlay the main UI and intercept keypresses until dismissed. But async commands keep running in the background. When their results arrive, they look like any other message.
+
+It's tempting to intercept *all* messages when the modal is active. This swallows those command results.
+
+### The Scenario
+
+1. User presses "u" to fetch uptime. The runtime dispatches an async command.
+2. User presses "c" to open a modal dialog.
+3. The uptime command completes. It sends `[:network, :uptime, { stdout:, ... }]`.
+4. The modal intercept sees the modal is active. It routes that message to the modal.
+5. The modal ignores it.
+6. The uptime panel never updates.
+
+### The Fix
+
+Route command results before modal interception. Modals intercept user input, not async results.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+# Wrong: modal intercepts everything
+UPDATE = lambda do |message, model|
+  if Modal.active?(model.modal)
+    # Swallows command results
+    return Modal::UPDATE.call(message, model.modal)
+  end
+
+  case message
+  in [:network, *rest]
+    # Never reached while modal is open
+  end
+end
+
+# Correct: route command results first
+UPDATE = lambda do |message, model|
+  # 1. Route async command results (always)
+  case message
+  in [:network, *rest]
+    return [model.with(network: new_network), command]
+  in [:stats, *rest]
+    return [model.with(stats: new_stats), command]
+  else
+    nil
+  end
+
+  # 2. Modal intercepts user input
+  if Modal.active?(model.modal)
+    return Modal::UPDATE.call(message, model.modal)
+  end
+
+  # 3. Handle other input
+  case message
+  in _ if message.q? then Command.exit
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->
+
+### The Router DSL
+
+`Tea::Router` handles this correctly. Routes declared with `route :prefix, to: ChildModule` process before keymap handlers. Command results flow through even when guards block keyboard input.
+
+<!-- SPDX-SnippetBegin -->
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long
+  SPDX-License-Identifier: MIT-0
+-->
+```ruby
+module Dashboard
+  include Tea::Router
+
+  route :stats, to: StatsPanel
+  route :network, to: NetworkPanel
+
+  keymap do
+    only when: MODAL_INACTIVE do
+      key "u", -> { Uptime.fetch_command }
+    end
+  end
+end
+```
+<!-- SPDX-SnippetEnd -->

data/examples/app_fractal_dashboard/README.md

@@ -0,0 +1,60 @@
+<!--
+  SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+  SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Cmd.map Fractal Dashboard
+
+Demonstrates **Fractal Architecture** using `Cmd.map` for component composition.
+
+## Problem
+
+Without composition, a complex app needs one giant `case` statement handling every possible message from every child—the "God Reducer" anti-pattern. This doesn't scale.
+
+## Solution
+
+`Cmd.map` wraps child commands so their results route through parents:
+
+```ruby
+# Child produces [:system_info, {stdout:, ...}]
+child_cmd = SystemInfoWidget.fetch_cmd
+
+# Parent wraps to produce [:stats, :system_info, {...}]
+parent_cmd = Cmd.map(child_cmd) { |m| [:stats, *m] }
+```
+
+Each layer handles only its own messages. Parents pattern-match on the first element to route to the correct child.
+
+## Architecture
+
+```
+Dashboard (root)
+├── StatsPanel
+│   ├── SystemInfoWidget → Cmd.exec("uname -a", :system_info)
+│   └── DiskUsageWidget  → Cmd.exec("df -h", :disk_usage)
+└── NetworkPanel
+    ├── PingWidget       → Cmd.exec("ping -c 1 localhost", :ping)
+    └── UptimeWidget     → Cmd.exec("uptime", :uptime)
+```
+
+## Hotkeys
+
+| Key | Action |
+|-----|--------|
+| `s` | Fetch system info |
+| `d` | Fetch disk usage |
+| `p` | Ping localhost |
+| `u` | Fetch uptime |
+| `q` | Quit |
+
+## Key Concepts
+
+1. **Widget isolation**: Each widget has its own `Model`, `UPDATE`, and `fetch_cmd`. It knows nothing about parents.
+2. **Message routing**: Parents prefix child messages (`:stats`, `:network`) and pattern-match to route.
+3. **Recursive dispatch**: `Cmd.map` delegates inner command execution to the runtime, then transforms the result.
+
+## Usage
+
+```bash
+ruby examples/widget_cmd_map/app.rb
+```

data/examples/app_fractal_dashboard/app.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+$LOAD_PATH.unshift File.expand_path("../../lib", __dir__)
+
+require "ratatui_ruby"
+require "ratatui_ruby/tea"
+
+# Demonstrates three approaches to UPDATE routing in Fractal Architecture.
+#
+# == Usage
+#
+#   ruby app.rb           # Defaults to 'manual'
+#   ruby app.rb manual    # Verbose pattern matching
+#   ruby app.rb helpers   # Tea.route and Tea.delegate helpers
+#   ruby app.rb router    # Tea::Router DSL
+#
+# All three share the same bags, Model, INITIAL, and VIEW. Only the UPDATE
+# implementation differs. Compare the three update_*.rb files to see the
+# progression from verbose to declarative.
+#
+# == Architecture
+#
+#   app.rb              ← Entry point (you are here)
+#   dashboard/
+#   ├── base.rb         ← Shared: Model, INITIAL, VIEW
+#   ├── update_manual.rb
+#   ├── update_helpers.rb
+#   └── update_router.rb
+#   bags/
+#   ├── system_info.rb
+#   ├── disk_usage.rb
+#   ├── ping.rb
+#   ├── uptime.rb
+#   ├── stats_panel.rb
+#   └── network_panel.rb
+
+VALID_MODES = %w[manual helpers router].freeze
+
+mode = ARGV[0] || "manual"
+unless VALID_MODES.include?(mode)
+  warn "Usage: ruby app.rb [#{VALID_MODES.join('|')}]"
+  exit 1
+end
+
+dashboard = case mode
+            when "manual"
+              require_relative "dashboard/update_manual"
+              DashboardManual
+            when "helpers"
+              require_relative "dashboard/update_helpers"
+              DashboardHelpers
+            when "router"
+              require_relative "dashboard/update_router"
+              DashboardRouter
+end
+
+puts "Running with #{mode} UPDATE..."
+RatatuiRuby::Tea.run(
+  model: dashboard::INITIAL,
+  view: dashboard::VIEW,
+  update: dashboard::UPDATE
+)

data/examples/app_fractal_dashboard/bags/custom_shell_input.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# Text input bag for custom shell command modal.
+#
+# Handles text entry. Sets cancelled: or submitted: in model for parent to detect.
+module CustomShellInput
+  Model = Data.define(:text, :cancelled, :submitted)
+  INITIAL = Ractor.make_shareable(Model.new(text: "", cancelled: false, submitted: false))
+
+  VIEW = lambda do |model, tui|
+    content = if model.text.empty?
+      tui.paragraph(text: tui.text_span(content: "Type a command...", style: { fg: :dark_gray }))
+    else
+      tui.paragraph(text: model.text)
+    end
+
+    tui.layout(
+      direction: :vertical,
+      constraints: [
+        tui.constraint_length(1),
+        tui.constraint_length(3),
+        tui.constraint_min(0),
+      ],
+      children: [
+        nil,
+        tui.center(
+          width_percent: 80,
+          child: tui.overlay(
+            layers: [
+              tui.clear,
+              tui.block(
+                title: "Run Command",
+                titles: [
+                  { content: "ESC: Cancel", position: :bottom, alignment: :left },
+                  { content: "ENTER: Run", position: :bottom, alignment: :right },
+                ],
+                borders: [:all],
+                children: [content]
+              ),
+            ]
+          )
+        ),
+        nil,
+      ]
+    )
+  end
+
+  UPDATE = lambda do |message, model|
+    case message
+    in _ if message.respond_to?(:esc?) && message.esc?
+      [model.with(cancelled: true), nil]
+
+    in _ if message.respond_to?(:enter?) && message.enter?
+      return [model.with(cancelled: true), nil] if model.text.strip.empty?
+      [model.with(submitted: true), nil]
+
+    in _ if message.respond_to?(:backspace?) && message.backspace?
+      [model.with(text: model.text.chop.freeze), nil]
+
+    in RatatuiRuby::Event::Paste
+      # Handle continuation backslashes: "foo \\\nbar" → "foo bar"
+      normalized = message.content.gsub(/\\\r?\n/, "").gsub(/[\r\n]/, " ")
+      [model.with(text: "#{model.text}#{normalized}".freeze), nil]
+
+    in RatatuiRuby::Event::Key if message.text? && message.code.length == 1
+      [model.with(text: "#{model.text}#{message.code}".freeze), nil]
+
+    else
+      [model, nil]
+    end
+  end
+end

data/examples/app_fractal_dashboard/bags/custom_shell_modal.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require_relative "custom_shell_input"
+require_relative "custom_shell_output"
+
+# Parent coordinator bag for custom shell modal.
+#
+# Routes to active child (input or output). Checks child model state for transitions.
+module CustomShellModal
+  Command = RatatuiRuby::Tea::Command
+
+  Model = Data.define(:mode, :input, :output)
+  INITIAL = Ractor.make_shareable(Model.new(mode: :none, input: CustomShellInput::INITIAL, output: CustomShellOutput::INITIAL))
+
+  VIEW = lambda do |model, tui|
+    case model.mode
+    when :none then nil
+    when :input then CustomShellInput::VIEW.call(model.input, tui)
+    when :output then CustomShellOutput::VIEW.call(model.output, tui)
+    end
+  end
+
+  UPDATE = lambda do |message, model|
+    case model.mode
+    when :input
+      new_input, cmd = CustomShellInput::UPDATE.call(message, model.input)
+
+      if new_input.cancelled
+        [INITIAL, nil]
+      elsif new_input.submitted
+        shell_cmd = new_input.text
+        new_output = CustomShellOutput::INITIAL.with(command: shell_cmd, running: true)
+        [
+          model.with(mode: :output, input: CustomShellInput::INITIAL, output: new_output),
+          Command.system(shell_cmd, :shell_output, stream: true),
+]
+      else
+        [model.with(input: new_input), cmd]
+      end
+
+    when :output
+      # Route streaming messages (strip :shell_output prefix)
+      routed = case message
+               in [:shell_output, *rest] then rest
+               else message
+      end
+
+      new_output, cmd = CustomShellOutput::UPDATE.call(routed, model.output)
+
+      if new_output.dismissed
+        [INITIAL, nil]
+      else
+        [model.with(output: new_output), cmd]
+      end
+
+    else
+      [model, nil]
+    end
+  end
+
+  def self.open
+    INITIAL.with(mode: :input, input: CustomShellInput::INITIAL)
+  end
+
+  def self.active?(model)
+    model.mode != :none
+  end
+end

data/examples/app_fractal_dashboard/bags/custom_shell_output.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# Streaming output bag for custom shell command modal.
+#
+# Displays interleaved stdout/stderr. Border color reflects exit status.
+# Sets dismissed: in model for parent to detect.
+module CustomShellOutput
+  Chunk = Data.define(:stream, :text)
+  Model = Data.define(:command, :chunks, :running, :exit_status, :dismissed)
+  INITIAL = Ractor.make_shareable(Model.new(command: "", chunks: [].freeze, running: false, exit_status: nil, dismissed: false))
+
+  VIEW = lambda do |model, tui|
+    # Build styled spans from chunks
+    spans = if model.chunks.empty? && model.running
+      [tui.text_span(content: "Running...", style: tui.style(fg: :dark_gray))]
+    else
+      model.chunks.map do |chunk|
+        style = (chunk.stream == :stderr) ? tui.style(fg: :yellow) : nil
+        tui.text_span(content: chunk.text, style:)
+      end
+    end
+
+    # Border color: green if exited 0, red if exited non-zero, default if running
+    border_style = case model.exit_status
+                   when nil then nil
+                   when 0 then tui.style(fg: :green)
+                   else tui.style(fg: :red)
+    end
+
+    left_title = model.running ? "ESC: Cancel" : "ESC: Dismiss"
+    display_cmd = (model.command.length > 60) ? "#{model.command[0..57]}..." : model.command
+
+    tui.center(
+      width_percent: 80,
+      height_percent: 80,
+      child: tui.overlay(
+        layers: [
+          tui.clear,
+          tui.block(
+            title: display_cmd,
+            titles: [
+              { content: left_title, position: :bottom, alignment: :left },
+              { content: "ENTER: Dismiss", position: :bottom, alignment: :right },
+            ],
+            borders: [:all],
+            border_style:,
+            children: [tui.paragraph(text: spans)]
+          ),
+        ]
+      )
+    )
+  end
+
+  UPDATE = lambda do |message, model|
+    case message
+    in [:stdout, chunk]
+      new_chunks = Ractor.make_shareable([*model.chunks, Chunk.new(stream: :stdout, text: chunk)].freeze)
+      [model.with(chunks: new_chunks), nil]
+
+    in [:stderr, chunk]
+      new_chunks = Ractor.make_shareable([*model.chunks, Chunk.new(stream: :stderr, text: chunk)].freeze)
+      [model.with(chunks: new_chunks), nil]
+
+    in [:complete, { status: }]
+      [model.with(running: false, exit_status: status), nil]
+
+    in [:error, { message: error_msg }]
+      new_chunks = Ractor.make_shareable([*model.chunks, Chunk.new(stream: :stderr, text: "Error: #{error_msg}\n")].freeze)
+      [model.with(chunks: new_chunks, running: false, exit_status: 1), nil]
+
+    in _ if message.respond_to?(:esc?) && message.esc?
+      [model.with(dismissed: true), nil]
+
+    in _ if message.respond_to?(:enter?) && message.enter?
+      [model.with(dismissed: true), nil]
+
+    else
+      [model, nil]
+    end
+  end
+end