rooibos 0.6.2 → 0.7.0

data/lib/rooibos/runtime.rb

@@ -165,7 +165,7 @@ module Rooibos
     # SPDX-SnippetEnd
     #++
     def self.normalize_init(result)
-      normalize_update_return(result, nil)
+      Transition.from(result, nil).to_a
     end
 
     # Sentinel value avoids accidentally quitting from application exceptions.
@@ -185,6 +185,9 @@ module Rooibos
             @model, @command = @init_callable.call
             validate_ractor_shareable!(@command, "command")
             validate_ractor_shareable!(@model, "model")
+            validate_ractor_shareable!(@update, "update")
+            validate_ractor_shareable!(@view, "view")
+            validate_ractor_shareable!(@init_callable, "init")
             dispatch_command
 
             loop do
@@ -214,7 +217,6 @@ module Rooibos
           frame.render_widget(widget, frame.area)
         end
       end
-
       # Enforces invariants
       private def fragment_from_kwargs(root_fragment, model: nil, view: nil, update: nil, command: nil)
         if root_fragment
@@ -228,7 +230,13 @@ module Rooibos
           fragment.const_set(:Model, model)
           fragment.const_set(:View, view)
           fragment.const_set(:Update, update)
-          fragment.const_set(:Init, -> { [model, command] })
+          fragment.const_set(:InitCommand, command)
+          # Init uses a module singleton method accessing constants via self.
+          # Module objects are always shareable, so this makes init shareable.
+          fragment.define_singleton_method(:call) do
+            [self::Model, self::InitCommand] # steep:ignore UnknownConstant
+          end
+          fragment.const_set(:Init, fragment)
           fragment
         end
       end
@@ -241,18 +249,20 @@ module Rooibos
       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
+            @fragment::Init
           else
             raise Rooibos::Error::Invariant, "Fragment::Init must respond to :call"
           end
         else
           if @fragment.const_defined?(:Model)
             if @fragment::Model.respond_to?(:new)
-              -> { @fragment::Model.new }
+              # Synthesize an Init using module singleton method.
+              # Module objects are always shareable, so accessing
+              # constants via self makes this Ractor-shareable.
+              unless @fragment.respond_to?(:call)
+                @fragment.define_singleton_method(:call) { self::Model.new } # steep:ignore UnknownConstant
+              end
+              @fragment
             else
               raise Rooibos::Error::Invariant, "Fragment::Model must respond to :new; or pass Fragment::Init instead"
             end
@@ -275,46 +285,6 @@ module Rooibos
           "View returned nil. Return a widget, or use TUI#clear for an empty screen."
       end
 
-      # 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?(:rooibos_command?) && command.rooibos_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?(:rooibos_command?) &&
-              !Ractor.shareable?(result)
-
-            warn "WARNING: Update returned [model, #{command.class}] but #{command.class} " \
-              "responds to #call without #rooibos_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?(:rooibos_command?) && result.rooibos_command?
-          command = result #: Rooibos::Command::execution
-          return [previous_model, command]
-        end
-
-        # Case 3: Result is the new model
-        [result, nil]
-      end
-
       # Validates an object is Ractor-shareable (deeply frozen).
       #
       # Models and messages must be shareable for future Ractor support.
@@ -322,12 +292,20 @@ module Rooibos
       #
       # Only enforced in debug mode (and tests). Production skips this check
       # for performance; mutable objects will still cause bugs, but silently.
+      #
+      # This method TRIES to make the object shareable (which auto-freezes).
+      # It only fails if the object captures non-shareable state (e.g., a
+      # lambda defined inside a method that captures self).
       private def validate_ractor_shareable!(object, name)
         return unless RatatuiRuby::Debug.enabled?
         return if Ractor.shareable?(object)
 
+        # Try to make it shareable - this will freeze it and succeed for
+        # most objects. It only fails for objects that truly can't be shared.
+        Ractor.make_shareable(object)
+      rescue Ractor::IsolationError => e
         raise Rooibos::Error::Invariant,
-          "#{name.capitalize} is not Ractor-shareable. Use Ractor.make_shareable or Object#freeze."
+          "#{name} cannot be made Ractor-shareable: #{e.message}"
       end
 
       private def handle_ratatui_event
@@ -343,7 +321,7 @@ module Rooibos
           return true
         end
 
-        @model, @command = normalize_update_return(@update.call(message, @model), @model)
+        @model, @command = Transition.from(@update.call(message, @model), @model).to_a
         validate_ractor_shareable!(@model, "model")
         throw QUIT if Command::Exit === @command
         dispatch_command
@@ -359,7 +337,7 @@ module Rooibos
           break if background_message == QUEUE_EMPTY
 
           result = @update.call(background_message, @model)
-          @model, @command = normalize_update_return(result, @model)
+          @model, @command = Transition.from(result, @model).to_a
           return unless dispatch
 
           validate_ractor_shareable!(@model, "model")
@@ -379,6 +357,13 @@ module Rooibos
           # Remove cancelled future from pending list so sync doesn't wait for it
           @pending_futures.delete(entry.future) if entry
           nil
+        elsif Command.const_get(:Separate) === @command
+          # Internal: dispatch each command independently (no Message::Batch)
+          @command.commands.each do |cmd|
+            entry = @lifecycle.run_async(cmd, @message_queue)
+            @pending_futures << entry.future if entry.future
+          end
+          nil # No single future to return
         elsif @command.respond_to?(:rooibos_command?) && @command.rooibos_command?
           entry = @lifecycle.run_async(@command, @message_queue)
           entry.future

data/lib/rooibos/test_helper.rb

@@ -117,5 +117,27 @@ module Rooibos
         raise failure_msg
       end
     end
+
+    # ===========================================================================
+    # Shared Fixtures
+    #
+    # Ractor-shareable callables for common test patterns
+    # ===========================================================================
+
+    # Simple view that just clears the terminal
+    ClearView = -> (_model, tui) { tui.clear }
+
+    # Update that exits on 'q' key, passes through all other messages
+    ExitOnQUpdate = -> (msg, model) do
+      case msg
+      when RatatuiRuby::Event::Key
+        (msg.code == "q") ? [model, Rooibos::Command.exit] : [model, nil]
+      else
+        [model, nil]
+      end
+    end
+
+    # Update that exits immediately on any key
+    ExitOnAnyKeyUpdate = -> (_msg, model) { [model, Rooibos::Command.exit] }
   end
 end

data/lib/rooibos/transition.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  # Transition represents a normalized [model, command] tuple from Update.
+  # Use Transition.from to convert DWIM return values.
+  class Transition < Data.define(:model, :command)
+    # Creates a Transition from an Update return value.
+    #
+    # Handles:
+    # <tt>nil</tt>:: preserve previous model, no command
+    # <tt>model</tt>:: new model, no command
+    # <tt>command</tt>:: previous model, command
+    # <tt>[model, command]</tt>:: as-is
+    def self.from(update_return, previous_model)
+      case update_return
+      when nil
+        new(model: previous_model, command: nil)
+      when -> (r) { r.respond_to?(:rooibos_command?) && r.rooibos_command? }
+        new(model: previous_model, command: update_return)
+      when Array
+        case update_return
+        in [model, command] if command.nil? || (command.respond_to?(:rooibos_command?) && command.rooibos_command?)
+          new(model:, command:)
+        else
+          warn_suspicious_callable(update_return)
+          new(model: update_return, command: nil)
+        end
+      else
+        new(model: update_return, command: nil)
+      end
+    end
+
+    # Creates an initial Transition with no command.
+    def self.initial(model)
+      new(model:, command: nil)
+    end
+
+    # Returns new Transition with an updated model, or self if nil.
+    def with_model(new_model)
+      return self unless new_model
+
+      Transition.new(model: new_model, command:)
+    end
+
+    # Returns new Transition with an updated command, or self if nil.
+    def with_command(new_command)
+      return self unless new_command
+
+      Transition.new(model:, command: new_command)
+    end
+
+    # Returns new Transition with command added (batched if existing).
+    def with_added_command(new_command)
+      return self unless new_command
+      return with_command(new_command) unless command
+
+      with_command(Command.batch(command, new_command))
+    end
+
+    # Returns new Transition with command added via Separate (for observe).
+    def with_separate_command(new_command)
+      return self unless new_command
+      return with_command(new_command) unless command
+
+      with_command(Command.const_get(:Separate).new(commands: [command, new_command]))
+    end
+
+    # Converts to [model, command] tuple.
+    def to_a = [model, command]
+    alias to_ary to_a
+    alias deconstruct to_a
+
+    # Warns if tuple looks like [model, command] but command isn't marked as such.
+    private_class_method def self.warn_suspicious_callable(update_return) # :nodoc:
+      return unless RatatuiRuby::Debug.enabled?
+
+      _, suspect = update_return
+      return unless suspect.respond_to?(:call)
+      return if Ractor.shareable?(update_return)
+
+      warn "WARNING: Update returned [model, #{suspect.class}] but #{suspect.class} " \
+        "responds to #call without #rooibos_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."
+    end
+  end
+end

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.6.2"
+  VERSION = "0.7.0"
 end

data/lib/rooibos.rb

@@ -9,6 +9,8 @@ require_relative "rooibos/version"
 require_relative "rooibos/error"
 require_relative "rooibos/message"
 require_relative "rooibos/command"
+require_relative "rooibos/transition"
+require_relative "rooibos/configuration"
 require_relative "rooibos/runtime"
 require_relative "rooibos/router"
 require_relative "rooibos/welcome"
@@ -62,61 +64,4 @@ module Rooibos
   def self.normalize_init(result)
     Runtime.normalize_init(result)
   end
-
-  # Wraps a command with a routing prefix.
-  #
-  # 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 fragment command results in Fractal Architecture.
-  #
-  # [command] The child fragment command to wrap.
-  # [prefix] Symbol prepended to results (e.g., <tt>:stats</tt>).
-  #
-  # === Example
-  #
-  #   # Verbose:
-  #   Command.map(child_fragment.fetch_command) { |r| [:stats, *r] }
-  #
-  #   # Concise:
-  #   Rooibos.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 fragment's UPDATE.
-  #
-  # 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.
-  #
-  # This method handles the dispatch. It checks the prefix, calls the child,
-  # and wraps any command. Returns <tt>nil</tt> if the prefix does not match.
-  #
-  # [message] Incoming message (e.g., <tt>[:stats, :system_info, {...}]</tt>).
-  # [prefix] Expected prefix symbol (e.g., <tt>:stats</tt>).
-  # [child_update] The child's UPDATE callable.
-  # [child_model] The child's current model.
-  #
-  # === Example
-  #
-  #   # Verbose:
-  #   case message
-  #   in [:stats, *rest]
-  #     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)
-  def self.delegate(message, prefix, child_update, child_model)
-    return nil unless message.is_a?(Array) && message.first == prefix
-
-    rest = message[1]
-    new_child, command = child_update.call(rest, child_model)
-    wrapped = command ? route(command, prefix) : nil
-    [new_child, wrapped]
-  end
 end

data/sig/rooibos/cli.rbs

@@ -29,6 +29,7 @@ module Rooibos
         def self.exe_template: (String, String) -> String
         def self.app_template: (String, String) -> String
         def self.test_template: (String, String) -> String
+        def self.rubocop_template: () -> String
       end
 
       module Run

data/sig/rooibos/command.rbs

@@ -29,6 +29,21 @@ module Rooibos
     def self.new: () -> instance
   end
 
+  # Internal wrapper for multiple commands to be dispatched separately.
+  # Router DSL uses this to return multiple commands from observe + keymap
+  # without triggering Message::Batch. The runtime unwraps this and dispatches
+  # each command independently.
+  class Separate < Data
+    include Custom
+
+    attr_reader commands: Array[execution?]
+
+    def self.new: (commands: Array[execution?]) -> instance
+
+    # Stub - Separate is a sentinel unwrapped by runtime before dispatch.
+    def call: (Outlet out, Concurrent::Cancellation token) -> void
+  end
+
   # Runs a shell command and routes its output back as messages.
   class System < Data
     attr_reader command: String
@@ -107,6 +122,12 @@ module Rooibos
   def self.custom: (^(Outlet, Concurrent::Cancellation) -> void callable, ?grace_period: Float?) -> _Command
                  | (?grace_period: Float?) { (Outlet, Concurrent::Cancellation) -> void } -> _Command
 
+  # Delivers a message to Update.
+  def self.deliver: (Object message) -> Deliver
+
+  # Bubbles a message outward through the fragment hierarchy.
+  def self.bubble: (Object message) -> Bubble
+
   # Creates a one-shot timer command.
   def self.wait: (Float seconds, Symbol tag) -> Wait
 
@@ -160,6 +181,29 @@ module Rooibos
     def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
   end
 
+  # Command that delivers a message to Update.
+  class Deliver < Data
+    include Custom
+
+    attr_reader message: Object
+
+    def self.new: (message: Object) -> instance
+
+    def call: (Outlet out, Concurrent::Cancellation token) -> void
+  end
+
+  # Command that bubbles a message outward through the fragment hierarchy.
+  class Bubble < Data
+    include Custom
+
+    attr_reader message: Object
+
+    def self.new: (message: Object) -> instance
+
+    # Raises an error if called — outer fragments should handle bubbles.
+    def call: (Outlet out, Concurrent::Cancellation token) -> void
+  end
+
   # Minimal interface for callables accepted by Lifecycle.run_sync.
   interface _Callable
     def call: (Outlet out, Concurrent::Cancellation token) -> void

data/sig/rooibos/configuration.rbs

@@ -0,0 +1,20 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  # Immutable Mealy machine (state, input) pair.
+  class Configuration < Data
+    attr_reader message: message
+    attr_reader model: _DataModel
+
+    # Derives a new Configuration with an updated model.
+    def with_model: (_DataModel? new_model) -> Configuration
+
+    # Destructures into [message, model] array.
+    def to_a: () -> [message, _DataModel]
+    alias to_ary to_a
+    alias deconstruct to_a
+  end
+end

data/sig/rooibos/message.rbs

@@ -198,5 +198,17 @@ module Rooibos
     def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
     def method_missing: (Symbol name, *untyped args, **untyped kwargs) ?{ () -> untyped } -> bool
   end
+
+  # Message wrapper for bubbled messages from child fragments.
+  class Bubbled < Data
+    include Predicates
+
+    attr_reader message: message
+
+    def self.new: (message: message) -> instance
+
+    def bubbled?: () -> bool
+    def deconstruct_keys: (Array[Symbol]? keys) -> { type: Symbol, message: message }
+  end
 end
 end

data/sig/rooibos/router/action.rbs

@@ -0,0 +1,33 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Action type: either a LambdaAction or RoutedAction.
+    type action = LambdaAction | RoutedAction
+
+    # Lambda action - calls handler directly.
+    class LambdaAction < Data
+      attr_reader name: Symbol?
+      attr_reader handler: handler
+
+      def routed?: () -> false
+
+      # Applies the handler and returns a Transition.
+      def apply: (message, _DataModel, Routes) -> Transition
+    end
+
+    # Routed action - wraps message and delegates through route to fragment.
+    class RoutedAction < Data
+      attr_reader name: Symbol
+      attr_reader fragment: Module
+
+      def routed?: () -> true
+
+      # Applies via route delegation and returns a Transition.
+      def apply: (message, _DataModel, Routes) -> Transition
+    end
+  end
+end

data/sig/rooibos/router/actions.rbs

@@ -0,0 +1,27 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Collection of named actions.
+    class Actions < Data
+      include Enumerable[action]
+
+      attr_reader rules: Array[action]
+
+      def initialize: (?rules: Array[action]) -> void
+
+      # Registers an action by name.
+      def add: (Symbol name, handler | Module handler_arg) -> void
+
+      # Looks up an action by name.
+      def []: (Symbol name) -> action
+
+      # Iterates over all actions.
+      def each: () { (action) -> void } -> Array[action]
+              | () -> Enumerator[action, Array[action]]
+    end
+  end
+end

data/sig/rooibos/router/flow/dispatch.rbs

@@ -0,0 +1,29 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    module Flow
+      # Shared dispatch logic mixed into Inward and Outward flows.
+      module Dispatch : _HasRoutes
+        # Interface for classes that include Dispatch.
+        interface _HasRoutes
+          def routes: () -> Routes
+        end
+
+        private
+
+        # Runs all rules, accumulating model changes and separate commands.
+        def run_all: (Observes rules, message, _DataModel) -> Transition
+
+        # Applies the first matching rule. Returns Transition or nil.
+        def apply_first_matching: (Enumerable[Rule] rules, Configuration config, Transition transition) -> Transition?
+
+        # Merges model from new_transition, keeps commands separate.
+        def separate_commands: (Transition transition, Transition new_transition) -> Transition
+      end
+    end
+  end
+end

data/sig/rooibos/router/flow/inward.rbs

@@ -0,0 +1,37 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    module Flow
+      # Inward flow: messages traveling toward the leaves.
+      class Inward < Data
+        include Dispatch
+
+        attr_reader observes: Observes
+        attr_reader receives: Receives
+        attr_reader forwards: Forwards
+        attr_reader otherwises: Otherwises
+        attr_reader routes: Routes
+
+        def initialize: (
+          observes: Observes,
+          receives: Receives,
+          forwards: Forwards,
+          otherwises: Otherwises,
+          routes: Routes
+        ) -> void
+
+        # Dispatches a message through observe -> receive -> forward -> otherwise.
+        def call: (message, _DataModel) -> Transition
+
+        private
+
+        # Validates all forward and otherwise targets resolve.
+        def validate_routes!: () -> void
+      end
+    end
+  end
+end

data/sig/rooibos/router/flow/outward.rbs

@@ -0,0 +1,36 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    module Flow
+      # Outward flow: bubbled messages traveling toward the root.
+      class Outward < Data
+        include Dispatch
+
+        attr_reader observes: Observes
+        attr_reader receives: Receives
+        attr_reader routes: Routes
+
+        def initialize: (
+          observes: Observes,
+          receives: Receives,
+          routes: Routes
+        ) -> void
+
+        # Sentinel: intercept consumed the bubble.
+        INTERCEPTED: Object
+
+        # Dispatches a bubbled message through observe -> intercept.
+        def call: (message, _DataModel) -> Transition
+
+        private
+
+        # Applies the first matching intercept rule.
+        def intercept_first_matching: (Receives rules, Configuration config, Transition transition) -> Transition?
+      end
+    end
+  end
+end

data/sig/rooibos/router/forward.rbs

@@ -0,0 +1,35 @@
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Router
+    # Forward rule - matches messages and delegates to route(s).
+    class Forward < Data
+      include Rule
+
+      # Targets: a single target, array of targets, or ALL_ROUTES sentinel.
+      type targets = route_target | Array[route_target] | all_routes_sentinel
+
+      attr_reader predicate: predicate
+      attr_reader targets: targets
+      attr_reader envelope: Symbol?
+      attr_reader guard: Guard
+
+      def initialize: (
+        predicate: predicate,
+        ?targets: targets,
+        ?envelope: Symbol?,
+        ?guard: Guard?
+      ) -> void
+
+      # Routes the message to target route(s) and returns a Transition.
+      def apply: (message, _DataModel, Routes) -> Transition
+
+      private
+
+      def envelop: (message msg) -> (message | Message::Routed)
+    end
+  end
+end