rooibos 0.5.0 → 0.6.0

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.0"
 end

data/lib/rooibos/welcome.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: MIT-0
+#++
+
+module Rooibos
+  # Built-in welcome screen used by scaffolded applications.
+  module Welcome
+    module UI # :nodoc:
+      module Styles # :nodoc:
+        TEXT = RatatuiRuby::Style::Style.new
+        FILENAME = RatatuiRuby::Style::Style.new(fg: :green)
+        COMMAND = RatatuiRuby::Style::Style.new(fg: :red)
+        URL = RatatuiRuby::Style::Style.new(fg: :blue)
+
+        COMMAND_BUTTON = RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:underlined])
+        COMMAND_BUTTON_FOCUS = RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:bold, :underlined])
+        COMMAND_BUTTON_HOVER = RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:reversed])
+        COMMAND_BUTTON_BOTH = RatatuiRuby::Style::Style.new(fg: :red, modifiers: [:bold, :reversed])
+
+        URL_BUTTON = RatatuiRuby::Style::Style.new(fg: :blue, modifiers: [:underlined])
+        URL_BUTTON_FOCUS = RatatuiRuby::Style::Style.new(fg: :blue, modifiers: [:bold, :underlined])
+        URL_BUTTON_HOVER = RatatuiRuby::Style::Style.new(fg: :blue, modifiers: [:reversed])
+        URL_BUTTON_BOTH = RatatuiRuby::Style::Style.new(fg: :blue, modifiers: [:bold, :reversed])
+      end
+
+      module Widgets # :nodoc:
+        WELCOME_TEXT = {
+          "Welcome to Rooibos! You will find the Ruby code " \
+            "for this application in " => Styles::TEXT,
+          "lib/saturday.rb" => Styles::FILENAME,
+          ". The tests that verify it are at " => Styles::TEXT,
+          "test/test_saturday.rb" => Styles::FILENAME,
+          ". You can run the tests with " => Styles::TEXT,
+          "bundle exec rake test" => Styles::COMMAND,
+          ". Visit " => Styles::TEXT,
+          "www.rooibos.run" => Styles::URL,
+          " to learn about Rooibos and to find other " \
+            "Rooibos developers. You can press " => Styles::TEXT,
+          "Control + C" => Styles::COMMAND,
+          " to exit at any time." => Styles::TEXT,
+        }
+
+        PARAGRAPH = RatatuiRuby::Widgets::Paragraph.new(
+          text: RatatuiRuby::Text::Line.new(
+            spans: WELCOME_TEXT.map { |text, style| RatatuiRuby::Text::Span.new(content: text, style:) }
+          ),
+          wrap: true,
+          alignment: :left
+        )
+
+        def self.website_button(focused: false, hovered: false)
+          style = if focused && hovered
+            Styles::URL_BUTTON_BOTH
+          elsif focused
+            Styles::URL_BUTTON_FOCUS
+          elsif hovered
+            Styles::URL_BUTTON_HOVER
+          else
+            Styles::URL_BUTTON
+          end
+          RatatuiRuby::Text::Span.new(content: "[Visit Website]", style:)
+        end
+
+        def self.exit_button(focused: false, hovered: false)
+          style = if focused && hovered
+            Styles::COMMAND_BUTTON_BOTH
+          elsif focused
+            Styles::COMMAND_BUTTON_FOCUS
+          elsif hovered
+            Styles::COMMAND_BUTTON_HOVER
+          else
+            Styles::COMMAND_BUTTON
+          end
+          RatatuiRuby::Text::Span.new(content: "[Exit App]", style:)
+        end
+      end
+
+      BUTTON_SLOTS = { website: 1, exit: 3 }.freeze
+      FOCUS_ORDER = [:website, :exit].freeze
+
+      BUTTON_BAR_CONSTRAINTS = [
+        RatatuiRuby::Layout::Constraint.fill(1),
+        RatatuiRuby::Layout::Constraint.length(18),
+        RatatuiRuby::Layout::Constraint.length(2),
+        RatatuiRuby::Layout::Constraint.length(14),
+        RatatuiRuby::Layout::Constraint.fill(1),
+      ].freeze
+
+      CONTENT_CONSTRAINTS = [
+        RatatuiRuby::Layout::Constraint.fill(1),
+        RatatuiRuby::Layout::Constraint.length(1),
+      ].freeze
+
+      def self.button_bar(focused:, hovered:)
+        RatatuiRuby::Layout::Layout.new(
+          direction: :horizontal,
+          constraints: BUTTON_BAR_CONSTRAINTS,
+          children: [
+            nil,
+            Widgets.website_button(focused: focused == :website, hovered: hovered == :website),
+            nil,
+            Widgets.exit_button(focused: focused == :exit, hovered: hovered == :exit),
+            nil,
+          ]
+        )
+      end
+
+      def self.content_layout(focused:, hovered:)
+        RatatuiRuby::Layout::Layout.new(
+          direction: :vertical,
+          constraints: CONTENT_CONSTRAINTS,
+          children: [Widgets::PARAGRAPH, button_bar(focused:, hovered:)]
+        )
+      end
+
+      def self.frame(focused:, hovered:)
+        RatatuiRuby::Widgets::Block.new(
+          title: "Hello, Rooibos!",
+          borders: [:all],
+          border_style: { fg: :cyan },
+          padding: [2, 2, 1, 1],
+          children: [content_layout(focused:, hovered:)]
+        )
+      end
+
+      # Value object wrapping hit-test areas for clickable buttons.
+      ButtonAreas = Data.define(:website, :exit) do
+        def contains?(name, x, y) = public_send(name)&.contains?(x, y)
+
+        def button_at(x, y)
+          return :website if website&.contains?(x, y)
+          return :exit if exit&.contains?(x, y)
+
+          nil
+        end
+
+        def for_viewport(width, height)
+          viewport = RatatuiRuby::Layout::Rect.new(x: 0, y: 0, width:, height:)
+          frame = UI.frame(focused: nil, hovered: nil)
+          inner = frame.inner(viewport)
+
+          content_rects = RatatuiRuby::Layout::Layout.split(
+            inner,
+            direction: :vertical,
+            constraints: CONTENT_CONSTRAINTS
+          )
+          button_rects = RatatuiRuby::Layout::Layout.split(
+            content_rects[1],
+            direction: :horizontal,
+            constraints: BUTTON_BAR_CONSTRAINTS
+          )
+
+          ButtonAreas.new(
+            website: button_rects[BUTTON_SLOTS[:website]],
+            exit: button_rects[BUTTON_SLOTS[:exit]]
+          )
+        end
+      end
+    end
+
+    # focused: keyboard focus (persists until Tab/Shift+Tab)
+    # hovered: mouse hover (clears on mouse-out)
+    Model = Data.define(:button_areas, :focused, :hovered) do
+      def tree = UI.frame(focused:, hovered:)
+
+      # Returns the "active" button for activation (keyboard takes precedence)
+      def active_button = focused || hovered
+    end
+
+    View = -> (model, _tui) { model.tree }
+
+    Update = -> (message, model) {
+      case message
+      in _ if message.ctrl_c?
+        Rooibos::Command.exit
+      in _ if message.resize?
+        model.with(button_areas: model.button_areas.for_viewport(message.width, message.height))
+      in _ if message.tab?
+        cycle_focus(model, :forward)
+      in _ if message.shift_back_tab?
+        cycle_focus(model, :backward)
+      in _ if message.enter? && model.active_button
+        activate_button(model.active_button, model)
+      in _ if message.mouse? && message.down? && message.button == "left"
+        handle_click(message, model)
+      in { type: :mouse }
+        handle_hover(message, model)
+      else
+        model
+      end
+    }
+
+    Init = -> {
+      viewport = RatatuiRuby.terminal_size
+      areas = UI::ButtonAreas.new(website: nil, exit: nil).for_viewport(viewport.width, viewport.height)
+      Ractor.make_shareable Model.new(button_areas: areas, focused: nil, hovered: nil)
+    }
+
+    def self.handle_click(message, model)
+      button = model.button_areas.button_at(message.x, message.y)
+      activate_button(button, model)
+    end
+
+    def self.handle_hover(message, model)
+      new_hovered = model.button_areas.button_at(message.x, message.y)
+      return model if new_hovered == model.hovered
+
+      model.with(hovered: new_hovered)
+    end
+
+    def self.cycle_focus(model, direction)
+      order = UI::FOCUS_ORDER
+      return model.with(focused: order.first) unless model.focused
+
+      current_index = order.index(model.focused)
+      return model.with(focused: order.first) unless current_index
+
+      next_index = case direction
+                  when :forward then (current_index + 1) % order.length
+                  when :backward then (current_index - 1) % order.length
+                  else 0
+      end
+      model.with(focused: order[next_index])
+    end
+
+    def self.activate_button(button, model)
+      case button
+      when :website then [model, Rooibos::Command.system("open 'https://www.rooibos.run'", :open_url)]
+      when :exit then Rooibos::Command.exit
+      else model
+      end
+    end
+  end
+end

data/lib/rooibos.rb

@@ -11,6 +11,7 @@ require_relative "rooibos/message"
 require_relative "rooibos/command"
 require_relative "rooibos/runtime"
 require_relative "rooibos/router"
+require_relative "rooibos/welcome"
 
 # The Elm Architecture for Ruby.
 #
@@ -103,17 +104,17 @@ module Rooibos
   #   # Verbose:
   #   case message
   #   in [:stats, *rest]
-  #     new_child, cmd = StatsPanel::UPDATE.call(rest, model.stats)
+  #     new_child, cmd = StatsPanel::Update.call(rest, model.stats)
   #     mapped = cmd ? Command.map(cmd) { |r| [:stats, *r] } : nil
   #     [new_child, mapped]
   #   end
   #
   #   # Concise:
-  #   Rooibos.delegate(message, :stats, StatsPanel::UPDATE, model.stats)
+  #   Rooibos.delegate(message, :stats, StatsPanel::Update, model.stats)
   def self.delegate(message, prefix, child_update, child_model)
     return nil unless message.is_a?(Array) && message.first == prefix
 
-    rest = message[1..]
+    rest = message[1]
     new_child, command = child_update.call(rest, child_model)
     wrapped = command ? route(command, prefix) : nil
     [new_child, wrapped]

data/mise.toml

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: LGPL-3.0-or-later
 
 [tools]
-ruby = "4.0.0"
+ruby = "4.0.1"
 rust = "1.91.1"
 python = "3.12"
 pre-commit = "latest"

data/rbs_collection.lock.yaml

@@ -66,11 +66,11 @@ gems:
   source:
     type: stdlib
 - name: prism
-  version: 1.7.0
+  version: 1.8.0
   source:
     type: rubygems
 - name: ratatui_ruby
-  version: 0.10.2
+  version: 1.1.0
   source:
     type: rubygems
 - name: ratatui_ruby-devtools

data/sig/concurrent.rbs

@@ -39,6 +39,9 @@ module Concurrent
 
     # Races multiple futures/events, returning when any resolves.
     def self.any_event: (*Future[untyped] | ResolvableEvent) -> ResolvableEvent
+
+    # Joins multiple futures, resolving when all complete.
+    def self.zip_futures: (*Future[untyped]) -> Future[Array[untyped]]
   end
 
   # Single-element blocking container for synchronization.

data/sig/gem.rbs

@@ -0,0 +1,20 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+# Local shim for Gem::Version#segments not in stdlib RBS.
+# TODO: Remove when upstream RBS adds this method.
+
+module Gem
+  class Version
+    # Returns version segments as an array of integers and strings.
+    def segments: () -> Array[Integer | String]
+  end
+end
+
+# Local shim for RatatuiRuby.terminal_size alias not in upstream RBS.
+# The Ruby gem has: alias terminal_size get_terminal_size
+module RatatuiRuby
+  def self.terminal_size: () -> RatatuiRuby::Layout::Rect
+end

data/sig/rooibos/cli.rbs

@@ -0,0 +1,42 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module CLI
+    COMMANDS: Hash[String, singleton(Commands::New) | singleton(Commands::Run)]
+
+    def self.call: (Array[String]) -> void
+    def self.usage: () -> String
+
+    module Commands
+      module New
+        # Options hash from parse_options.
+        type options = Hash[Symbol, bool | String]
+
+        BUNDLE_GEM_DEFAULTS: Array[String]
+
+        def self.call: (Array[String]) -> void
+        def self.usage: () -> String
+        def self.parse_options: (Array[String]) -> options
+        def self.create_app: (String, Array[String], options) -> void
+        def self.build_bundle_gem_args: (Array[String]) -> Array[String]
+        def self.git_enabled?: (Array[String]) -> bool
+        def self.make_initial_commit: (Pathname) -> void
+        def self.to_module_name: (String) -> String
+        def self.fix_gemspec_placeholders: (String) -> String
+        def self.exe_template: (String, String) -> String
+        def self.app_template: (String, String) -> String
+        def self.test_template: (String, String) -> String
+      end
+
+      module Run
+        def self.call: (Array[String]) -> void
+        def self.usage: () -> String
+        def self.run_app: () -> void
+        def self.find_project_root: () -> Pathname?
+      end
+    end
+  end
+end