ratatui_ruby-tea 0.3.1 → 0.4.0

data/lib/ratatui_ruby/tea/runtime.rb

@@ -6,6 +6,7 @@
 #++
 
 require "ratatui_ruby"
+require "concurrent-edge"
 
 module RatatuiRuby
   module Tea
@@ -38,224 +39,358 @@ module RatatuiRuby
       #
       # Runs until the update function returns a <tt>Command.exit</tt> command.
       #
-      # [model] Initial application state (immutable).
-      # [view] Callable receiving <tt>(model, tui)</tt>, returns a widget.
-      # [update] Callable receiving <tt>(message, model)</tt>, returns <tt>[new_model, command]</tt> or just <tt>new_model</tt>.
-      # [init] Optional callable to run at startup. Returns a message for update.
-      def self.run(model:, view:, update:, init: nil)
-        validate_ractor_shareable!(model, "model")
-
-        # Execute init command synchronously if provided
-        if init
-          init_message = init.call
-          result = update.call(init_message, model)
-          model, _command = normalize_update_result(result, model)
-          validate_ractor_shareable!(model, "model")
-        end
+      # == Root Fragment with Init
+      #
+      # Pass a fragment module with <tt>Init</tt>, <tt>Update</tt>, and <tt>View</tt> constants.
+      # This allows your application to do work at startup, and your Update will be called with the result.
+      # It also allows you to create a more complex model with access to <tt>ARGV</tt> and <tt>ENV</tt>.
+      #
+      #   module MyApp
+      #     # Init is any callable, and returns an immutable Model and/or Command, according to your application's needs.
+      #     # The Model is your application's initial state, and the Command is any command to run at startup.
+      #     Init = -> () {
+      #       # To do work at startup:
+      #       return [Data.define(:count).new(count: 0), Command.http("https://api.example.com/data")]
+      #       # To start idle:
+      #       return Data.define(:count).new(count: 0)
+      #     }
+      #
+      #     # Update has access to a single Message, and your fragment's latest immutable Model.
+      #     # It returns a new Model and/or a Command, according to your application's needs.
+      #     Update = ->(message, model) {
+      #       [model, Command.exit]
+      #     }
+      #
+      #     # View has access to your fragment's latest immutable Model, and a RatatuiRuby::TUI.
+      #     # It returns a tree of RatatuiRuby::Widget and/or Custom Widgets.
+      #     View = ->(model, tui) {
+      #       tui.paragraph(text: model.count.to_s)
+      #     }
+      #   end
+      #
+      #   Tea.run(MyApp)
+      #
+      # == Root Fragment with auto-Init
+      #
+      # Pass a fragment module with a <tt>Model</tt> class and <tt>Update</tt> and <tt>View</tt> constants.
+      # Your application will be idle until a RatatuiRuby::Event message is sent to your Update.
+      #
+      #   module MyApp
+      #     # Model is anything that responds to <tt>new</tt>.
+      #     Model = Data.define(:count).new(count: 0)
+      #
+      #     # Update has access to a single Message, and your fragment's latest immutable Model.
+      #     # It returns a new Model and/or a Command, according to your application's needs.
+      #     Update = ->(message, model) {
+      #       [model, Command.exit]
+      #     }
+      #
+      #     # View has access to your fragment's latest immutable Model, and a RatatuiRuby::TUI.
+      #     # It returns a tree of RatatuiRuby::Widget and/or Custom Widgets.
+      #     View = ->(model, tui) {
+      #       tui.paragraph(text: model.count.to_s)
+      #     }
+      #   end
+      #
+      #   Tea.run(MyApp)
+      #
+      # == Explicit Parameters API
+      #
+      # A root fragment is not required. You can pass individual parameters:
+      #
+      #   Tea.run(
+      #     model: MyApp::Model.new(count: 0),
+      #     view: MyApp::View,
+      #     update: MyApp::Update,
+      #     command: Command.http("https://api.example.com/data")
+      #   )
+      #
+      # == Parameters
+      #
+      # [root_fragment] Module with Model, Init, Update, View constants. *Mutually exclusive with model/view/update.*
+      # [fps] Target frames per second for the application. Higher values feel more responsive, but may spike CPU usage.
+      # [model] Initial application state (immutable). *Required if fragment not provided.*
+      # [view] Callable receiving <tt>(model, tui)</tt>, returns a widget. *Required if fragment not provided.*
+      # [update] Callable receiving <tt>(message, model)</tt>, returns <tt>[new_model, command]</tt> or just <tt>new_model</tt>. *Required if fragment not provided.*
+      # [command] Optional callable to run at startup. Returns a message for update.
+      #
+      # == Raises
+      #
+      # [RatatuiRuby::Error::Invariant] If both fragment and any of (model, view, update, command) are provided.
+      def self.run(root_fragment = nil, fps: 60, model: nil, view: nil, update: nil, command: nil)
+        @fragment = fragment_from_kwargs(root_fragment, model:, view:, update:, command:)
+        @view = @fragment::View
+        @update = @fragment::Update
+        @model, @command = init_callable.call
+        @timeout = 1 / fps
 
-        queue = Queue.new
-        pending_threads = [] #: Array[Thread]
-        active_commands = {} #: Hash[Command::_Command, active_entry]
-
-        catch(:quit) do
-          RatatuiRuby.run do |tui|
-            loop do
-              tui.draw do |frame|
-                widget = view.call(model, tui)
-                validate_view_result!(widget)
-                frame.render_widget(widget, frame.area)
-              end
+        # commands do significant work, so they run off the main thread
+        validate_ractor_shareable!(@command, "command")
+        # models get passed to and from commands on other threads
+        validate_ractor_shareable!(@model, "model")
+        # views and updates run on the main thread, so they don't need to be shareable
 
-              # 1. Handle user input (blocks up to 16ms)
-              message = tui.poll_event
+        start_runtime
+      end
 
-              # If provided, handle the event
-              unless message.is_a?(RatatuiRuby::Event::None)
-                result = update.call(message, model)
-                model, command = normalize_update_result(result, model)
-                validate_ractor_shareable!(model, "model")
-                throw :quit if command.is_a?(Command::Exit)
+      # Normalizes Init callable return value to <tt>[model, command]</tt> tuple.
+      #
+      # Init callables return initial state and optional startup command. They can use
+      # DWIM (Do What I Mean) syntax: return just a model, just a command, or a full tuple.
+      #
+      # This method handles all formats. Use it when composing child fragment Inits.
+      #
+      # [result] The Init return value (model, command, or <tt>[model, command]</tt> tuple).
+      #
+      # === Examples
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   # Just model
+      #   model, cmd = Tea.normalize_init(Model.new(...))
+      #   # => [Model.new(...), nil]
+      #
+      #   # Just command
+      #   model, cmd = Tea.normalize_init(Command.http(...))
+      #   # => [nil, Command.http(...)]
+      #
+      #   # Tuple (already normalized)
+      #   model, cmd = Tea.normalize_init([Model.new(...), Command.http(...)])
+      #   # => [Model.new(...), Command.http(...)]
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def self.normalize_init(result)
+        normalize_update_return(result, nil)
+      end
 
-                thread = dispatch(command, queue, active_commands) if command
-                pending_threads << thread if thread
-              end
+      # Sentinel value avoids accidentally quitting from application exceptions.
+      QUIT = Object.new.freeze
 
-              # 2. Check for synthetic events (Sync)
-              # This comes AFTER poll_event so Sync waits for commands dispatched
-              # by the preceding event (e.g., inject_key("a"); inject_sync)
-              if RatatuiRuby::SyntheticEvents.pending?
-                synthetic = RatatuiRuby::SyntheticEvents.pop
-                if synthetic&.sync?
-                  # Wait for all pending threads to complete
-                  pending_threads.each(&:join)
-                  pending_threads.clear
-
-                  # Yield to ensure any final queue writes are visible
-                  Thread.pass
-
-                  # Process all pending queue items
-                  until queue.empty?
-                    begin
-                      background_message = queue.pop(true)
-                      result = update.call(background_message, model)
-                      model, command = normalize_update_result(result, model)
-                      validate_ractor_shareable!(model, "model")
-                      throw :quit if command.is_a?(Command::Exit)
-
-                      thread = dispatch(command, queue, active_commands) if command
-                      pending_threads << thread if thread
-                    rescue ThreadError
-                      break
-                    end
-                  end
-                end
-              end
+      class << self
+        private def start_runtime
+          @message_queue = Concurrent::Promises::Channel.new
+          @pending_futures = [] #: Array[Concurrent::Promises::Future[void]]
+          @lifecycle = Command::Lifecycle.new
 
-              # 3. Check for background outcomes (non-blocking)
-              until queue.empty?
-                begin
-                  background_message = queue.pop(true)
-                  result = update.call(background_message, model)
-                  model, command = normalize_update_result(result, model)
-                  validate_ractor_shareable!(model, "model")
-                  throw :quit if command.is_a?(Command::Exit)
-
-                  thread = dispatch(command, queue, active_commands) if command
-                  pending_threads << thread if thread
-                rescue ThreadError
-                  break
-                end
+          catch(QUIT) do
+            dispatch_command
+            RatatuiRuby.run do |tui|
+              @tui = tui
+              loop do
+                draw_view
+                handle_ratatui_event
+                handle_sync
+                send_pending_messages
               end
             end
           end
+
+          # Shutdown: signal all, wait grace periods (cooperative cancellation)
+          @lifecycle.shutdown
+
+          # Process any final messages from completed commands
+          send_pending_messages(dispatch: false)
+
+          @model
+        end
+
+        private def draw_view
+          @tui.draw do |frame|
+            widget = @view.call(@model, @tui)
+            validate_view_return!(widget)
+            frame.render_widget(widget, frame.area)
+          end
         end
 
-        # Shutdown: signal all, wait grace periods, then kill
-        active_commands.each do |handle, entry|
-          entry[:token].cancel!
-          grace = handle.tea_cancellation_grace_period
-          if grace.finite?
-            deadline = Time.now + grace
-            sleep 0.02 while entry[:thread].alive? && Time.now < deadline
-            entry[:thread].kill if entry[:thread].alive?
+        # Enforces invariants
+        private def fragment_from_kwargs(root_fragment, model: nil, view: nil, update: nil, command: nil)
+          if root_fragment
+            fragment_invariant!("model") if model
+            fragment_invariant!("view") if view
+            fragment_invariant!("update") if update
+            fragment_invariant!("command") if command
+            root_fragment
           else
-            entry[:thread].join
+            fragment = Module.new
+            fragment.const_set(:Model, model)
+            fragment.const_set(:View, view)
+            fragment.const_set(:Update, update)
+            fragment.const_set(:Init, -> { [model, command] })
+            fragment
           end
         end
 
-        # Process any final messages from completed commands
-        until queue.empty?
-          begin
-            background_message = queue.pop(true)
-            result = update.call(background_message, model)
-            model, = normalize_update_result(result, model)
-          rescue ThreadError
-            break
+        # Helps app developers understand invariants
+        private def fragment_invariant!(param)
+          raise RatatuiRuby::Error::Invariant, "Cannot provide both fragment: and #{param}: parameters. Use fragment-first API (fragment:) OR explicit parameters (model:, view:, update:, command:), not both."
+        end
+
+        private def init_callable
+          if @fragment.const_defined?(:Init)
+            if @fragment::Init.respond_to?(:call)
+              if Proc === @fragment::Init or Method === @fragment::Init
+                @fragment::Init
+              else
+                @fragment::Init.method(:call)
+              end
+            else
+              raise RatatuiRuby::Error::Invariant, "Fragment::Init must respond to :call"
+            end
+          else
+            if @fragment.const_defined?(:Model)
+              if @fragment::Model.respond_to?(:new)
+                -> { @fragment::Model.new }
+              else
+                raise RatatuiRuby::Error::Invariant, "Fragment::Model must respond to :new; or pass Fragment::Init instead"
+              end
+            else
+              raise RatatuiRuby::Error::Invariant, "Fragment must define a Model class or an Init callable"
+            end
           end
         end
 
-        model
-      end
+        private
 
-      # Validates the view returned a widget.
-      #
-      # Views return widget trees. Returning +nil+ is a bug—you forgot to
-      # return something. For an intentionally empty screen, use TUI#clear.
-      private_class_method def self.validate_view_result!(widget)
-        return unless widget.nil?
+        # Validates the view returned a widget.
+        #
+        # Views return widget trees. Returning +nil+ is a bug—you forgot to
+        # return something. For an intentionally empty screen, use TUI#clear.
+        private def validate_view_return!(widget)
+          return unless widget.nil?
 
-        raise RatatuiRuby::Error::Invariant,
-          "View returned nil. Return a widget, or use TUI#clear for an empty screen."
-      end
+          raise RatatuiRuby::Error::Invariant,
+            "View returned nil. Return a widget, or use TUI#clear for an empty screen."
+        end
 
-      # Extracts [model, command] from update result.
-      #
-      # Uses is_a? checks for type narrowing. The result parameter is untyped
-      # because the method performs runtime type detection.
-      #
-      # @param result [Array, Command::execution, Object] The update result
-      # @param previous_model [Model] Fallback model if result is a command
-      # @return [Array(Object, Command::execution?)] The [model, command] tuple
-      private_class_method def self.normalize_update_result(result, previous_model)
-        # Case 0: Nil result - preserve previous model
-        return [previous_model, nil] if result.nil?
-
-        # Case 1: Already a [model, command] tuple
-        if result.is_a?(Array) && (result.size == 2)
-          model = result[0]
-          command = result[1]
-          # Verify the second element is a valid command (nil, built-in, or custom)
-          if command.nil? ||
-              command.class.name&.start_with?("RatatuiRuby::Tea::Command::") ||
-              (command.respond_to?(:tea_command?) && command.tea_command?)
-
-            return [model, command]
+        # Extracts [model, command] from Update return value.
+        private def normalize_update_return(result, previous_model)
+          # Case 0: Nil result - preserve previous model
+          return [previous_model, nil] if result.nil?
+
+          # Case 1: Already a [model, command] tuple
+          if result.is_a?(Array) && (result.size == 2)
+            model, command = result
+            # Verify the second element is a valid command
+            if command.nil? ||
+                (command.respond_to?(:tea_command?) && command.tea_command?)
+
+              return [model, command]
+            end
+
+            # Debug-mode heuristic: warn about suspicious command-like objects
+            if RatatuiRuby::Debug.enabled? &&
+                command.respond_to?(:call) &&
+                !command.respond_to?(:tea_command?) &&
+                !Ractor.shareable?(result)
+
+              warn "WARNING: Update returned [model, #{command.class}] but #{command.class} " \
+                "responds to #call without #tea_command?. Did you forget to include Command::Custom? " \
+                "The tuple will be treated as the model, not as [model, command]. " \
+                "To suppress this warning if the array is your model, use Ractor.make_shareable on it. " \
+                "(#{caller.first})"
+            end
+
+          end
+
+          # Case 2: Result is a Command - use previous model
+          if result.respond_to?(:tea_command?) && result.tea_command?
+            command = result #: RatatuiRuby::Tea::Command::execution
+            return [previous_model, command]
           end
+
+          # Case 3: Result is the new model
+          [result, nil]
         end
 
-        # Case 2: Result is a Command - use previous model
-        if result.class.name&.start_with?("RatatuiRuby::Tea::Command::")
-          return [previous_model, result]
+        # Validates an object is Ractor-shareable (deeply frozen).
+        #
+        # Models and messages must be shareable for future Ractor support.
+        # Mutable objects cause race conditions. Freeze your data.
+        #
+        # Only enforced in debug mode (and tests). Production skips this check
+        # for performance; mutable objects will still cause bugs, but silently.
+        private def validate_ractor_shareable!(object, name)
+          return unless RatatuiRuby::Debug.enabled?
+          return if Ractor.shareable?(object)
+
+          raise RatatuiRuby::Error::Invariant,
+            "#{name.capitalize} is not Ractor-shareable. Use Ractor.make_shareable or Object#freeze."
         end
-        if result.respond_to?(:tea_command?) && result.tea_command?
-          return [previous_model, result]
+
+        private def handle_ratatui_event
+          message = @tui.poll_event(timeout: @timeout)
+          return if message.none?
+
+          @model, @command = normalize_update_return(@update.call(message, @model), @model)
+          validate_ractor_shareable!(@model, "model")
+          throw QUIT if Command::Exit === @command
+          dispatch_command
         end
 
-        # Case 3: Result is the new model
-        [result, nil]
-      end
+        # This must come *after* handle_ratatui_event so Sync waits for commands
+        # dispatched by the preceding event. For example, in a test:
+        #
+        #   inject_key("a")
+        #   inject_sync
+        #
+        # We need <kbd>a</kbd> to call the Update and queue its message before
+        # processing the Sync.
+        private def handle_sync
+          if RatatuiRuby::SyntheticEvents.pending?
+            synthetic = RatatuiRuby::SyntheticEvents.pop
+            if synthetic&.sync?
+              # Wait for all pending futures to complete
+              @pending_futures.each(&:wait)
+              @pending_futures.clear
 
-      # Validates an object is Ractor-shareable (deeply frozen).
-      #
-      # Models and messages must be shareable for future Ractor support.
-      # Mutable objects cause race conditions. Freeze your data.
-      #
-      # Only enforced in debug mode (and tests). Production skips this check
-      # for performance; mutable objects will still cause bugs, but silently.
-      private_class_method def self.validate_ractor_shareable!(object, name)
-        return unless RatatuiRuby::Debug.enabled?
-        return if Ractor.shareable?(object)
-
-        raise RatatuiRuby::Error::Invariant,
-          "#{name.capitalize} is not Ractor-shareable. Use Ractor.make_shareable or Object#freeze."
-      end
+              # Yield to ensure any final queue writes are visible
+              Thread.pass
 
-      # Dispatches a command asynchronously. :nodoc:
-      #
-      # Spawns a background thread and pushes results to the message queue.
-      # See Command.system for message formats.
-      private_class_method def self.dispatch(command, queue, active_commands = {})
-        case command
-        when Command::Cancel
-          entry = active_commands[command.handle]
-          if entry && entry[:thread].alive?
-            entry[:token].cancel!
-            grace = command.handle.tea_cancellation_grace_period
-            if grace.finite?
-              deadline = Time.now + grace
-              sleep 0.02 while entry[:thread].alive? && Time.now < deadline
-              entry[:thread].kill if entry[:thread].alive?
-            else
-              entry[:thread].join
+              # Process all pending message queue items
+              send_pending_messages
             end
           end
-          active_commands.delete(command.handle)
-          nil
-        else
-          # Custom command (responds to tea_command?)
-          if command.respond_to?(:tea_command?) && command.tea_command?
-            token = Command::CancellationToken.new
-            outlet = Command::Outlet.new(queue)
-
-            thread = Thread.new do
-              command.call(outlet, token)
-            rescue => e
-              queue << Command::Error.new(command:, exception: e)
-            end
+        end
+
+        QUEUE_EMPTY = Object.new.freeze
+        private_constant :QUEUE_EMPTY
+
+        private def send_pending_messages(dispatch: true)
+          loop do
+            background_message = @message_queue.try_pop(QUEUE_EMPTY)
+            break if background_message == QUEUE_EMPTY
+
+            result = @update.call(background_message, @model)
+            @model, @command = normalize_update_return(result, @model)
+            return unless dispatch
 
-            active_commands[command] = { thread:, token: }
-            thread
+            validate_ractor_shareable!(@model, "model")
+            throw QUIT if Command::Exit === @command
+
+            dispatch_command
+          end
+        end
+
+        # Spawns a future and pushes results to the message queue.
+        # See Command.system for message formats.
+        private def dispatch_command
+          future = if @command.nil?
+            nil
+          elsif Command::Cancel === @command
+            @lifecycle.cancel(@command.handle)
+            nil
+          elsif @command.respond_to?(:tea_command?) && @command.tea_command?
+            entry = @lifecycle.run_async(@command, @message_queue)
+            entry.future
+          else
+            raise RatatuiRuby::Error::Invariant,
+              "#{@command.inspect} is not a valid Tea command."
           end
+          @pending_futures << future if future
         end
       end
     end

data/lib/ratatui_ruby/tea/shortcuts.rb

@@ -36,8 +36,8 @@ module RatatuiRuby
 
         # Creates a shell execution command.
         # Short alias for +Command.system+.
-        def self.sh(command, tag)
-          Command.system(command, tag)
+        def self.sh(command, envelope)
+          Command.system(command, envelope)
         end
 
         # Creates a mapped command.

data/lib/ratatui_ruby/tea/test_helper.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "ratatui_ruby/test_helper"
+
+module RatatuiRuby
+  module Tea
+    # Test helpers for Tea command validation.
+    #
+    # This module extends RatatuiRuby::TestHelper with Tea-specific assertions
+    # for verifying custom commands implement the proper protocol.
+    module TestHelper
+      # Validates a command implements the Tea command protocol.
+      #
+      # Custom commands run in background threads. They dispatch work and send messages.
+      # Forgetting to include \<tt>Command::Custom\</tt> breaks dispatch. The runtime
+      # treats \<tt>[model, bad_command]\</tt> as a model, not a tuple. Tests fail with
+      # confusing Ractor shareability errors.
+      #
+      # This method checks the protocol. Call it in tests to catch mistakes early.
+      #
+      # [command] The command object to validate.
+      #
+      # === Example
+      #
+      #   def test_websocket_command_protocol
+      #     cmd = WebSocketCommand.new("wss://example.com")
+      #     validate_tea_command!(cmd)
+      #   end
+      def validate_tea_command!(command)
+        unless command.respond_to?(:tea_command?)
+          raise RatatuiRuby::Error::Invariant,
+            "#{command.class} does not respond to #tea_command?. " \
+              "Include Command::Custom or implement the tea_command? predicate."
+        end
+
+        unless command.respond_to?(:call)
+          raise RatatuiRuby::Error::Invariant,
+            "#{command.class} does not respond to #call. " \
+              "Implement call(out, token) to execute the command."
+        end
+
+        unless command.respond_to?(:tea_cancellation_grace_period)
+          raise RatatuiRuby::Error::Invariant,
+            "#{command.class} does not respond to #tea_cancellation_grace_period. " \
+              "Include Command::Custom or implement this method."
+        end
+      end
+    end
+  end
+end
+
+# Attach Tea test helpers to RatatuiRuby::TestHelper
+RatatuiRuby::TestHelper.include(RatatuiRuby::Tea::TestHelper)

data/lib/ratatui_ruby/tea/version.rb

@@ -9,6 +9,6 @@ module RatatuiRuby # :nodoc: Documented in the ratatui_ruby gem.
   module Tea
     # The version of this gem.
     # See https://semver.org/spec/v2.0.0.html
-    VERSION = "0.3.1"
+    VERSION = "0.4.0"
   end
 end