ratatui_ruby-tea 0.3.0 → 0.3.1

data/sig/examples/verify_readme_usage/app.rbs

@@ -13,7 +13,7 @@ class VerifyReadmeUsage
 
   VIEW: ^(Model, RatatuiRuby::TUI) -> untyped
 
-  UPDATE: ^(RatatuiRuby::Event, Model) -> (Model | [Model, RatatuiRuby::Tea::Cmd::Quit])
+  UPDATE: ^(RatatuiRuby::Event, Model) -> (Model | [Model, RatatuiRuby::Tea::Command::Exit])
 
   def run: () -> void
 end

data/sig/examples/widget_command_system/app.rbs

@@ -20,7 +20,7 @@ class WidgetCmdExec
   # Msg can be Event or [:got_output, Hash]
   type msg = RatatuiRuby::Event | [Symbol, Hash[Symbol, untyped]]
 
-  UPDATE: ^(msg, Model) -> (Model | [Model, RatatuiRuby::Tea::Cmd::execution?])
+  UPDATE: ^(msg, Model) -> (Model | [Model, RatatuiRuby::Tea::Command::execution?])
 
   def run: () -> void
 end

data/sig/open3.rbs

@@ -0,0 +1,17 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# Local shim for Open3 methods not in stdlib RBS.
+# The stdlib open3/0/open3.rbs only defines capture2e.
+# TODO: Remove when upstream RBS adds these methods.
+
+module Open3
+  # Executes a command and returns stdout, stderr, and status.
+  def self.capture3: (*String, ?stdin_data: String, ?binmode: boolish) -> [String, String, Process::Status]
+
+  # Executes a command with pipes for stdin, stdout, stderr.
+  def self.popen3: (*String) { (IO stdin, IO stdout, IO stderr, Thread wait_thr) -> void } -> Process::Status
+                 | (*String) -> [IO, IO, IO, Thread]
+end

data/sig/ratatui_ruby/tea/command.rbs

@@ -6,42 +6,158 @@
 module RatatuiRuby
   module Tea
     module Command
+      # Interface for user-defined custom commands.
+      # Any callable satisfying this interface can be dispatched.
+      interface _Command
+        # Brand predicate for update return disambiguation.
+        def tea_command?: () -> true
+
+        # Execute the command's side effect.
+        # Push result messages via the outlet.
+        def call: (Outlet out, CancellationToken token) -> void
+
+        # Grace period for cooperative cancellation (seconds).
+        # Runtime waits this long before force-killing the thread.
+        def tea_cancellation_grace_period: () -> Float
+      end
+
       # Sentinel value for application termination.
       class Exit < Data
         def self.new: () -> instance
       end
 
-      # Command to run a shell command via Open3.
+      # Runs a shell command and routes its output back as messages.
       class System < Data
         attr_reader command: String
         attr_reader tag: Symbol | Class
         attr_reader stream: bool
 
+        # Command identification for runtime dispatch.
+        def tea_command?: () -> true
+
+        # Grace period for cleanup after cancellation.
+        def tea_cancellation_grace_period: () -> Float
+
         # Returns true if streaming mode is enabled.
         def stream?: () -> bool
 
+        # Executes the shell command and sends results via outlet.
+        def call: (Outlet out, CancellationToken token) -> void
+
         def self.new: (command: String, tag: (Symbol | Class), stream: bool) -> instance
       end
 
       # Command that wraps another command's result with a transformation.
       class Mapped < Data
         attr_reader inner_command: execution
-        attr_reader mapper: ^(untyped) -> untyped
+        attr_reader mapper: ^(Array[untyped]) -> Array[untyped]
+
+        # Command identification for runtime dispatch.
+        def tea_command?: () -> true
+
+        # Grace period delegates to inner command.
+        def tea_cancellation_grace_period: () -> Float
+
+        # Executes the inner command and transforms the result.
+        def call: (Outlet out, CancellationToken token) -> void
 
-        def self.new: (inner_command: execution, mapper: ^(untyped) -> untyped) -> instance
+        def self.new: (inner_command: execution, mapper: ^(Array[untyped]) -> Array[untyped]) -> instance
+      end
+
+      # Sentinel value for command cancellation.
+      class Cancel < Data
+        attr_reader handle: _Command
+
+        def self.new: (handle: _Command) -> instance
+      end
+
+      # Sentinel value for command errors.
+      class Error < Data
+        attr_reader command: _Command
+        attr_reader exception: Exception
+
+        def self.new: (command: _Command, exception: Exception) -> instance
       end
 
       # Union type for all valid commands
-      type execution = Execute | Mapped
+      type execution = System | Mapped | _Command
 
       # Creates a quit command.
-      def self.exit: () -> Quit
+      def self.exit: () -> Exit
 
       # Creates a shell execution command.
       def self.system: (String command, (Symbol | Class) tag, ?stream: bool) -> System
 
       # Creates a mapped command for Fractal Architecture composition.
-      def self.map: (execution inner_command) { (untyped) -> untyped } -> Mapped
+      def self.map: (execution inner_command) { (Array[untyped]) -> Array[untyped] } -> Mapped
+
+      # Request cancellation of a running command.
+      def self.cancel: (_Command handle) -> Cancel
+
+      # Creates an error sentinel.
+      def self.error: (_Command command, Exception exception) -> Error
+
+      # Wraps a callable for unique identity per dispatch.
+      def self.custom: (^(Outlet, CancellationToken) -> void callable, ?grace_period: Float?) -> _Command
+                     | (?grace_period: Float?) { (Outlet, CancellationToken) -> void } -> _Command
+
+      # Private wrapper for Command.custom.
+      class Wrapped < Data
+        include Custom
+
+        attr_reader callable: ^(Outlet, CancellationToken) -> void
+        attr_reader grace_period: Float?
+
+        def self.new: (callable: ^(Outlet, CancellationToken) -> void, grace_period: Float?) -> instance
+        def call: (Outlet out, CancellationToken token) -> void
+      end
+
+      # Cooperative cancellation mechanism for long-running commands.
+      class CancellationToken
+        # Number of times cancel! has been called.
+        attr_reader cancel_count: Integer
+
+        def self.new: () -> instance
+
+        # Signals cancellation. Thread-safe.
+        def cancel!: () -> void
+
+        # Checks if cancellation was requested. Thread-safe.
+        def cancelled?: () -> bool
+
+        # Null object for commands that ignore cancellation.
+        class NoneToken < Data
+          attr_reader cancelled?: bool
+
+          def self.new: (cancelled?: bool) -> instance
+
+          # Does nothing. Ignores cancellation requests.
+          def cancel!: () -> nil
+        end
+
+        # Singleton null token.
+        NONE: NoneToken
+      end
+
+      # Mixin for user-defined custom commands.
+      module Custom
+        # Brand predicate for command identification.
+        def tea_command?: () -> true
+
+        # Cleanup time after cancellation is requested. In seconds.
+        # Default: 0.1 seconds (100 milliseconds).
+        def tea_cancellation_grace_period: () -> Float
+      end
+
+      # Messaging gateway for custom commands.
+      class Outlet
+        @queue: Thread::Queue[Array[untyped]]
+
+        def initialize: (Thread::Queue[Array[untyped]] queue) -> void
+
+        # Sends a tagged message to the runtime.
+        def put: (Symbol tag, *untyped payload) -> void
+      end
     end
   end
 end

data/sig/ratatui_ruby/tea/router.rbs

@@ -5,94 +5,150 @@
 
 module RatatuiRuby
   module Tea
-    # Interface for child bag modules (required by route).
-    interface _Bag[M]
-      def self.UPDATE: ^(top, M) -> [M, Command::execution?]
-      def self.INITIAL: M
-    end
-
     # Declarative DSL for Fractal Architecture.
     module Router
       def self.included: (Class base) -> void
 
-      # Guard callable: receives model, returns truthy/falsy.
-      type guard[M] = ^(M model) -> boolish
+      # Duck type for Data-like models that support `with`.
+      interface _DataModel
+        def public_send: (Symbol, *Object) -> Object
+        def with: (**Object) -> self
+      end
+
+      # Interface for fractal child modules (bags).
+      # Routed modules must have an UPDATE constant that handles child messages.
+      # NOTE: We use Module here because RBS interfaces can't declare class methods.
 
-      # Handler callable: returns a command or nil.
-      type handler = ^() -> Command::execution?
+      # Configuration for key handlers.
+      class KeyHandlerConfig < Data
+        attr_reader handler: (^() -> Command::execution?)?
+        attr_reader action: Symbol?
+        attr_reader route: Symbol?
+        attr_reader guard: (^(_DataModel) -> bool)?
 
-      # Click handler: receives x, y coordinates.
-      type click_handler = ^(Integer x, Integer y) -> Command::execution?
+        def initialize: (?handler: (^() -> Command::execution?)?, ?action: Symbol?, ?route: Symbol?, ?guard: (^(_DataModel) -> bool)?) -> void
+      end
 
-      # Key handler config stored in handlers hash.
-      type key_config[M] = {
-        handler: handler?,
-        action: Symbol?,
-        route: Symbol?,
-        guard: guard[M]?
-      }
+      # Configuration for scroll handlers (no coordinates).
+      class ScrollHandlerConfig < Data
+        attr_reader handler: (^() -> Command::execution?)?
+        attr_reader action: Symbol?
 
-      # Mouse handler config.
-      type mouse_config = {
-        handler: handler | click_handler,
-        action: Symbol?
-      }
+        def initialize: (?handler: (^() -> Command::execution?)?, ?action: Symbol?) -> void
+      end
+
+      # Configuration for click handlers (x, y coordinates).
+      class ClickHandlerConfig < Data
+        attr_reader handler: (^(Integer, Integer) -> Command::execution?)?
+        attr_reader action: Symbol?
+
+        def initialize: (?handler: (^(Integer, Integer) -> Command::execution?)?, ?action: Symbol?) -> void
+      end
 
       # Class methods added when Router is included.
-      module ClassMethods
-        def route: [M] (Symbol | String prefix, to: _Bag[M]) -> void
+      module ClassMethods : Module
+        @routes: Hash[Symbol, Module]
+        @actions: Hash[Symbol, ^() -> Command::execution?]
+        @key_handlers: Hash[String, KeyHandlerConfig]
+        @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+        @click_handler: ClickHandlerConfig?
+
+        def route: (Symbol | String prefix, to: Module) -> void
         def routes: () -> Hash[Symbol, Module]
 
-        def action: (Symbol | String name, handler) -> void
-        def actions: () -> Hash[Symbol, handler]
+        def action: (Symbol | String name, ^() -> Command::execution? handler) -> void
+        def actions: () -> Hash[Symbol, ^() -> Command::execution?]
 
-        def keymap: () { () -> void } -> void
-        def key_handlers: [M] () -> Hash[String, key_config[M]]
+        def keymap: () { (KeymapBuilder) [self: KeymapBuilder] -> void } -> void
+        def key_handlers: () -> Hash[String, KeyHandlerConfig]
 
-        def mousemap: () { () -> void } -> void
-        def mouse_handlers: () -> Hash[Symbol, mouse_config]
+        def mousemap: () { (MousemapBuilder) [self: MousemapBuilder] -> void } -> void
+        def scroll_handlers: () -> Hash[Symbol, ScrollHandlerConfig]
+        def click_handler: () -> ClickHandlerConfig?
 
-        # Generates an UPDATE lambda from routes, keymap, and mousemap.
-        def from_router: [M, Msg] () -> ^(Msg message, M model) -> [M, Command::execution?]
+        # Returns UPDATE callable that handles routing.
+        # Uses is_a? checks for Event::Key and Event::Mouse type narrowing.
+        # Model must be Data-like with `with` and field accessors.
+        def from_router: () -> RouterUpdate
+      end
+
+      # UPDATE callable returned by from_router with proper typing.
+      # Implements #call to satisfy Proc-like interfaces.
+      class RouterUpdate
+        @routes: Hash[Symbol, Module]
+        @actions: Hash[Symbol, ^() -> Command::execution?]
+        @key_handlers: Hash[String, KeyHandlerConfig]
+        @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+        @click_handler: ClickHandlerConfig?
+
+        def initialize: (
+          routes: Hash[Symbol, Module],
+          actions: Hash[Symbol, ^() -> Command::execution?],
+          key_handlers: Hash[String, KeyHandlerConfig],
+          scroll_handlers: Hash[Symbol, ScrollHandlerConfig],
+          click_handler: ClickHandlerConfig?
+        ) -> void
+
+        # Process message and return [model, command] tuple.
+        def call: (
+          (RatatuiRuby::Event::Key | RatatuiRuby::Event::Mouse | Array[Object]) message,
+          _DataModel model
+        ) -> [_DataModel, Command::execution?]
       end
 
       # Builder for keymap DSL.
       class KeymapBuilder
-        @handlers: Hash[String, key_config[top]]
+        @handlers: Hash[String, KeyHandlerConfig]
+        @guard_stack: Array[^(_DataModel) -> bool]
 
-        attr_reader handlers: Hash[String, key_config[top]]
+        attr_reader handlers: Hash[String, KeyHandlerConfig]
 
         def initialize: () -> void
 
-        # Registers a key handler with optional guards.
-        def key: [M] (
+        def key: (
           String | Symbol key_name,
-          handler | Symbol handler_or_action,
+          (^() -> Command::execution?) | Symbol handler_or_action,
           ?route: Symbol?,
-          ?when: guard[M]?,
-          ?if: guard[M]?,
-          ?only: guard[M]?,
-          ?guard: guard[M]?,
-          ?unless: guard[M]?,
-          ?except: guard[M]?,
-          ?skip: guard[M]?
+          ?when: (^(_DataModel) -> bool)?,
+          ?if: (^(_DataModel) -> bool)?,
+          ?only: (^(_DataModel) -> bool)?,
+          ?guard: (^(_DataModel) -> bool)?,
+          ?unless: (^(_DataModel) -> bool)?,
+          ?except: (^(_DataModel) -> bool)?,
+          ?skip: (^(_DataModel) -> bool)?
         ) -> void
+
+        def only: (
+          ?when: (^(_DataModel) -> bool)?,
+          ?if: (^(_DataModel) -> bool)?,
+          ?only: (^(_DataModel) -> bool)?,
+          ?guard: (^(_DataModel) -> bool)?
+        ) { () -> void } -> void
+
+        def skip: (
+          ?when: (^(_DataModel) -> bool)?,
+          ?if: (^(_DataModel) -> bool)?,
+          ?skip: (^(_DataModel) -> bool)?,
+          ?guard: (^(_DataModel) -> bool)?
+        ) { () -> void } -> void
+
+        private
+
+        def with_guard: ((^(_DataModel) -> bool)?) { () -> void } -> void
       end
 
       # Builder for mousemap DSL.
       class MousemapBuilder
-        @handlers: Hash[Symbol, mouse_config]
+        @scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+        @click_handler: ClickHandlerConfig?
 
-        attr_reader handlers: Hash[Symbol, mouse_config]
+        attr_reader scroll_handlers: Hash[Symbol, ScrollHandlerConfig]
+        attr_reader click_handler: ClickHandlerConfig?
 
         def initialize: () -> void
 
-        def click: (click_handler | Symbol handler_or_action) -> void
-        def scroll: (:up | :down direction, handler | Symbol handler_or_action) -> void
-
-        private
-
-        def register: (Symbol key, handler | click_handler | Symbol handler_or_action) -> void
+        def click: ((^(Integer, Integer) -> Command::execution?) | Symbol handler_or_action) -> void
+        def scroll: (:up | :down direction, (^() -> Command::execution?) | Symbol handler_or_action) -> void
       end
     end
   end

data/sig/ratatui_ruby/tea/runtime.rbs

@@ -5,22 +5,40 @@
 
 module RatatuiRuby
   module Tea
+    # MVU runtime event loop.
     class Runtime
+      # Active command tracking entry.
+      type active_entry = { thread: Thread, token: Command::CancellationToken }
+
+      # Widget type accepted by view functions.
+      type renderable = RatatuiRuby::_CustomWidget | RatatuiRuby::widget
+
+      # Duck type for update result that can be normalized.
+      # Steep needs a union type (not interface) for is_a? narrowing.
+      type update_result = [Object, Command::execution?] | Command::execution | Object
+
+      # Duck type for values that can be queried for command-ness.
+      interface _MaybeCommand
+        def nil?: () -> bool
+        def class: () -> Class
+        def respond_to?: (Symbol, ?bool) -> bool
+        def tea_command?: () -> bool
+      end
+
       # Starts the MVU event loop.
-      def self.run: [M, Msg] (
-        model: M,
-        view: ^(M model, RatatuiRuby::TUI tui) -> untyped,
-        update: ^(Msg msg, M model) -> (M | [M, Cmd::execution?] | [M, Cmd::Quit] | [M, nil]),
-        ?init: ^() -> Msg
-      ) -> M
+      def self.run: [Model] (
+        model: Model,
+        view: ^(Model, RatatuiRuby::TUI) -> renderable,
+        update: ^(RatatuiRuby::Event, Model) -> update_result?,
+        ?init: (^() -> RatatuiRuby::Event)?
+      ) -> Model
 
       private
 
-      def self.validate_view_result!: (untyped widget) -> void
-      def self.normalize_update_result: [M] (untyped result, M previous_model) -> [M, untyped]
-      def self.valid_cmd?: (untyped value) -> bool
-      def self.validate_ractor_shareable!: (untyped object, String name) -> void
-      def self.dispatch: (untyped cmd, Queue queue) -> void
+      def self.validate_view_result!: (renderable? widget) -> void
+      def self.normalize_update_result: [Model] (update_result? result, Model previous_model) -> [Model, Command::execution?]
+      def self.validate_ractor_shareable!: [T] (T object, String name) -> void
+      def self.dispatch: (Command::execution command, Queue[Array[Symbol | Hash[Symbol, String | Integer]]], ?Hash[Command::_Command, active_entry] active_commands) -> Thread?
     end
   end
 end

data/sig/ratatui_ruby/tea/shortcuts.rbs

@@ -0,0 +1,18 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    # Convenient short aliases for Tea APIs.
+    module Shortcuts
+      # Short alias for Command.
+      module Cmd
+        def self.exit: () -> Command::Exit
+        def self.sh: (String command, Symbol | Class tag) -> Command::System
+        def self.map: (Command::execution inner_command) { (Array[untyped]) -> Array[untyped] } -> Command::Mapped
+      end
+    end
+  end
+end

data/sig/ratatui_ruby/tea/version.rbs

@@ -0,0 +1,10 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    VERSION: String
+  end
+end

data/sig/ratatui_ruby/tea.rbs

@@ -4,13 +4,25 @@
 #++
 
 module RatatuiRuby
+  # The Elm Architecture for RatatuiRuby.
   module Tea
-    # See RatatuiRuby::Tea::Runtime.run
-    def self.run: [M, Msg] (
-      model: M,
-      view: ^(M model, RatatuiRuby::TUI tui) -> untyped,
-      update: ^(Msg msg, M model) -> (M | [M, Cmd::execution?] | [M, Cmd::Quit] | [M, nil]),
-      ?init: ^() -> Msg
-    ) -> M
+    # Starts the MVU event loop.
+    def self.run: [Model] (
+      model: Model,
+      view: ^(Model, RatatuiRuby::TUI) -> (RatatuiRuby::_CustomWidget | RatatuiRuby::widget),
+      update: ^(RatatuiRuby::Event, Model) -> Runtime::update_result?,
+      ?init: (^() -> untyped)?
+    ) -> Model
+
+    # Wraps a command with a routing prefix.
+    def self.route: (Command::execution command, Symbol prefix) -> Command::Mapped
+
+    # Delegates a prefixed message to a child bag's UPDATE.
+    def self.delegate: (
+      untyped message,
+      Symbol prefix,
+      ^(Array[untyped]?, untyped) -> [untyped, Command::execution?] child_update,
+      untyped child_model
+    ) -> ([untyped, Command::execution?] | nil)
   end
 end

data/tasks/steep.rake

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+desc "Run Steep type checker"
+task :steep do
+  sh "bundle exec steep check"
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ratatui_ruby-tea
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Kerrick Long
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.1
+        version: 0.10.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.1
+        version: 0.10.1
 - !ruby/object:Gem::Dependency
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +94,8 @@ files:
 - Steepfile
 - doc/concepts/application_architecture.md
 - doc/concepts/application_testing.md
+- doc/contributors/design/commands_and_outlets.md
+- doc/contributors/kit-no-outlet.md
 - doc/contributors/priorities.md
 - doc/custom.css
 - doc/getting_started/quickstart.md
@@ -123,21 +125,30 @@ files:
 - exe/.gitkeep
 - lib/ratatui_ruby/tea.rb
 - lib/ratatui_ruby/tea/command.rb
+- lib/ratatui_ruby/tea/command/cancellation_token.rb
+- lib/ratatui_ruby/tea/command/custom.rb
+- lib/ratatui_ruby/tea/command/outlet.rb
 - lib/ratatui_ruby/tea/router.rb
 - lib/ratatui_ruby/tea/runtime.rb
 - lib/ratatui_ruby/tea/shortcuts.rb
 - lib/ratatui_ruby/tea/version.rb
 - mise.toml
+- rbs_collection.lock.yaml
+- rbs_collection.yaml
 - sig/examples/verify_readme_usage/app.rbs
 - sig/examples/widget_command_system/app.rbs
+- sig/open3.rbs
 - sig/ratatui_ruby/tea.rbs
 - sig/ratatui_ruby/tea/command.rbs
 - sig/ratatui_ruby/tea/router.rbs
 - sig/ratatui_ruby/tea/runtime.rbs
+- sig/ratatui_ruby/tea/shortcuts.rbs
+- sig/ratatui_ruby/tea/version.rbs
 - tasks/example_viewer.html.erb
 - tasks/resources/build.yml.erb
 - tasks/resources/index.html.erb
 - tasks/resources/rubies.yml
+- tasks/steep.rake
 - vendor/goodcop/base.yml
 homepage: https://sr.ht/~kerrick/ratatui_ruby/
 licenses: