rooibos 0.5.0 → 0.6.1

data/lib/rooibos/message/error.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # Error message from a failed command.
+    #
+    # Commands run in background threads. Exceptions bubble up silently.
+    # Your update function never sees them. Backtraces in STDERR corrupt the TUI.
+    #
+    # The runtime catches exceptions and wraps them in Error messages.
+    # Pattern match on Error in your update function. Display the error, log it, or recover.
+    #
+    # Use it to surface failures from HTTP requests, file I/O, or external processes.
+    #
+    # === Examples
+    #
+    #   Update = ->(message, model) {
+    #     case message
+    #     in { type: :error, command:, exception: }
+    #       # Show error toast
+    #       model.with(error: exception.message)
+    #     in Message::Error
+    #       # Store for later inspection
+    #       model.with(last_error: message.exception)
+    #     end
+    #   }
+    Error = Data.define(:command, :exception) do
+      include Predicates
+
+      # Returns <tt>true</tt> for error messages.
+      def error?
+        true
+      end
+
+      # Deconstructs for pattern matching.
+      #
+      # Returns a hash with <tt>type</tt>, <tt>command</tt>, and <tt>exception</tt>.
+      def deconstruct_keys(_keys)
+        { type: :error, command:, exception: }
+      end
+    end
+  end
+end

data/lib/rooibos/message/open.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # Signals that a file or URL was successfully opened.
+    #
+    # This message arrives after +Command.open+ completes with exit status 0.
+    # Non-zero exits produce +Message::Error+ instead.
+    #
+    # === Pattern Matching
+    #
+    #   case message
+    #   in { type: :open, envelope: path }
+    #     model.with(status: "Opened #{path}")
+    #   end
+    #
+    class Open < Data.define(:envelope)
+      include Predicates
+
+      def deconstruct_keys(_keys)
+        { type: :open, envelope: }
+      end
+    end
+  end
+end

data/lib/rooibos/message.rb

@@ -8,21 +8,97 @@
 module Rooibos
   # Messages sent from commands to update functions.
   #
-  # All built-in response types live here. Each includes the +Predicates+
+  # All built-in response types live here. Each includes the <tt>Predicates</tt>
   # mixin for safe predicate calls.
   module Message
+    # Matches built-in framework message types for case/when dispatch.
+    #
+    # Returns <tt>true</tt> only for classes under <tt>Rooibos::Message::</tt>.
+    # Rejects key events and user-defined message classes.
+    #
+    # === Example
+    #
+    #   case message
+    #   when Rooibos::Message
+    #     handle_command_response(message)
+    #   when RatatuiRuby::Event::Key
+    #     handle_key(message)
+    #   end
+    def self.===(other)
+      other.class.name&.start_with?("Rooibos::Message::")
+    end
+
     # Fallback predicate mixin.
     #
-    # Returns +false+ for any unknown predicate method (ending in +?+).
-    # Include in custom message types for safe predicate calls.
+    # Update functions receive many message types. Checking unknown predicates
+    # crashes with NoMethodError. Verifying every predicate clutters the code.
+    #
+    # This mixin returns <tt>false</tt> for unknown predicates. It also adds
+    # symbol comparison via <tt>to_sym</tt> and <tt>==</tt>.
+    #
+    # Include in custom message types for safe predicate calls and symbol matching.
     module Predicates
-      # Returns +false+ for unknown predicate methods.
+      # Converts the message to a Symbol.
+      #
+      # Returns the <tt>:type</tt> value from <tt>deconstruct_keys</tt> prefixed
+      # with <tt>message_</tt>. The prefix avoids collision with RatatuiRuby
+      # event symbols like <tt>:resize</tt> or <tt>:mouse</tt>.
+      #
+      # === Example
+      #
+      #   timer = Message::Timer.new(envelope: :tick, elapsed: 0.016)
+      #   timer.to_sym # => :message_timer
+      def to_sym
+        :"message_#{deconstruct_keys(nil)[:type]}"
+      end
+
+      # Compares the message with another object.
+      #
+      # Symbols compare against <tt>to_sym</tt>. Other objects use default equality.
+      #
+      # === Example
+      #
+      #   if message == :message_timer
+      #     handle_tick(message)
+      #   end
+      def ==(other)
+        case other
+        when Symbol then to_sym == other
+        else super
+        end
+      end
+
+      # Returns <tt>false</tt> for unknown predicate methods.
       def method_missing(name, *args, **kwargs, &block)
         return false if name.to_s.end_with?("?") && args.empty? && kwargs.empty?
 
         super
       end
 
+      # Fallback pattern matching for classes without explicit deconstruct_keys.
+      #
+      # Derives <tt>:type</tt> from the class name in snake_case. Anonymous
+      # classes default to <tt>:custom</tt>.
+      #
+      # === Example
+      #
+      #   class MyCustomMessage
+      #     include Rooibos::Message::Predicates
+      #   end
+      #
+      #   msg = MyCustomMessage.new
+      #   msg.deconstruct_keys(nil) # => { type: :my_custom_message }
+      #   msg.to_sym                # => :message_my_custom_message
+      def deconstruct_keys(_keys)
+        class_name = self.class.name&.split("::")&.last
+        type_name = if class_name
+          class_name.gsub(/([a-z])([A-Z])/, '\1_\2').downcase.to_sym
+        else
+          :custom
+        end
+        { type: type_name }
+      end
+
       # Responds to all predicate methods.
       def respond_to_missing?(name, *)
         name.to_s.end_with?("?")
@@ -32,7 +108,11 @@ module Rooibos
 end
 
 require_relative "message/timer"
+require_relative "message/open"
 require_relative "message/http_response"
 require_relative "message/system/batch"
 require_relative "message/system/stream"
 require_relative "message/all"
+require_relative "message/batch"
+require_relative "message/error"
+require_relative "message/canceled"

data/lib/rooibos/router.rb

@@ -1,7 +1,7 @@
-# frozen_string_literal: true
-
 #--
 # SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# frozen_string_literal: true
+
 # SPDX-License-Identifier: LGPL-3.0-or-later
 #++
 
@@ -13,10 +13,10 @@ module Rooibos
   # Writing this routing logic by hand is tedious and error-prone.
   #
   # Include this module to declare routes and keymaps. Call +from_router+ to
-  # generate an UPDATE lambda that handles routing automatically.
+  # generate an Update lambda that handles routing automatically.
   #
-  # A *fragment* is a module containing <tt>Model</tt>, <tt>INITIAL</tt>,
-  # <tt>UPDATE</tt>, and <tt>VIEW</tt> constants. Fragments compose: parent fragments
+  # A *fragment* is a module containing <tt>Model</tt>, <tt>Init</tt>,
+  # <tt>Update</tt>, and <tt>View</tt> constants. Fragments compose: parent fragments
   # delegate to child fragments.
   #
   # === Example
@@ -33,9 +33,9 @@ module Rooibos
   #     end
   #
   #     Model = Data.define(:stats, :network)
-  #     INITIAL = Model.new(stats: StatsPanel::INITIAL, network: NetworkPanel::INITIAL)
-  #     VIEW = ->(model, tui) { ... }
-  #     UPDATE = from_router
+  #     Init = -> { Model.new(stats: StatsPanel::Init.(), network: NetworkPanel::Init.()) }
+  #     View = ->(model, tui) { ... }
+  #     Update = from_router
   #   end
   module Router
     # Configuration for key handlers.
@@ -59,8 +59,7 @@ module Rooibos
       end
     end
 
-    # :nodoc:
-    def self.included(base)
+    def self.included(base) # :nodoc:
       base.extend(ClassMethods)
     end
 
@@ -254,8 +253,7 @@ module Rooibos
       # Returns the registered handlers hash.
       attr_reader :handlers
 
-      # :nodoc:
-      def initialize
+      def initialize # :nodoc:
         @handlers = {}
         @guard_stack = []
       end
@@ -369,8 +367,7 @@ module Rooibos
       # Returns the registered click handler.
       attr_reader :click_handler
 
-      # :nodoc:
-      def initialize
+      def initialize # :nodoc:
         @scroll_handlers = {}
         @click_handler = nil
       end

data/lib/rooibos/runtime.rb

@@ -8,6 +8,10 @@
 require "ratatui_ruby"
 require "concurrent-edge"
 
+# Enable inline sync mode for deterministic event ordering in tests.
+# This ensures poll_event returns Event::Sync in sequence with key events.
+RatatuiRuby::SyntheticEvents.inline_sync!
+
 module Rooibos
   # Runs the Model-View-Update event loop.
   #
@@ -95,13 +99,17 @@ module Rooibos
     #
     # == Explicit Parameters API
     #
-    # A root fragment is not required. You can pass individual parameters:
+    # Tests need deterministic state. Init reads from the filesystem, network, or
+    # environment—sources that change between runs. Injecting a known model makes
+    # tests reproducible.
+    #
+    # Pass <tt>model:</tt>, <tt>view:</tt>, and <tt>update:</tt> directly. The runtime
+    # skips Init and uses your model as the starting state.
     #
     #   Rooibos.run(
-    #     model: MyApp::Model.new(count: 0),
+    #     model: Ractor.make_shareable(MyApp::Model.new(count: 0)),
     #     view: MyApp::View,
-    #     update: MyApp::Update,
-    #     command: Command.http("https://api.example.com/data")
+    #     update: MyApp::Update
     #   )
     #
     # == Parameters
@@ -120,14 +128,8 @@ module Rooibos
       @fragment = fragment_from_kwargs(root_fragment, model:, view:, update:, command:)
       @view = @fragment::View
       @update = @fragment::Update
-      @model, @command = init_callable.call
-      @timeout = 1 / fps
-
-      # 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
+      @init_callable = init_callable
+      @timeout = 1.0 / fps
 
       start_runtime
     end
@@ -176,13 +178,18 @@ module Rooibos
         @lifecycle = Command::Lifecycle.new
 
         catch(QUIT) do
-          dispatch_command
           RatatuiRuby.run do |tui|
             @tui = tui
+
+            # Init runs after terminal is ready so it can query terminal_size, etc.
+            @model, @command = @init_callable.call
+            validate_ractor_shareable!(@command, "command")
+            validate_ractor_shareable!(@model, "model")
+            dispatch_command
+
             loop do
               draw_view
               handle_ratatui_event
-              handle_sync
               send_pending_messages
             end
           end
@@ -198,9 +205,12 @@ module Rooibos
       end
 
       private def draw_view
+        # Build widget tree OUTSIDE draw context - queries work here
+        widget = @view.call(@model, @tui)
+        validate_view_return!(widget)
+
+        # Render INSIDE draw context - only rendering happens here
         @tui.draw do |frame|
-          widget = @view.call(@model, @tui)
-          validate_view_return!(widget)
           frame.render_widget(widget, frame.area)
         end
       end
@@ -322,37 +332,22 @@ module Rooibos
 
       private def handle_ratatui_event
         message = @tui.poll_event(timeout: @timeout)
-        return if message.none?
+        return false if message.none?
+
+        # Handle sync events: wait for pending async work before continuing
+        if message.sync?
+          @pending_futures.each(&:wait)
+          @pending_futures.clear
+          Thread.pass
+          send_pending_messages
+          return true
+        end
 
         @model, @command = normalize_update_return(@update.call(message, @model), @model)
         validate_ractor_shareable!(@model, "model")
         throw QUIT if Command::Exit === @command
         dispatch_command
-      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
-
-            # Yield to ensure any final queue writes are visible
-            Thread.pass
-
-            # Process all pending message queue items
-            send_pending_messages
-          end
-        end
+        true # Event was processed
       end
 
       QUEUE_EMPTY = Object.new.freeze
@@ -380,7 +375,9 @@ module Rooibos
         future = if @command.nil?
           nil
         elsif Command::Cancel === @command
-          @lifecycle.cancel(@command.handle)
+          entry = @lifecycle.cancel(@command.handle)
+          # Remove cancelled future from pending list so sync doesn't wait for it
+          @pending_futures.delete(entry.future) if entry
           nil
         elsif @command.respond_to?(:rooibos_command?) && @command.rooibos_command?
           entry = @lifecycle.run_async(@command, @message_queue)

data/lib/rooibos/shortcuts.rb

@@ -6,6 +6,7 @@
 #++
 
 require_relative "command"
+require_relative "message"
 
 module Rooibos
   # Convenient short aliases for Rooibos APIs.
@@ -45,5 +46,51 @@ module Rooibos
         Command.map(inner_command, &mapper)
       end
     end
+
+    # Short aliases for +Message+ types.
+    #
+    # App developers pattern-match against message types frequently.
+    # The full names (+Rooibos::Message::HttpResponse+) are verbose.
+    # These shortcuts save characters and improve readability.
+    #
+    # === Example
+    #
+    #   case message
+    #   in Msg::Timer[envelope: :dismiss]
+    #     [model.with(notification: nil), nil]
+    #   in Msg::Http[status: 200, body:]
+    #     [model.with(data: JSON.parse(body)), nil]
+    #   in Msg::Sh::Batch[status: 0, stdout:]
+    #     [model.with(output: stdout), nil]
+    #   end
+    module Msg
+      # Timer message type.
+      # Alias for +Message::Timer+.
+      Timer = Message::Timer
+
+      # HTTP response message type.
+      # Alias for +Message::HttpResponse+.
+      Http = Message::HttpResponse
+
+      # Shell command message types.
+      # Mirrors +Cmd.sh+ for symmetry.
+      module Sh
+        # Batch mode shell output.
+        # Alias for +Message::System::Batch+.
+        Batch = Message::System::Batch
+
+        # Streaming mode shell output.
+        # Alias for +Message::System::Stream+.
+        Stream = Message::System::Stream
+      end
+
+      # Aggregated parallel results.
+      # Alias for +Message::All+.
+      All = Message::All
+
+      # Batch completion signal.
+      # Alias for +Message::Batch+.
+      Batch = Message::Batch
+    end
   end
 end

data/lib/rooibos/test_helper.rb

@@ -8,11 +8,33 @@
 require "ratatui_ruby/test_helper"
 
 module Rooibos
-  # Test helpers for Rooibos command validation.
+  # Assertions and test utilities for Rooibos applications.
   #
-  # This module extends RatatuiRuby::TestHelper with Rooibos-specific assertions
-  # for verifying custom commands implement the proper protocol.
+  # Custom commands run in background threads. Forgetting to include
+  # <tt>Command::Custom</tt> causes cryptic Ractor errors. Validating
+  # protocol compliance manually is tedious.
+  #
+  # This module provides Rooibos-specific assertions. It also includes
+  # {RatatuiRuby::TestHelper}[https://www.ratatui-ruby.dev/docs/v1.0/RatatuiRuby/TestHelper.html],
+  # giving you access to <tt>with_test_terminal</tt>, <tt>inject_key</tt>, etc.
+  #
+  # Use it in Minitest classes to validate commands and control test terminals.
+  #
+  # === Example
+  #
+  #   class TestMyApp < Minitest::Test
+  #     include Rooibos::TestHelper
+  #
+  #     def test_app_exits_on_ctrl_c
+  #       with_test_terminal do
+  #         inject_key(:ctrl_c)
+  #         Rooibos.run(MyApp)
+  #       end
+  #     end
+  #   end
   module TestHelper
+    include RatatuiRuby::TestHelper
+
     # Validates a command implements the Rooibos command protocol.
     #
     # Custom commands run in background threads. They dispatch work and send messages.
@@ -49,8 +71,51 @@ module Rooibos
             "Include Command::Custom or implement this method."
       end
     end
+
+    # Fails if any Message::Error is present in the messages array.
+    #
+    # Call after running the runtime and before asserting on expected messages.
+    # This ensures tests fail fast with helpful error messages instead of
+    # silently passing when errors occur.
+    #
+    # [messages] Array of messages collected from the update function.
+    # [msg]      Optional custom failure message prefix.
+    #
+    # === Example
+    #
+    #   def test_dashboard_loads_data
+    #     messages = []
+    #     update = -> (msg, m) do
+    #       # ... handle keys ...
+    #       messages << msg
+    #       [m, nil]
+    #     end
+    #
+    #     with_test_terminal do
+    #       inject_key("s")
+    #       inject_sync
+    #       inject_key("q")
+    #       Rooibos::Runtime.run(model:, view:, update:)
+    #     end
+    #
+    #     assert_no_errors(messages)
+    #     # ... rest of assertions
+    #   end
+    #
+    def assert_no_errors(messages, msg = nil)
+      error = messages.find { |m| m.is_a?(Rooibos::Message::Error) }
+      return unless error
+
+      error_detail = "#{error.exception.class}: #{error.exception.message}"
+      failure_msg = msg ? "#{msg}\n#{error_detail}" : "Unexpected Message::Error: #{error_detail}"
+
+      if respond_to?(:flunk)
+        # rubocop:disable Style/SendWithLiteralMethodName
+        public_send(:flunk, failure_msg)
+        # rubocop:enable Style/SendWithLiteralMethodName
+      else
+        raise failure_msg
+      end
+    end
   end
 end
-
-# Attach Rooibos test helpers to RatatuiRuby::TestHelper
-RatatuiRuby::TestHelper.include(Rooibos::TestHelper)

data/lib/rooibos/version.rb

@@ -8,5 +8,5 @@
 module Rooibos
   # The version of this gem.
   # See https://semver.org/spec/v2.0.0.html
-  VERSION = "0.5.0"
+  VERSION = "0.6.1"
 end