ratatui_ruby-tea 0.3.1 → 0.4.0

data/lib/ratatui_ruby/tea.rb

@@ -6,6 +6,7 @@
 #++
 
 require_relative "tea/version"
+require_relative "tea/message"
 require_relative "tea/command"
 require_relative "tea/runtime"
 require_relative "tea/router"
@@ -24,35 +25,68 @@ module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
     # Starts the MVU event loop.
     #
     # Convenience delegator to Runtime.run. See Runtime for full documentation.
-    def self.run(...)
-      Runtime.run(...)
+    def self.run(root_fragment = nil, **)
+      Runtime.run(root_fragment, **)
+    end
+
+    # Normalizes Init callable return value to <tt>[model, command]</tt> tuple.
+    #
+    # Init callables use DWIM syntax. They can return just a model, just a command,
+    # or a full <tt>[model, command]</tt> tuple.
+    #
+    # This method handles all formats. Use it when composing child fragment Inits
+    # in fractal architecture.
+    #
+    # [result] The Init return value.
+    #
+    # === Examples
+    #
+    #--
+    # SPDX-SnippetBegin
+    # SPDX-FileCopyrightText: 2026 Kerrick Long
+    # SPDX-License-Identifier: MIT-0
+    #++
+    #   # Parent fragment composes children
+    #   Init = ->(theme:) do
+    #     stats_model, stats_cmd = Tea.normalize_init(StatsPanel::Init.(theme: theme))
+    #     network_model, network_cmd = Tea.normalize_init(NetworkPanel::Init.(theme: theme))
+    #
+    #     model = Model.new(stats: stats_model, network: network_model)
+    #     command = Command.batch(stats_cmd, network_cmd)
+    #     [model, command]
+    #   end
+    #--
+    # SPDX-SnippetEnd
+    #++
+    def self.normalize_init(result)
+      Runtime.normalize_init(result)
     end
 
     # Wraps a command with a routing prefix.
     #
-    # Parent bags trigger child bag commands. The results need routing back
-    # to the correct child bag. Manually wrapping every command is tedious.
+    # Parent fragments trigger child fragment commands. The results need routing back
+    # to the correct child fragment. Manually wrapping every command is tedious.
     #
     # This method prefixes command results automatically. Use it to route
-    # child bag command results in Fractal Architecture.
+    # child fragment command results in Fractal Architecture.
     #
-    # [command] The child bag command to wrap.
+    # [command] The child fragment command to wrap.
     # [prefix] Symbol prepended to results (e.g., <tt>:stats</tt>).
     #
     # === Example
     #
     #   # Verbose:
-    #   Command.map(child_bag.fetch_command) { |r| [:stats, *r] }
+    #   Command.map(child_fragment.fetch_command) { |r| [:stats, *r] }
     #
     #   # Concise:
-    #   Tea.route(child_bag.fetch_command, :stats)
+    #   Tea.route(child_fragment.fetch_command, :stats)
     def self.route(command, prefix)
       Command.map(command) { |result| [prefix, *result] }
     end
 
-    # Delegates a prefixed message to a child bag's UPDATE.
+    # Delegates a prefixed message to a child fragment's UPDATE.
     #
-    # Parent bag UPDATE functions route messages to child bags. Each route
+    # Parent fragment UPDATE functions route messages to child fragments. Each route
     # requires pattern matching, calling the child, and rewrapping any returned
     # command. The boilerplate adds up fast.
     #

data/rbs_collection.lock.yaml

@@ -17,14 +17,6 @@ gems:
   version: '0'
   source:
     type: stdlib
-- name: dbm
-  version: '0'
-  source:
-    type: stdlib
-- name: erb
-  version: '0'
-  source:
-    type: stdlib
 - name: ffi
   version: 1.17.3
   source:
@@ -77,16 +69,8 @@ gems:
   version: 1.7.0
   source:
     type: rubygems
-- name: pstore
-  version: '0'
-  source:
-    type: stdlib
-- name: psych
-  version: '0'
-  source:
-    type: stdlib
 - name: ratatui_ruby
-  version: 0.10.1
+  version: 0.10.2
   source:
     type: rubygems
 - name: ratatui_ruby-devtools

data/sig/concurrent.rbs

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+
+# Minimal stubs for concurrent-ruby-edge types used by Tea.
+# This is not a complete type definition — just enough for Steep.
+
+module Concurrent
+  module Promises
+    # Factory for resolvable events.
+    def self.resolvable_event: () -> ResolvableEvent
+
+    # A future/event that can be resolved by user code.
+    class ResolvableEvent
+      def resolve: (?bool wait, ?bool raise_on_reassign) -> self
+      def resolved?: () -> bool
+      def wait: (?Numeric? timeout) -> self
+    end
+
+    # Thread-safe FIFO channel for message passing.
+    class Channel
+      def initialize: (?Integer capacity) -> void
+      def push: (untyped message, ?Numeric? timeout) -> self
+      def pop: (?Numeric? timeout, ?untyped timeout_value) -> untyped
+      def try_pop: (?untyped no_value) -> untyped
+    end
+
+    # Represents a value that may not yet be available.
+    class Future[T]
+      def pending?: () -> bool
+      def resolved?: () -> bool
+      def rejected?: () -> bool
+      def wait: (?Numeric? timeout) -> self
+      def value: () -> T?
+      def reason: () -> Exception?
+    end
+
+    # Factory method for creating futures.
+    def self.future: [T] () { () -> T } -> Future[T]
+
+    # Races multiple futures/events, returning when any resolves.
+    def self.any_event: (*Future[untyped] | ResolvableEvent) -> ResolvableEvent
+  end
+
+  # Single-element blocking container for synchronization.
+  class MVar
+    TIMEOUT: Symbol
+
+    def initialize: (?untyped initial_value) -> void
+    def put: (untyped value) -> void
+    def take: (?Numeric? timeout) -> untyped
+  end
+
+  # Cooperative cancellation abstraction.
+  class Cancellation
+    def self.new: (?Promises::ResolvableEvent origin) -> [Cancellation, Promises::ResolvableEvent]
+    def self.timeout: (Numeric seconds) -> Cancellation
+
+    def origin: () -> Promises::ResolvableEvent
+    def canceled?: () -> bool
+    def check!: (?Class error) -> self
+    def join: (*Cancellation cancellations) -> Cancellation
+  end
+
+  # Thread-safe hash implementation.
+  class Map[K, V]
+    def initialize: () -> void
+    def []: (K key) -> V?
+    def []=: (K key, V value) -> V
+    def delete: (K key) -> V?
+    def each: () { (K, V) -> void } -> self
+  end
+end

data/sig/ratatui_ruby/tea/command.rbs

@@ -14,7 +14,7 @@ module RatatuiRuby
 
         # Execute the command's side effect.
         # Push result messages via the outlet.
-        def call: (Outlet out, CancellationToken token) -> void
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
 
         # Grace period for cooperative cancellation (seconds).
         # Runtime waits this long before force-killing the thread.
@@ -42,7 +42,7 @@ module RatatuiRuby
         def stream?: () -> bool
 
         # Executes the shell command and sends results via outlet.
-        def call: (Outlet out, CancellationToken token) -> void
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
 
         def self.new: (command: String, tag: (Symbol | Class), stream: bool) -> instance
       end
@@ -59,7 +59,7 @@ module RatatuiRuby
         def tea_cancellation_grace_period: () -> Float
 
         # Executes the inner command and transforms the result.
-        def call: (Outlet out, CancellationToken token) -> void
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
 
         def self.new: (inner_command: execution, mapper: ^(Array[untyped]) -> Array[untyped]) -> instance
       end
@@ -85,6 +85,9 @@ module RatatuiRuby
       # Creates a quit command.
       def self.exit: () -> Exit
 
+      # Creates a fresh cancellation that never fires.
+      def self.uncancellable: () -> Concurrent::Cancellation
+
       # Creates a shell execution command.
       def self.system: (String command, (Symbol | Class) tag, ?stream: bool) -> System
 
@@ -98,45 +101,37 @@ module RatatuiRuby
       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.custom: (^(Outlet, Concurrent::Cancellation) -> void callable, ?grace_period: Float?) -> _Command
+                     | (?grace_period: Float?) { (Outlet, Concurrent::Cancellation) -> void } -> _Command
 
-        def self.new: (callable: ^(Outlet, CancellationToken) -> void, grace_period: Float?) -> instance
-        def call: (Outlet out, CancellationToken token) -> void
-      end
+      # Creates a one-shot timer command.
+      def self.wait: (Float seconds, Symbol tag) -> Wait
 
-      # Cooperative cancellation mechanism for long-running commands.
-      class CancellationToken
-        # Number of times cancel! has been called.
-        attr_reader cancel_count: Integer
+      # Alias for wait, semantically used for recurring timers.
+      def self.tick: (Float seconds, Symbol tag) -> Wait
 
-        def self.new: () -> instance
+      # One-shot timer command that waits, then sends a message.
+      class Wait < Data
+        include Custom
 
-        # Signals cancellation. Thread-safe.
-        def cancel!: () -> void
+        attr_reader seconds: Float
+        attr_reader tag: Symbol
 
-        # Checks if cancellation was requested. Thread-safe.
-        def cancelled?: () -> bool
+        def self.new: (seconds: Float, tag: Symbol) -> instance
 
-        # Null object for commands that ignore cancellation.
-        class NoneToken < Data
-          attr_reader cancelled?: bool
+        # Execute the timer with cooperative cancellation.
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
+      end
 
-          def self.new: (cancelled?: bool) -> instance
+      # Private wrapper for Command.custom.
+      class Wrapped < Data
+        include Custom
 
-          # Does nothing. Ignores cancellation requests.
-          def cancel!: () -> nil
-        end
+        attr_reader callable: ^(Outlet, Concurrent::Cancellation) -> void
+        attr_reader grace_period: Float?
 
-        # Singleton null token.
-        NONE: NoneToken
+        def self.new: (callable: ^(Outlet, Concurrent::Cancellation) -> void, grace_period: Float?) -> instance
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
       end
 
       # Mixin for user-defined custom commands.
@@ -149,15 +144,124 @@ module RatatuiRuby
         def tea_cancellation_grace_period: () -> Float
       end
 
+      # Minimal interface for callables accepted by Lifecycle.run_sync.
+      interface _Callable
+        def call: (Outlet out, Concurrent::Cancellation token) -> void
+        def respond_to?: (Symbol, ?bool) -> bool
+        def tea_cancellation_grace_period: () -> Float
+      end
+
+      # Manages command execution with lifecycle support.
+      class Lifecycle
+        # Internal representation of a tracked async command.
+        class Entry < Data
+          attr_reader future: Concurrent::Promises::Future[void]
+          attr_reader origin: Concurrent::Promises::ResolvableEvent
+
+          def self.new: (future: Concurrent::Promises::Future[void], origin: Concurrent::Promises::ResolvableEvent) -> instance
+        end
+
+        @active: Concurrent::Map[_Callable, Entry]
+
+        def initialize: () -> void
+
+        # Runs a command synchronously, returning its result.
+        def run_sync: (_Callable command, Concurrent::Cancellation token, timeout: Float) -> Object?
+
+        # Runs a command asynchronously, tracking it for later cancellation.
+        def run_async: (_Callable command, Concurrent::Promises::Channel channel) -> Entry
+
+        # Cancels a running command, waiting for its grace period.
+        def cancel: (_Callable command) -> void
+
+        # Cancels all active commands and waits for them to complete.
+        def shutdown: () -> void
+      end
+
       # Messaging gateway for custom commands.
       class Outlet
-        @queue: Thread::Queue[Array[untyped]]
+        @channel: Concurrent::Promises::Channel
+        @live: Lifecycle
 
-        def initialize: (Thread::Queue[Array[untyped]] queue) -> void
+        def initialize: (Concurrent::Promises::Channel channel, lifecycle: Lifecycle) -> void
 
-        # Sends a tagged message to the runtime.
-        def put: (Symbol tag, *untyped payload) -> void
+        # Internal infrastructure for nested command lifecycle sharing.
+        attr_reader live: Lifecycle
+
+        # Sends a message to the runtime.
+        def put: (*Object args) -> void
+
+        # Runs a child command synchronously, returning its result.
+        def source: (_Callable command, Concurrent::Cancellation token, ?timeout: Float) -> Object?
+      end
+
+      # A fire-and-forget parallel command.
+      class Batch
+        include Custom
+
+        attr_reader commands: Array[Custom]
+
+        def self.new: (*Custom | Array[Custom]) -> instance
+
+        def call: (Outlet outlet, Concurrent::Cancellation token) -> void
+      end
+
+      # Creates a parallel batch command.
+      def self.batch: (*Custom | Array[Custom]) -> Batch
+
+      # An aggregating parallel command.
+      class All
+        include Custom
+
+        attr_reader tag: Symbol
+        attr_reader commands: Array[Custom]
+        attr_reader nested: bool
+
+        def self.new: (Symbol tag, *Custom | Array[Custom]) -> instance
+
+        def call: (Outlet outlet, Concurrent::Cancellation token) -> void
+      end
+
+      # Creates an aggregating parallel command.
+      def self.all: (Symbol tag, *Custom | Array[Custom]) -> All
+
+      # HTTP response shapes for pattern matching
+      type http_success_shape = { type: :http, envelope: Symbol, status: Integer, body: String, headers: Hash[String, String] }
+      type http_error_shape = { type: :http, envelope: Symbol, error: String }
+
+      # HTTP response with deconstruct_keys for pattern matching.
+      class HttpResponse < Data
+        attr_reader envelope: Symbol
+        attr_reader status: Integer?
+        attr_reader body: String?
+        attr_reader headers: Hash[String, String]?
+        attr_reader error: String?
+
+        def self.new: (envelope: Symbol, status: Integer?, body: String?, headers: Hash[String, String]?, error: String?) -> instance
+
+        def deconstruct_keys: (Array[Symbol]?) -> (http_success_shape | http_error_shape)
       end
+
+      # An HTTP request command.
+      class Http < Data
+        include Custom
+
+        attr_reader method: Symbol
+        attr_reader url: String
+        attr_reader envelope: Symbol
+        attr_reader headers: Hash[String, String]?
+        attr_reader body: String?
+        attr_reader timeout: (Integer | Float)?
+
+        def self.new: (method: Symbol, url: String, envelope: Symbol, headers: Hash[String, String]?, body: String?, timeout: (Integer | Float)?) -> instance
+
+        def call: (Outlet outlet, Concurrent::Cancellation token) -> void
+      end
+
+      # Creates an HTTP request command.
+      # DWIM: accepts positional args, method keywords (get:, post:, etc.), or explicit keywords.
+      # See Http class and documentation for all supported patterns.
+      def self.http: (*(Symbol | String | nil), **(Symbol | String | Integer | Float | Hash[String, String] | ^(String, Hash[String, String]?, Integer?) -> Object | nil)) -> Http
     end
   end
 end

data/sig/ratatui_ruby/tea/message.rbs

@@ -0,0 +1,123 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    # Messages sent from commands to update functions.
+    module Message
+      # Fallback predicate mixin.
+      module Predicates
+        # Returns false for unknown predicate methods.
+        def method_missing: (Symbol name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
+
+        # Responds to all predicate methods.
+        def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
+      end
+
+      # System command response types.
+      module System
+        # Response from a system command (batch mode).
+        class Batch
+          include Predicates
+
+          attr_reader envelope: Symbol
+          attr_reader stdout: String
+          attr_reader stderr: String
+          attr_reader status: Integer
+
+          def initialize: (
+            envelope: Symbol,
+            stdout: String,
+            stderr: String,
+            status: Integer
+          ) -> void
+
+          def system?: () -> bool
+          def success?: () -> bool
+          def error?: () -> bool
+          def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+        end
+
+        # Streaming message from a system command.
+        class Stream
+          include Predicates
+
+          attr_reader envelope: Symbol
+          attr_reader stream: Symbol
+          attr_reader content: String?
+          attr_reader status: Integer?
+
+          def initialize: (
+            envelope: Symbol,
+            stream: Symbol,
+            content: String?,
+            status: Integer?
+          ) -> void
+
+          def system?: () -> bool
+          def stdout?: () -> bool
+          def stderr?: () -> bool
+          def complete?: () -> bool
+          def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+        end
+      end
+
+      # Response from a timer command.
+      class Timer
+        include Predicates
+
+        attr_reader envelope: Symbol
+        attr_reader elapsed: Float
+
+        def initialize: (envelope: Symbol, elapsed: Float) -> void
+
+        def timer?: () -> bool
+        def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+      end
+
+      # Response from an HTTP command.
+      class HttpResponse
+        include Predicates
+
+        attr_reader envelope: Symbol
+        attr_reader status: Integer?
+        attr_reader body: String?
+        attr_reader headers: Hash[String, String]?
+        attr_reader error: String?
+
+        def initialize: (
+          envelope: Symbol,
+          status: Integer?,
+          body: String?,
+          headers: Hash[String, String]?,
+          error: String?
+        ) -> void
+
+        def http?: () -> bool
+        def success?: () -> bool
+        def error?: () -> bool
+        def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+      end
+
+      # Response from Command.all aggregating parallel execution.
+      class All
+        include Predicates
+
+        attr_reader envelope: Symbol
+        attr_reader results: Array[untyped]
+        attr_reader nested: bool
+
+        def initialize: (
+          envelope: Symbol,
+          results: Array[untyped],
+          nested: bool
+        ) -> void
+
+        def all?: () -> bool
+        def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
+      end
+    end
+  end
+end

data/sig/ratatui_ruby/tea/router.rbs

@@ -15,7 +15,7 @@ module RatatuiRuby
         def with: (**Object) -> self
       end
 
-      # Interface for fractal child modules (bags).
+      # Interface for fractal child modules (fragments).
       # Routed modules must have an UPDATE constant that handles child messages.
       # NOTE: We use Module here because RBS interfaces can't declare class methods.
 

data/sig/ratatui_ruby/tea/runtime.rbs

@@ -8,7 +8,7 @@ module RatatuiRuby
     # MVU runtime event loop.
     class Runtime
       # Active command tracking entry.
-      type active_entry = { thread: Thread, token: Command::CancellationToken }
+      type active_entry = { future: Concurrent::Promises::Future[void], origin: Concurrent::Promises::ResolvableEvent }
 
       # Widget type accepted by view functions.
       type renderable = RatatuiRuby::_CustomWidget | RatatuiRuby::widget
@@ -17,6 +17,9 @@ module RatatuiRuby
       # Steep needs a union type (not interface) for is_a? narrowing.
       type update_result = [Object, Command::execution?] | Command::execution | Object
 
+      # Duck type for init result that can be normalized.
+      type init_result = [Object, Command::execution?] | Command::execution | Object
+
       # Duck type for values that can be queried for command-ness.
       interface _MaybeCommand
         def nil?: () -> bool
@@ -25,20 +28,50 @@ module RatatuiRuby
         def tea_command?: () -> bool
       end
 
-      # Starts the MVU event loop.
+      # Starts the MVU event loop (positional fragment).
       def self.run: [Model] (
+        ?Module? root_fragment,
+        ?fps: Integer
+      ) -> Model
+
+      # Starts the MVU event loop (explicit parameters).
+      | [Model] (
+        ?Module? root_fragment,
+        ?fps: Integer,
         model: Model,
         view: ^(Model, RatatuiRuby::TUI) -> renderable,
         update: ^(RatatuiRuby::Event, Model) -> update_result?,
-        ?init: (^() -> RatatuiRuby::Event)?
+        ?command: Command::execution?
       ) -> Model
 
+      # Starts the MVU event loop (explicit parameters without fps).
+      | [Model] (
+        ?Module? root_fragment,
+        model: Model,
+        view: ^(Model, RatatuiRuby::TUI) -> renderable,
+        update: ^(RatatuiRuby::Event, Model) -> update_result?,
+        ?command: Command::execution?
+      ) -> Model
+
+      # Normalizes Init callable return value to [model, command] tuple.
+      def self.normalize_init: [Model] (init_result result) -> [Model?, Command::execution?]
+      QUIT: Object
+
       private
 
-      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_view_return!: (renderable? widget) -> void
+      def self.normalize_update_return: [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?
+      def self.fragment_from_kwargs: (Module? root_fragment, ?model: untyped, ?view: untyped, ?update: untyped, ?command: untyped) -> Module
+      def self.fragment_invariant!: (String param) -> void
+      def self.init_callable: [Model] () -> ^() -> [Model?, Command::execution?]
+      def self.start_runtime: () -> untyped
+      def self.draw_view: () -> void
+      def self.handle_ratatui_event: () -> void
+      def self.handle_sync: () -> void
+      QUEUE_EMPTY: Object
+      def self.send_pending_messages: (?dispatch: bool) -> void
+      def self.dispatch_command: () -> void
     end
   end
 end

data/sig/ratatui_ruby/tea/test_helper.rbs

@@ -0,0 +1,12 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  module Tea
+    module TestHelper
+      def validate_tea_command!: (Runtime::_MaybeCommand) -> nil
+    end
+  end
+end