rooibos 0.7.2 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84b4f67bd8240b412f78b91e8e8e52af841e6438694bb51013519d3ba6e28fe7
-  data.tar.gz: 63ac12eba2aee98ecf595aa948d457babc3533ce66b2d9fa20eee5257e26bcf1
+  metadata.gz: 978bf3a71ec2efd09d2b4d1fd7f5d8c04bfe9af2705df1b26f3f341a0e56e1e3
+  data.tar.gz: 6ab63cbe1f40881689c49a4990e71f4e4ba1dcb5b76f81d27b9fe96a9257121d
 SHA512:
-  metadata.gz: 193556d2bf1093e16c1229162e579113c3d4a75c472cf37c071db593f4d1506405de0c7eaf1bccfcb9b2555335ed304c64d25f1cd08231c7c084a58bfa9ba731
-  data.tar.gz: a8ab3b783bc7f40527f05b15d7c32e971f70518cb9a4769f5d0312590ff866773debe986dcfb93ab36e8cf61a95dc40f9b91db842557633b36333296ffaf6fbf
+  metadata.gz: 4e89b8ec3d0fa1377204256c9bcd2a6ba9cbdea6e862b3b041b82e35482a84449308737ed087e13ef65266bce291dae8e35b7e6d778bc319dbbb6e1df25cdfa5
+  data.tar.gz: e64af325d6c7f4e578390d541f5414d5838aaa434ae8fd828d352b6d949b02fa1ea12102a41f3e0da01342e2ba5d2fa633901b8e3aa728300c54defc2ad3f879

data/REUSE.toml

@@ -8,6 +8,11 @@ path = 'Gemfile.lock'
 SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
 SPDX-License-Identifier = "CC0-1.0"
 
+[[annotations]]
+path = 'rbs_collection.lock.yaml'
+SPDX-FileCopyrightText = "2026 Kerrick Long <me@kerricklong.com>"
+SPDX-License-Identifier = "CC0-1.0"
+
 [[annotations]]
 path = 'README.rdoc'
 SPDX-FileCopyrightText = "2025 Kerrick Long <me@kerricklong.com>"

data/lib/rooibos/cli/commands/new.rb

@@ -381,7 +381,7 @@ module Rooibos
               rooibos: lib/rooibos/rubocop.yml
 
             AllCops:
-              TargetRubyVersion: 3.2
+              TargetRubyVersion: 3.3
 
             Style/StringLiterals:
               EnforcedStyle: double_quotes

data/lib/rooibos/command/clock.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Command
+    # A one-shot clock command.
+    #
+    # Applications display the time, throttle refreshes, and show
+    # "last updated 30 seconds ago." All of these call <tt>Time.now</tt>.
+    # But <tt>Time.now</tt> in Update is a side effect. The same model
+    # and message produce different results depending on when you call
+    # them. Testing becomes non-deterministic.
+    #
+    # This command waits, then sends a <tt>Message::Clock</tt> with the
+    # current time. It responds to cancellation cooperatively. When
+    # canceled, it sends <tt>Message::Canceled</tt> so you know the
+    # clock stopped.
+    #
+    # Use it for periodic time updates, scheduling, or any feature that
+    # asks "what time is it?"
+    #
+    # Prefer the <tt>Command.clock</tt> factory method for convenience.
+    #
+    # === Example: Periodic refresh
+    #
+    #   def update(msg, model)
+    #     case msg
+    #     in { type: :clock, envelope: :refresh, time: }
+    #       [model.with(current_time: time.utc.to_s),
+    #        Command.clock(1, :refresh)]
+    #     end
+    #   end
+    #
+    # === Example: "Last updated" display
+    #
+    #   def update(msg, model)
+    #     case msg
+    #     in { type: :clock, envelope: :clock, time: }
+    #       ago = (time - model.last_fetch).round
+    #       [model.with(status: "Updated #{ago}s ago"),
+    #        Command.clock(1, :clock)]
+    #     end
+    #   end
+    class Clock < Data.define(:seconds, :envelope)
+      include Custom
+      include Timed
+
+      private def timed_response(_start_time)
+        Message::Clock.new(envelope:, time: Time.now)
+      end
+    end
+  end
+end

data/lib/rooibos/command/random.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Command
+    # A command that generates a random value.
+    #
+    # Games roll dice. Encryption needs keys. Shuffling needs seeds.
+    # All of these call <tt>Kernel#rand</tt> or <tt>Random</tt>. But
+    # randomness in Update is a side effect: the same model and message
+    # would produce different results on each call. Testing would become
+    # fragile and non-deterministic.
+    #
+    # This command delegates to Ruby's <tt>Random</tt> class through
+    # the runtime. Update receives the result as a
+    # <tt>Message::Random</tt>.
+    #
+    # Use it for dice rolls, shuffles, key generation, or any feature
+    # that needs random values without side effects in Update.
+    #
+    # Prefer the <tt>Command.random</tt> factory method for convenience.
+    #
+    # === Example: Dice roll
+    #
+    #   def update(msg, model)
+    #     case msg
+    #     in { type: :random, envelope: :roll, value: }
+    #       model.with(die_face: value)
+    #     end
+    #   end
+    #
+    # === Example: Random float
+    #
+    #   def update(msg, model)
+    #     case msg
+    #     in { type: :random, envelope: :spawn_chance, value: }
+    #       model.with(should_spawn: value < 0.3)
+    #     end
+    #   end
+    class Random < Data.define(:args, :envelope)
+      include Custom
+
+      # Executes the random command.
+      #
+      # Without a leading symbol, calls <tt>Random.rand</tt> with the
+      # stored arguments. With a leading symbol, calls that method on
+      # <tt>Random</tt> via <tt>public_send</tt>.
+      #
+      # [out] Outlet for sending messages.
+      # [token] Cancellation token from the runtime.
+      def call(out, token)
+        if token.canceled?
+          out.put(Message::Canceled.new(command: self))
+          return
+        end
+
+        value = if args.first.is_a?(Symbol)
+          method_name = args.first
+          ::Random.public_send(method_name, *args[1..])
+        else
+          ::Random.rand(*args)
+        end
+        out.put(Ractor.make_shareable(Message::Random.new(envelope:, value:)))
+      end
+    end
+  end
+end

data/lib/rooibos/command/timed.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Command
+    # Shared behavior for commands that wait, then respond.
+    #
+    # Timer and clock commands follow the same pattern: wait for
+    # <tt>seconds</tt>, check for cancellation, then send a response.
+    # Duplicating the cancellation dance is error-prone.
+    #
+    # This module extracts the wait-cancel-respond skeleton. Include
+    # it in any <tt>Data.define(:seconds, :envelope)</tt> command and
+    # implement <tt>timed_response</tt> to build the success message.
+    #
+    # === Example
+    #
+    #   class MyTimer < Data.define(:seconds, :envelope)
+    #     include Custom
+    #     include Timed
+    #
+    #     private def timed_response(start_time)
+    #       Message::Timer.new(envelope:, elapsed: Time.now - start_time)
+    #     end
+    #   end
+    #
+    module Timed # :nodoc:
+      # Cooperative cancellation needs no grace period.
+      # The command responds instantly to cancellation via
+      # <tt>Concurrent::Cancellation.timeout</tt>.
+      def rooibos_cancellation_grace_period
+        0
+      end
+
+      # Waits for <tt>seconds</tt>, then sends the result of
+      # <tt>timed_response</tt>. If canceled, sends
+      # <tt>Message::Canceled</tt> instead.
+      #
+      # [out] Outlet for sending messages.
+      # [token] Cancellation token from the runtime.
+      def call(out, token)
+        start_time = Time.now
+        timer_cancellation, _origin = Concurrent::Cancellation.timeout(seconds)
+        combined = token.join(timer_cancellation)
+        combined.origin.wait
+
+        if token.canceled?
+          out.put(Message::Canceled.new(command: self))
+        else
+          out.put(Ractor.make_shareable(timed_response(start_time)))
+        end
+      end
+    end
+    private_constant :Timed
+  end
+end

data/lib/rooibos/command/wait.rb

@@ -49,34 +49,11 @@ module Rooibos
     #   end
     class Wait < Data.define(:seconds, :envelope)
       include Custom
+      include Timed
 
-      # Cooperative cancellation needs no grace period.
-      # The command responds instantly to cancellation via
-      # <tt>Concurrent::Cancellation.timeout</tt>.
-      def rooibos_cancellation_grace_period
-        0
-      end
-
-      # Executes the timer.
-      #
-      # Waits for <tt>seconds</tt>, then sends <tt>TimerResponse</tt>.
-      # If canceled, sends <tt>Message::Canceled</tt> instead.
-      #
-      # [out] Outlet for sending messages.
-      # [token] Cancellation token from the runtime.
-      def call(out, token)
-        start_time = Time.now
-        timer_cancellation, _origin = Concurrent::Cancellation.timeout(seconds)
-        combined = token.join(timer_cancellation)
-        combined.origin.wait
-
-        if token.canceled?
-          out.put(Message::Canceled.new(command: self))
-        else
-          elapsed = Time.now - start_time
-          response = Message::Timer.new(envelope:, elapsed:)
-          out.put(Ractor.make_shareable(response))
-        end
+      private def timed_response(start_time)
+        elapsed = Time.now - start_time
+        Message::Timer.new(envelope:, elapsed:)
       end
     end
   end

data/lib/rooibos/command.rb

@@ -9,7 +9,10 @@ require "concurrent-edge"
 require_relative "command/custom"
 require_relative "command/outlet"
 require_relative "command/lifecycle"
+require_relative "command/timed"
 require_relative "command/wait"
+require_relative "command/clock"
+require_relative "command/random"
 require_relative "command/batch"
 require_relative "command/all"
 require_relative "command/http"
@@ -86,6 +89,16 @@ module Rooibos
       def call(_out, _token)
         raise "Separate command should never be dispatched directly"
       end
+
+      def extract_bubbles # :nodoc:
+        bubbles, rest = commands.partition { |c| c.is_a?(Bubble) }
+        remaining = case rest.size
+        when 0 then nil
+        when 1 then rest.first
+        else Separate.new(commands: rest)
+        end
+        [bubbles, remaining]
+      end
     end
     private_constant :Separate
 
@@ -584,6 +597,32 @@ module Rooibos
     # [tag] Symbol to tag the result message.
     singleton_class.alias_method :tick, :wait
 
+    # Creates a wall-clock time command.
+    #
+    # Waits for +seconds+ then sends +Message::Clock+ with the current time.
+    # Use for displaying time, throttling refreshes, or scheduling.
+    #
+    # [seconds] Duration to wait (Float or Integer).
+    # [envelope] Symbol to tag the result message.
+    def self.clock(seconds, envelope)
+      Clock.new(seconds:, envelope:)
+    end
+
+    # Creates a random value command.
+    #
+    # Delegates to Ruby's <tt>Random</tt> class through the runtime.
+    # The last argument is always the envelope. Everything before it
+    # maps to <tt>Random</tt>.
+    #
+    # Without a leading symbol, calls <tt>Random#rand</tt>.
+    # With a leading symbol, calls that method on <tt>Random</tt>.
+    #
+    # [*args] Arguments to pass to <tt>Random</tt>, followed by the envelope.
+    def self.random(*args)
+      envelope = args.pop
+      Random.new(args: args.freeze, envelope:)
+    end
+
     # Creates a parallel batch command.
     #
     # Applications fetch data from multiple sources. Dashboard panels load

data/lib/rooibos/message/clock.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # Response from a clock command.
+    #
+    # Long-lived applications display the time. Dashboards show "last updated
+    # 30 seconds ago." Schedulers fire actions at specific hours. All of these
+    # need wall-clock time. But calling <tt>Time.now</tt> in Update is a side
+    # effect—the same model and message produce different results depending
+    # on when you call them.
+    #
+    # This response carries the wall-clock time from the runtime. Update
+    # pattern-matches on the envelope to distinguish multiple clocks.
+    #
+    # Use it to handle <tt>Command.clock</tt> completions.
+    #
+    # === Example
+    #
+    #   case msg
+    #   in { type: :clock, envelope: :refresh, time: }
+    #     [model.with(last_refresh: time), Command.clock(1, :refresh)]
+    #   in { type: :clock, envelope: :display, time: }
+    #     model.with(current_time: time.utc.to_s)
+    #   end
+    #
+    class Clock < Data.define(:envelope, :time)
+      include Predicates
+      # Returns <tt>true</tt> for clock responses.
+      def clock?
+        true
+      end
+    end
+  end
+end

data/lib/rooibos/message/random.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module Rooibos
+  module Message
+    # Response from a random command.
+    #
+    # Games roll dice. Encryption needs keys. Shuffling needs seeds.
+    # All of these call <tt>Kernel#rand</tt> or <tt>Random</tt>. But
+    # randomness in Update is a side effect: the same model and message
+    # would produce different results on each call. Testing would become
+    # fragile.
+    #
+    # This response carries the random value from the runtime. Update
+    # pattern-matches on the envelope to distinguish multiple rolls.
+    #
+    # Use it to handle <tt>Command.random</tt> completions.
+    #
+    # === Example
+    #
+    #   case msg
+    #   in { type: :random, envelope: :roll_die, value: }
+    #     model.with(roll: value)
+    #   in { type: :random, envelope: :shuffle_seed, value: }
+    #     model.with(sort_seed: value)
+    #   end
+    #
+    class Random < Data.define(:envelope, :value)
+      include Predicates
+      # Returns +true+ for random responses.
+      def random?
+        true
+      end
+    end
+  end
+end

data/lib/rooibos/message.rb

@@ -125,6 +125,8 @@ module Rooibos
 end
 
 require_relative "message/timer"
+require_relative "message/clock"
+require_relative "message/random"
 require_relative "message/open"
 require_relative "message/http_response"
 require_relative "message/system/batch"

data/lib/rooibos/router/flow/outward.rb

@@ -12,8 +12,8 @@ module Rooibos
     module Flow
       # Outward flow: messages traveling toward the root.
       #
-      # Observe → intercept.
-      class Outward < Data.define(:observes, :receives, :routes)
+      # Observe → intercept → forward.
+      class Outward < Data.define(:observes, :receives, :forwards, :routes)
         include Dispatch
 
         # Sentinel: intercept consumed the bubble. Non-nil so
@@ -25,6 +25,7 @@ module Rooibos
           transition = run_all(observes, message, model)
           config = Configuration.new(message:, model: transition.model)
           intercept_first_matching(receives, config, transition) ||
+            apply_first_matching(forwards, config, transition) ||
             transition
         end
 

data/lib/rooibos/router/registry/forwards.rb

@@ -23,22 +23,22 @@ module Rooibos
         envelope: as
       ))
 
-      def add_events(keys, to:, as: nil, guard: nil, when: nil, unless: nil) = add(Forward.new(
+      def add_events(keys, to: nil, as: nil, broadcast: false, broadcast_to: nil, guard: nil, when: nil, unless: nil) = add(Forward.new(
         predicate: Predicate::Events.new(keys:),
-        targets: to,
+        targets: resolve_targets(to:, broadcast:, broadcast_to:),
         envelope: as,
         guard: Guard.from(guard:, when: binding.local_variable_get(:when), unless: binding.local_variable_get(:unless))
       ))
 
-      def add_routed(envelopes, to:, as: nil) = add(Forward.new(
+      def add_routed(envelopes, to: nil, as: nil, broadcast: false, broadcast_to: nil) = add(Forward.new(
         predicate: Predicate::RoutedEnvelopes.new(envelopes:),
-        targets: to,
+        targets: resolve_targets(to:, broadcast:, broadcast_to:),
         envelope: as
       ))
 
-      def add_custom(predicate, to:, as: nil, **guard_opts) = add(Forward.new(
+      def add_custom(predicate, to: nil, as: nil, broadcast: false, broadcast_to: nil, **guard_opts) = add(Forward.new(
         predicate:,
-        targets: to,
+        targets: resolve_targets(to:, broadcast:, broadcast_to:),
         envelope: as,
         guard: Guard.from(**guard_opts)
       ))

data/lib/rooibos/router/router_update.rb

@@ -11,6 +11,7 @@ module Rooibos
     # :stopdoc:
     # Encapsulates dispatch logic - given frozen rule sets, processes messages.
     class RouterUpdate < Data.define(:inward, :outward)
+      Separate = Command.const_get(:Separate)
       def call(message, model)
         case message
         when Message::Bubbled then dispatch_outward(message.message, model)
@@ -20,18 +21,24 @@ module Rooibos
 
       private def dispatch_inward(message, model)
         transition = inward.call(message, model)
+        transition = extract_bubbles(transition)
+        transition = transition.with(command: nil) if transition.command.equal?(Flow::Outward::INTERCEPTED)
+        transition.to_a
+      end
+
+      private def extract_bubbles(transition)
         case transition.command
         when Command::Bubble # Sentinel; not a real Command to be handled by the runtime
           bubble_model, bubble_cmd = dispatch_outward(transition.command.message, transition.model)
-          transition = transition.with_model(bubble_model).with_command(bubble_cmd)
-        when Command::Batch
-          transition = extract_bubbles_from_batch(transition)
+          transition.with_model(bubble_model).with_command(bubble_cmd)
+        when Command::Batch, Separate
+          extract_bubbles_from_compound(transition)
+        else
+          transition
         end
-        transition = transition.with(command: nil) if transition.command.equal?(Flow::Outward::INTERCEPTED)
-        transition.to_a
       end
 
-      private def extract_bubbles_from_batch(transition)
+      private def extract_bubbles_from_compound(transition)
         bubbles, remaining = transition.command.extract_bubbles
         return transition if bubbles.empty?
 
@@ -39,7 +46,8 @@ module Rooibos
         bubbles.each do |bubble|
           model, cmd = dispatch_outward(bubble.message, result.model)
           result = Transition.new(model:, command: result.command)
-          result = result.with_added_command(cmd) unless cmd.nil? || cmd.equal?(Flow::Outward::INTERCEPTED)
+          result = result.with_added_command(bubble) if cmd.nil?
+          result = result.with_added_command(cmd) unless cmd.equal?(Flow::Outward::INTERCEPTED)
         end
         result
       end

data/lib/rooibos/router/rule/forward.rb

@@ -28,7 +28,8 @@ module Rooibos
 
       private def envelop(message)
         if envelope
-          Message::Routed.new(envelope:, event: message)
+          event = message.is_a?(Message::Routed) ? message.event : message
+          Message::Routed.new(envelope:, event:)
         else
           message
         end

data/lib/rooibos/router.rb

@@ -123,7 +123,7 @@ module Rooibos
       def from_router
         RouterUpdate.new(
           inward: Flow::Inward.new(observes:, receives:, forwards:, otherwises:, routes:),
-          outward: Flow::Outward.new(observes:, receives:, routes:)
+          outward: Flow::Outward.new(observes:, receives:, forwards:, routes:)
         )
       end
 
@@ -165,22 +165,6 @@ module Rooibos
         routes.add(Route.new(prefix: prefix&.to_s&.to_sym, fragment: to, read:, write:))
       end
 
-      # Forwards all instances of a class to routes.
-      #
-      # Matches messages by class. Ideal for custom message types or
-      # RatatuiRuby event classes like <tt>Event::Resize</tt>.
-      #
-      # Use <tt>broadcast: true</tt> to send to all declared routes, or
-      # <tt>broadcast_to:</tt> with an array of specific route targets.
-      #
-      # === Example
-      #
-      #   forward_instances_of RatatuiRuby::Event::Resize, to: :main_layout
-      #   forward_instances_of ThemeChanged, broadcast: true
-      def forward_instances_of(klass, ...)
-        forwards.add_instances_of(klass, ...)
-      end
-
       # Defines a named action referenceable by symbol.
       #
       # Actions are reusable handlers. Reference them by name in
@@ -314,6 +298,9 @@ module Rooibos
       # with a semantic envelope. This decouples keybindings from nested
       # fragment internals.
       #
+      # Use <tt>broadcast: true</tt> to send to all declared routes, or
+      # <tt>broadcast_to:</tt> with an array of specific route targets.
+      #
       # === Example
       #
       #   forward_events :enter, to: :active_form, as: :submit
@@ -322,6 +309,22 @@ module Rooibos
         forwards.add_events(keys, to:, **)
       end
 
+      # Forwards all instances of a class to routes.
+      #
+      # Matches messages by class. Ideal for custom message types or
+      # RatatuiRuby event classes like <tt>Event::Resize</tt>.
+      #
+      # Use <tt>broadcast: true</tt> to send to all declared routes, or
+      # <tt>broadcast_to:</tt> with an array of specific route targets.
+      #
+      # === Example
+      #
+      #   forward_instances_of RatatuiRuby::Event::Resize, to: :main_layout
+      #   forward_instances_of ThemeChanged, broadcast: true
+      def forward_instances_of(klass, to: @_scoped_target, **)
+        forwards.add_instances_of(klass, to:, **)
+      end
+
       # Routes matching routed messages to a declared route.
       #
       # Matches <tt>Message::Routed</tt> messages by envelope. Use this
@@ -332,6 +335,9 @@ module Rooibos
       # Each layer speaks its inner fragment's API without knowing what
       # lies deeper.
       #
+      # Use <tt>broadcast: true</tt> to send to all declared routes, or
+      # <tt>broadcast_to:</tt> with an array of specific route targets.
+      #
       # === Example
       #
       #   forward_routed :leaf_1, to: :top_leaf, as: :increment

data/lib/rooibos/runtime.rb

@@ -120,16 +120,18 @@ module Rooibos
     # [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.
+    # [update_every_frame] When +true+, <tt>Event::None</tt> (idle frame) events are passed to Update instead of being dropped. Use for animations, physics, or any per-frame state change. Default +false+.
     #
     # == Raises
     #
     # [Rooibos::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)
+    def self.run(root_fragment = nil, fps: 60, model: nil, view: nil, update: nil, command: nil, update_every_frame: false)
       @fragment = fragment_from_kwargs(root_fragment, model:, view:, update:, command:)
       @view = @fragment::View
       @update = @fragment::Update
       @init_callable = init_callable
       @timeout = 1.0 / fps
+      @update_every_frame = update_every_frame
 
       start_runtime
     end
@@ -310,7 +312,7 @@ module Rooibos
 
       private def handle_ratatui_event
         message = @tui.poll_event(timeout: @timeout)
-        return false if message.none?
+        return false if message.none? && !@update_every_frame
 
         # Handle sync events: wait for pending async work before continuing
         if message.sync?

data/lib/rooibos/shortcuts.rb

@@ -68,6 +68,14 @@ module Rooibos
       # Alias for +Message::Timer+.
       Timer = Message::Timer
 
+      # Clock message type.
+      # Alias for +Message::Clock+.
+      Clock = Message::Clock
+
+      # Random value message type.
+      # Alias for +Message::Random+.
+      Rand = Message::Random
+
       # HTTP response message type.
       # Alias for +Message::HttpResponse+.
       Http = Message::HttpResponse

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.7.2"
+  VERSION = "0.8.0"
 end

data/sig/rooibos/command.rbs

@@ -134,19 +134,72 @@ module Rooibos
   # Alias for wait, semantically used for recurring timers.
   def self.tick: (Float seconds, Symbol tag) -> Wait
 
+  # Methods expected from classes that include Timed.
+  interface _TimedBase
+    def seconds: () -> Float
+    def timed_response: (Time start_time) -> (Message::Timer | Message::Clock)
+  end
+
+  # Shared behavior for commands that wait, then respond.
+  module Timed : _TimedBase
+    # Cooperative cancellation needs no grace period.
+    def rooibos_cancellation_grace_period: () -> Integer
+
+    # Waits then sends the result of timed_response, or Message::Canceled.
+    def call: (Outlet out, Concurrent::Cancellation token) -> void
+  end
+
   # One-shot timer command that waits, then sends a message.
   class Wait < Data
     include Custom
+    include Timed
+
+    attr_reader seconds: Float
+    attr_reader envelope: Symbol
+
+    def self.new: (seconds: Float, envelope: Symbol) -> instance
+
+    private
+
+    # Builds the timer response with elapsed time.
+    def timed_response: (Time start_time) -> Message::Timer
+  end
+
+  # One-shot clock command that waits, then sends a message with wall-clock time.
+  class Clock < Data
+    include Custom
+    include Timed
 
     attr_reader seconds: Float
     attr_reader envelope: Symbol
 
     def self.new: (seconds: Float, envelope: Symbol) -> instance
 
-    # Execute the timer with cooperative cancellation.
+    private
+
+    # Builds the clock response with wall-clock time.
+    def timed_response: (Time start_time) -> Message::Clock
+  end
+
+  # Creates a wall-clock time command.
+  def self.clock: (Float seconds, Symbol envelope) -> Clock
+
+  # A command that generates a random value.
+  class Random < Data
+    include Custom
+
+    attr_reader args: Array[(Symbol | Integer | Float | Range[Integer] | Range[Float])]
+    attr_reader envelope: Symbol
+
+    def self.new: (args: Array[(Symbol | Integer | Float | Range[Integer] | Range[Float])], envelope: Symbol) -> instance
+
+    # Execute the random command.
     def call: (Outlet out, Concurrent::Cancellation token) -> void
   end
 
+  # Creates a random value command.
+  def self.random: (*(Symbol | Integer | Float | Range[Integer] | Range[Float])) -> Random
+
   # Private wrapper for Command.custom.
   class Wrapped < Data
     include Custom

data/sig/rooibos/message.rbs

@@ -89,6 +89,28 @@ module Rooibos
     def deconstruct_keys: (Array[Symbol]? keys) -> Hash[Symbol, untyped]
   end
 
+  # Response from a clock command.
+  class Clock < Data
+    include Predicates
+    attr_reader envelope: Symbol
+    attr_reader time: Time
+
+    def self.new: (envelope: Symbol, time: Time) -> instance
+
+    def clock?: () -> bool
+  end
+
+  # Response from a random command.
+  class Random < Data
+    include Predicates
+    attr_reader envelope: Symbol
+    attr_reader value: (Integer | Float | String)
+
+    def self.new: (envelope: Symbol, value: (Integer | Float | String)) -> instance
+
+    def random?: () -> bool
+  end
+
   # Response from an HTTP command.
   class HttpResponse
     include Predicates

data/sig/rooibos/router/forwards.rbs

@@ -17,13 +17,13 @@ module Rooibos
       def add_instances_of: (Class klass, ?to: route_target?, ?as: Symbol?, ?broadcast: bool, ?broadcast_to: Array[route_target]?) -> void
 
       # Adds a forward rule matching key events.
-      def add_events: (Symbol | Array[Symbol] keys, ?to: route_target?, ?as: Symbol?, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
+      def add_events: (Symbol | Array[Symbol] keys, ?to: route_target?, ?as: Symbol?, ?broadcast: bool, ?broadcast_to: Array[route_target]?, ?guard: guard?, ?when: guard?, ?unless: guard?) -> void
 
       # Adds a forward rule matching routed messages by envelope.
-      def add_routed: (Symbol | Array[Symbol] envelopes, ?to: route_target?, ?as: Symbol?) -> void
+      def add_routed: (Symbol | Array[Symbol] envelopes, ?to: route_target?, ?as: Symbol?, ?broadcast: bool, ?broadcast_to: Array[route_target]?) -> void
 
       # Adds a forward rule matching a custom predicate.
-      def add_custom: (guard predicate, ?to: route_target?, ?as: Symbol?) -> void
+      def add_custom: (guard predicate, ?to: route_target?, ?as: Symbol?, ?broadcast: bool, ?broadcast_to: Array[route_target]?) -> void
 
       private
 

data/sig/rooibos/runtime.rbs

@@ -30,7 +30,8 @@ module Rooibos
   # Starts the MVU event loop (positional fragment).
   def self.run: [Model] (
     ?Module? root_fragment,
-    ?fps: Integer
+    ?fps: Integer,
+    ?update_every_frame: bool
   ) -> Model
 
   # Starts the MVU event loop (explicit parameters).
@@ -40,7 +41,8 @@ module Rooibos
     model: Model,
     view: ^(Model, RatatuiRuby::TUI) -> renderable,
     update: ^(RatatuiRuby::Event, Model) -> update_result?,
-    ?command: Command::execution?
+    ?command: Command::execution?,
+    ?update_every_frame: bool
   ) -> Model
 
   # Starts the MVU event loop (explicit parameters without fps).
@@ -49,7 +51,8 @@ module Rooibos
     model: Model,
     view: ^(Model, RatatuiRuby::TUI) -> renderable,
     update: ^(RatatuiRuby::Event, Model) -> update_result?,
-    ?command: Command::execution?
+    ?command: Command::execution?,
+    ?update_every_frame: bool
   ) -> Model
 
   # Normalizes Init callable return value to [model, command] tuple.

data/sig/rooibos/shortcuts.rbs

@@ -16,6 +16,8 @@ module Rooibos
   # Short aliases for Message types.
   module Msg
     Timer: singleton(Message::Timer)
+    Clock: singleton(Message::Clock)
+    Rand: singleton(Message::Random)
     Http: singleton(Message::HttpResponse)
 
     module Sh

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rooibos
 version: !ruby/object:Gem::Version
-  version: 0.7.2
+  version: 0.8.0
 platform: ruby
 authors:
 - Kerrick Long
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.4'
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement
@@ -306,12 +306,15 @@ files:
 - lib/rooibos/command/all.rb
 - lib/rooibos/command/batch.rb
 - lib/rooibos/command/bubble.rb
+- lib/rooibos/command/clock.rb
 - lib/rooibos/command/custom.rb
 - lib/rooibos/command/deliver.rb
 - lib/rooibos/command/http.rb
 - lib/rooibos/command/lifecycle.rb
 - lib/rooibos/command/open.rb
 - lib/rooibos/command/outlet.rb
+- lib/rooibos/command/random.rb
+- lib/rooibos/command/timed.rb
 - lib/rooibos/command/wait.rb
 - lib/rooibos/configuration.rb
 - lib/rooibos/error.rb
@@ -320,9 +323,11 @@ files:
 - lib/rooibos/message/batch.rb
 - lib/rooibos/message/bubbled.rb
 - lib/rooibos/message/canceled.rb
+- lib/rooibos/message/clock.rb
 - lib/rooibos/message/error.rb
 - lib/rooibos/message/http_response.rb
 - lib/rooibos/message/open.rb
+- lib/rooibos/message/random.rb
 - lib/rooibos/message/routed.rb
 - lib/rooibos/message/system/batch.rb
 - lib/rooibos/message/system/stream.rb
@@ -412,7 +417,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.9
+      version: 3.3.11
   - - "<"
     - !ruby/object:Gem::Version
       version: '5'
@@ -422,7 +427,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: "☕ Confidently Build Terminal Apps"
 test_files: []